Deploy to a Windows IIS server

Everything Monopam can do with an IIS server: import a managed certificate into the machine store, point one HTTPS binding at it, and confirm the result by reading the thumbprint back out of the server rather than from an API's answer. Through the agent on the server, or, where there is none, over WinRM from a Windows gateway.

Before you start

You need four things:

Where the certificate actually lands

This is the part worth reading before the first deployment, because it explains nearly every surprise an IIS certificate can produce. A binding on an IIS site does not hold a certificate. It holds a reference, and the certificate itself is registered in http.sys, the kernel component that owns the port. Those are two separate pieces of state, kept in two separate places, and they are keyed differently.

IIS site "Default Web Site"
  binding  *:443:shop.monofor.com      <- applicationHost.config
                 |
                 |  the port and the host, not the certificate
                 v
http.sys
  hostnameport=shop.monofor.com:443  ->  hash  ->  LocalMachine\My
  ipport=0.0.0.0:443                 ->  hash  ->  LocalMachine\My

A deployment therefore does three things in order, and all three have to succeed:

1. Import the PFX into LocalMachine\My (or the store named on the target).
2. Create the HTTPS binding on the site if it is not there yet, with SNI switched on when the target names a host.
3. Register the certificate in http.sys under the binding's key, then read it back.

The key is what separates one site's certificate from another's on the same port:

One port, several sites

Several HTTPS sites on one address and one port is ordinary, and it works because each named host gets its own entry in http.sys. The rules that follow from the table above:

• Two sites on the same port need different host headers. Give each target the host it answers for, and each keeps its own certificate.
• A catch-all and a named host can share a port. The binding without a host header is stored under ipport= and is not disturbed by a hostnameport= entry on the same port, nor the other way round.
• Two bindings on one port with no host header are the same slot. Whichever was deployed last wins, and the other site quietly starts serving it. Separate them by host header or by IP.

This was measured rather than assumed. On one lab server, seven bindings across five sites, each with its own certificate:

Sites c and d shared port 8500 and kept a certificate each. Site f's host-scoped binding on 8443 left site a's catch-all on the same port alone. The server's other bindings, which Monopam had never been told about, were unchanged throughout.

Create the deployment target

On the certificate, open the Deployment tab and press Add Target. Pick server type Windows / IIS.

Figure 1. A Windows / IIS target. The certificate's Deployment tab, then Add Target.

With an agent, or without one

The same work reaches the server two ways. The script is identical: it uses appcmd.exe and netsh.exe, which are present on every IIS host, rather than a PowerShell module, so it carries no assumption about the shell it lands in. What differs is the prerequisites, and a successful run says which route carried it.

Prefer the agent. The WinRM route exists for servers that cannot take one.

Deploy

Press Deploy on the target. There is no service interruption: nothing is stopped, recycled or restarted, and the binding is repointed in place. A successful run reads:

Deployed to IIS on 'Default Web Site' (*:443, host shop.monofor.com).
The binding now serves 68B29208A0554529164E6CA42EEFAE94F382EB24.

Check it from the server

On the server, ask http.sys directly. Use the key that matches the binding:

netsh http show sslcert hostnameport=shop.monofor.com:443
netsh http show sslcert ipport=0.0.0.0:443

The Certificate Hash in the output is the thumbprint the run reported. From outside the server, a browser or openssl s_client -servername shop.monofor.com -connect shop.monofor.com:443 shows the same certificate.

Renewal

Automatically deploy when the certificate renews is safe to leave on for this target type. Nothing restarts, and the binding is repointed in place, so a renewal is as quiet as the first deployment. Each target follows its own binding, so a certificate with several IIS targets renews onto all of them.

Undo

Every deployment records what the binding held before it ran. From the deployment's history:

• Restore previous certificate puts the binding back on the certificate it served before. The run reports '<site>' bound back to the certificate it served before.
• Remove what was deployed takes back what this deployment created, for a binding that did not exist before it.

The displaced certificate is left in the machine store, because another site may be using it. Remove it by hand only when you know nothing else serves it.

If something goes wrong

What Monopam does not do here

• It does not create or start the IIS site.
• It does not touch any binding other than the one the target names, including other bindings on the same port.
• It does not remove the displaced certificate from the machine store.
• It does not configure a web farm or shared configuration. Each server is its own target.
• It does not deploy to Windows services other than IIS. For files plus a command of your own, use the Windows / generic target type.