MDriven Server and MDriven Turnkey should be reached over https. This page explains which certificate to use on IIS, how to bind it, and how to find certificate problems. It applies to both the .NET Core and the .NET Framework builds.
Why the certificate matters more than usual
MDriven Server calls itself – and Turnkey calls MDriven Server – at the address they have been given. That call is made from the server itself, so:
- the certificate must be valid for exactly that address (the host name in the certificate must match the URL), and
- the certificate must be trusted by the server itself, not only by your browser.
If either is wrong, MDriven Server cannot talk to itself and may not start, even though the browser on your own machine accepts the page. A certificate warning that you click past in the browser is therefore not something you can ignore.
Choose a certificate
| Certificate | Use for | Notes |
|---|---|---|
| From your organisation's certificate authority, or a commercial one | Production | Usually already trusted on domain-joined servers. |
| Let's Encrypt | Production on a public address | Free, renewed automatically. On IIS, a client such as win-acme requests the certificate, binds it in IIS and renews it. |
| Self-signed | Test and development only | Must be added to the server's trusted root store (see below), and to the browsers that use it. |
On Azure App Service, certificates are handled by Azure – see Install on Azure.
Bind the certificate in IIS
- Install the certificate in the computer's Personal store (Cert:\LocalMachine\My), with its private key.
- In IIS Manager, select the site → Bindings → Add: type https, port 443, the host name, and the certificate. Select Require Server Name Indication when several sites share the IP address.
- Use the same host name everywhere: in the browser, in
App_Data/CommandLineOverride.xml(iis=https://…, .NET Core builds), and in Turnkey'sMDrivenServerOverride.xmlif you use one.
The MDriven Installation Scripts find the certificate by its friendly name when they create a site, so give the certificate a friendly name when you install it.
A self-signed certificate for testing
In IIS Manager → Server Certificates → Create Self-Signed Certificate, or with PowerShell (as administrator):
# Create the certificate for the server's full name
$cert = New-SelfSignedCertificate -DnsName "appserver01.example.local" -CertStoreLocation Cert:\LocalMachine\My -FriendlyName "MDriven test"
# Trust it on the server itself (copy it to Trusted Root Certification Authorities)
Export-Certificate -Cert $cert -FilePath "$env:TEMP\mdriven-test.cer" | Out-Null
Import-Certificate -FilePath "$env:TEMP\mdriven-test.cer" -CertStoreLocation Cert:\LocalMachine\Root | Out-Null
Then bind it as above and browse to https://appserver01.example.local/ – the name in the certificate, not localhost.
Behind a load balancer or reverse proxy
When https ends at a load balancer or proxy in front of IIS, the applications may be reached on a private address behind it. Give each application the address it is reached on from the server, and tell it its public address with HardServerUrl.xml – see also Load balancing.
Finding certificate problems
- Does the address match the certificate? Open the address that MDriven Server uses (from
CommandLineOverride.xmlor the IIS binding) in a browser on the server itself. Any certificate warning there is a problem for MDriven too. - Is the certificate trusted on the server? A self-signed certificate must be in Trusted Root Certification Authorities of the local computer.
- Has it expired? Check the expiry date, and that automatic renewal (for example win-acme's scheduled task) works.
- Is the right certificate bound? Check the site's https binding in IIS Manager.
- Still unsure? Try another browser, and read the server's log – see Logs.