Is this relevant to me?

If you look after a SharePoint environment that relies on ADFS 2.0 for authentication, then this post is relevant to you. By default, the ADFS token signing certificate is configured to expire 1 year after ADFS is first installed. When that happens, the new certificate needs to be re-imported in to SharePoint’s trusted identity provider, and be trusted by SharePoint. If these steps are not followed, all Web application zones that rely on ADFS for authentication will be unavailable. If your ADFS token signing certificate has already expired, then SharePoint is most likely unavailable and you will most likely find the following error in the event log on your SharePoint server(s):

If you aren’t sure whether a SharePoint Web application is using ADFS, here is an example of the “Authentication Providers” screen within SharePoint Central Administration, for a SP2010 Web App relying on ADFS. The fact that the “Trusted Identity Provider” box is checked is a pretty strong indication that ADFS is in use. Note that your provider is unlikely to be called “ADFSv2”, as the name is configured at the point of creation:

If you have access to the ADFS server, you can view certificate expiry dates under ADFS 2.0 > Service > Certificates:

What is an ADFS token signing certificate, and why would it expire?

Technet concisely  of the ADFS token signing certificate:

“Federation servers require token-signing certificates to prevent attackers from altering or counterfeiting security tokens in an attempt to gain unauthorized access to federated resources…The Web server in the resource partner uses the public key of the token-signing certificate to verify that the security token is signed by the resource federation server.”

My interpretation of this is that by importing the ADFS token signing certificate, SharePoint (the Web server) is able to verity that the certificates are signed by ADFS (the resource federation server).

As for “why would it expire”, common security guidelines for certificate management state that the shorter the lifetime of a certificate, the more frequently the identity of the signer is verified. To me, a year of validity seems to be a fairly sensible duration for a production deployment, but this duration may not be appropriate for less critical systems such as development and test environments.

Note that in a default configuration, expired certificates are automatically replaced by ADFS, due to usage of a feature known as auto-certificate rollover. The problem here is that relying parties (such as SharePoint) need to be made aware of the new token-signing certificate.

How do I renew the token-signing certificate in SharePoint?

There are two steps required to renew the certificate (at least as far as SharePoint is concerned – this assumes that the new ADFS token signing cert has already been generated):

1. Import certificate into SharePoint’s trusted certificate store (SharePoint Central Admin or PowerShell)
2. Import certificate into SharePoint’s trusted identity provider (PowerShell)

The PowerShell required to perform the above steps forms part of the overall process followed to , so if you have configured SharePoint for ADFS before this is nothing new. This script needs to be run on a SharePoint server:

Note that it doesn’t appear to be necessary to remove the previously used certificate (SPTrustedRootAuthority), and Set-SPTrustedIdentityTokenIssuer overwrites the previous token signing certificate. Additionally, an IISReset was not necessary when testing in my environment.

I don’t want to do this every year. How do I stop the certificate from expiring?

At Content and Code, we have a lot of development VMs that rely on ADFS. In this scenario, it’s quite possible that ADFS token signing certificates should never expire, as the security risk is minimal or non-existent. ADFS has the capability to generate its own certificates (in which case you should follow the steps below), or you could import a certificate generated externally (for example, you might decide to issue a new certificate using a certificate authority within the domain). If you decide to generate a certificate outside of ADFS, you may want to review the 

Assuming that you are using ADFS to generate the new token signing certificate, you can use the Set-ADFSProperties cmdlet to modify the CertificateDuration property, then create a new token signing certificate. In the example below, new certificates won’t expire for 36500 days (100 years):

Note that this needs to be run on the ADFS server. If you aren’t familiar with using the ADFS PowerShell cmdlets, I suggest running “Windows PowerShell Modules” as administrator to get started:

If you are the cautious type, you can run Get-ADFSProperties to check the current certificate duration before changing it. You will probably find that you ADFS server is set to the default value of 365 days, but in this case I have already changed the value to 36500 using the script above:

We can now create a new Token Signing certificate that will be valid for the new duration:

By including the –Urgent parameter, we are triggering immediate certificate rollover, meaning that any reliant parties will need to be updated with the new certificate before authentication via ADFS can occur. In other words, the cmdlet above will break authentication for all SharePoint Web Application zones using ADFS until we have imported the new certificate. Remember, this needs to be run on the ADFS server.

Having completed this step, you should now find that the token signing certificate within ADFS is valid for 100 years:

Optionally, you may wish to disable auto-certificate rollover completely in your development environments. This PowerShell script will do just that:

Obviously having done this, you will have to renew your ADFS certificate manually.

What about the other ADFS certificates?

You might have noticed that there are three types of ADFS certificate presented in the ADFS 2.0 UI:

I haven’t had a chance to investigate how the Service communications and Token-decrypting certificate are used in the context of SharePoint. For what it’s worth, I did  in my environment and did not notice any obvious availability problems within SharePoint. I do however advise treading very carefully, especially given the heavy reliance that SharePoint places on the token-signing certificate.

Perhaps the other ADFS certificates will be the topic of another blog post. Thanks for reading!

Ben