Managing and troubleshooting AD FS certificates

AD FS has several different certificate types that is uses for various operations:

• SSL. This is a standard SSL certificate that is used for securing communications between federation servers and clients.
• Token signing. This is a standard X509 certificate that is used for securely signing all tokens that the federation server issues.
• Token decrypting. This is a standard X509 certificate that is used to decrypt/encrypt any incoming requests. It is also published in federation metadata.
• Service Communications. This certificate enables WCF message security for securing communications between federation servers.

You can also read additional information on certificate requirements here.

What are you trying to do with your certificates?

Which type of certificate are you trying to update? Keep in mind that most deployments use the same certificate for SSL and service communications. So if you’re planning to update one, you’ll most likely need to update both.

You will need to create a new SSL certificate that will replace the existing one. There are several requirements for this certificate and it is critical that they are met. View the certificate requirements here.

Once you have a new SSL certificate, go ahead and continue to the next step.

We recommend that you use Azure AD Connect for SSL certificate management. This wizard provides a step-by-step guide for deploying a new certificate to all of your AD FS and WAP servers. And this functionality is available even if your specified sign-in method is not federation with AD FS.

We have a step-by-step document that walks you through the whole process, including screenshots of the different wizard pages. You can find the wizard guide here.

The process to update the SSL certificate for your AD FS farm is slightly different depending on the version that you have installed.

In order to update the SSL certificate using PowerShell, you will be running a series of operations on every server in your farm. It will be easier to open a remote session to all servers and do them at the same time. You will need to be logged in with an administrator account.

First you must import the certificate into the Local Machine store on all AD FS servers in the farm. Once the certificate is imported, you also must grant the AD FS service account Read permissions to the private key. This can be done using the Certificates MMC snap-in: right-click the new certificate, All Tasks, and then Manage Private Keys.

After you’ve finished importing the certificate on all servers, you’re ready to change the certificate in PowerShell. To do this, you’ll need to run the following PowerShell cmdlet on each server.

Set-AdfsSslCertificate -Thumbprint [thumbprint]

For additional information, please refer to our online documentation here.

Before you update the SSL certificate using PowerShell, you first must import the certificate into the Local Machine store on all AD FS servers in the farm. Once the certificate is imported, you also must grant the AD FS service account Read permissions to the private key. This can be done using the Certificates MMC snap-in: right-click the new certificate, All Tasks, and then Manage Private Keys.

After you’ve finished importing the certificate, you’re ready to change the certificate in PowerShell. To do this, you’ll need to log into the primary AD FS node in your farm with an account that has permissions to make configuration changes. The PowerShell cmdlet that is executed is multi-node, so you only have to make this change in one place.

If you are using default certificate authentication, execute the following:

Set-AdfsSslCertificate -Thumbprint [thumbprint]

If you are using alternate TLS binding, execute the following:

Set-AdfsAlternateTlsClientBinding -Thumbprint [thumbprint]

For additional information, please refer to our online documentation here.

In some environments, custom bindings may have been deployed using the existing certificate (for example: 0.0.0.0). If you have custom bindings, you’ll need to replace them as well. You can check for custom bindings using netsh.exe.

netsh.exe http show ssl

Look for any bindings using the old SSL certificate and update them to the new certificate. This will have to be performed on every server in the farm. Note that you can’t update an existing binding; you must delete the binding and then create a new one. And it is important that you set the CTL store and application ID correctly (these values are the same for all deployments).

Here is an example of removing a custom binding for localhost on port 443 and replacing it with a new one.

Remove an existing binding for localhost on port 443

netsh.exe http delete sslcert hostnameport=localhost:443

Add a new binding for localhost on port 443

netsh.exe http add sslcert hostnameport=localhost:443 certhash=[thumbprint] appid={5d89a20c-beab-4389-9447-324788eb944a} certstorename=MY sslctlstorename=AdfsTrustedDevices

There is no PowerShell cmdlet that replaces the SSL certificates across the entire WAP farm. So you’ll need to perform these operations on all WAP servers.

First, you’ll need to import the SSL certificate into the Local Machine store.

Next, update the certificate using the following cmdlet.

Set-WebApplicationProxySslCertificate [thumbprint]

In some environments, custom bindings may have been deployed using the existing certificate (for example: 0.0.0.0). If you have custom bindings, you’ll need to replace them as well. This can be done using netsh.exe. Note that you can’t update an existing binding; you must delete the binding and then create a new one.

netsh.exe http show ssl

Look for any bindings using the old SSL certificate and update them to the new certificate.

For additional information, please refer to our online documentation here.

The SSL certificate is typically the same as your service communications certificate. In fact, this is the default configuration. So there’s a very good chance that you also need to update this certificate.

Do you have automatic certificate rollover enabled? You can find out by logging into a primary AD FS server and running the following cmdlet:

(Get-AdfsProperties).AutoCertificateRollover

If you are using self-signed certificates and do not have automatic certificate rollover, we recommend that you do so. This way you won’t need to manually update certificates moving forward. You can find more information about automatic certificate rollover here.

Since you have automatic certificate rollover enabled, you don’t need to manually update your certificates.

You will need to create a new certificate that will replace the existing one. There are several requirements for this certificate and it is critical that they are met. View the certificate requirements here.

Next, you need to import the new certificate into the Local Machine store on all AD FS servers in the farm. Once the certificate is imported, you also must grant the AD FS service account Read permissions to the private key. This can be done using the Certificates MMC snap-in: right-click the new certificate, All Tasks, and then Manage Private Keys.

Next, add the new certificate as a secondary in the AD FS farm. To do this, launch the AD FS Management console and locate the Certificates node under Service. In the right-hand pane, there are options to add a new certificate. Select the link based on which certificate you want to add.

Now that the certificate has been deployed, it will be available to partners through the metadata. However, some applications may not automatically consume the new certificate from the metadata and you’ll need to manually provide them with the certificate.

After all partners have been updated to use the new certificate, you need to promote it to the primary certificate. This is also done using the AD FS Management console on the Certificates node under Service. In the right-hand pane, there is an option entitled "Set as Primary".

You can find more information about updating certificates here.

You will need to create a new certificate that will replace the existing one. It is recommended that you use the SSL certificate for service communications. There are several requirements for this certificate and it is critical that they are met. View the certificate requirements here.

Next, you need to import the new certificate into the Local Machine store on all AD FS servers in the farm. Once the certificate is imported, you also must grant the AD FS service account Read permissions to the private key. This can be done using the Certificates MMC snap-in: right-click the new certificate, All Tasks, and then Manage Private Keys.

Now you need to update AD FS to use the new certificate. To do this, launch the AD FS Management console and locate the Certificates node under Service. In the right-hand pane, there is an option to "Set Service Communications Certificate". Click this link and then select the new certificate.

The best way to troubleshoot problems with your existing certificates is to use the Diagnostics Analyzer on AD FS Help. This tool runs a comprehensive set of diagnostics against your servers, including certificates. Any issues will be surfaced as warnings or errors.

Some of the common issues are:

• Expired certificate
• Revoked certificate
• CRL reachable and therefore revocation status cannot be confirmed
• AD FS service account does not have Read permissions
• SSL certificate have multiple bindings to the same port

Now that you’ve made changes to your certificates, we should confirm that everything is working as expected. The best way to confirm the health of your service is to use the Diagnostics Analyzer on AD FS Help. This tool runs a comprehensive set of diagnostics against your servers, including certificates and synthetic transactions. Any issues will be surfaced as warnings or errors.

Finally, access one of your federated applications to make sure things work as expected.

We are sorry that the problem persists. We'd appreciate it if you can provide feedback with details of your issue so that we can improve the troubleshooting workflows.

Congratulations! Your issue has been solved.