How to Update Certificates for AD FS 3.0
Active Directory Federation Services (AD FS) 3.0 is a server role included in Windows Server 2012 R2.
Certificates play the most critical role in securing communications between federation servers, Web Application Proxies, federation server proxies, the cloud service, and web clients. The requirements for certificates vary, depending on whether you are setting up a federation server,a Web Application Proxy, or federation server proxy computer, as described in the following tables.
Federation servers require the certificates in the following table.
|Certificate type||Description||What you need to know before deploying|
|SSL certificate (also referred to as a Server Authentication Certificate) for AD FS in Windows Server 2012 R2||This is a standard Secure Sockets Layer (SSL) certificate that is used for securing communications between federation servers, clients, Web Application Proxy, and federation server proxy computers.||AD FS requires a certificate for SSL server authentication on each federation server in your federation server farm. The same certificate should be used on each federation server in a farm. You must have both the certificate and its private key available. For example, if you have the certificate and its private key in a .pfx file, you will be able import the file directly into the Active Directory Federation Services Configuration Wizard. This SSL certificate must contain the following:
|SSL certificate (also referred to as a Server Authentication Certificate) for legacy versions of AD FS||This is a standard Secure Sockets Layercertificate that is used for securing communications between federation servers, clients, Web Application Proxy, and federation server proxy computers.||AD FS requires an SSL certificate when configuring federation server settings. By default, AD FS uses the SSL certificate configured for the Default Web Site in Internet Information Services (IIS).
The Subject name of this SSL certificate is used to determine the Federation Service name for each instance of AD FS that you deploy. For this reason, you may want to consider choosing a Subject name on any new certification authority (CA)-issued certificates that best represents the name of your company or organization to the cloud service and this name must be Internet-routable. For example, in the diagram provided earlier in this article (see “Phase 2”), the subject name of the certificate would be fs.fabrikam.com.
Required: Because this certificate must be trusted by clients of AD FS and Microsoft cloud services, use an SSL certificate that is issued by a public (third-party) CA or by a CA that is subordinate to a publicly trusted root; for example, VeriSign or Thawte.
|Token-signing certificate||This is a standard X.509 certificate that is used for securely signing all tokens that the federation server issues and that the cloud service will accept and validate.||The token-signing certificate must contain a private key, and it should chain to a trusted root in the Federation Service. By default, AD FS creates a self-signed certificate. However, depending on the needs of your organization, you can change this later to a CA-issued certificate by using the AD FS Management snap-in.
Recommendation: Use the self-signed token-signing certificate generated by AD FS. By doing so, AD FS will manage this certificate for you by default. For example, in case this certificate is expiring, AD FS will generate a new self-signed certificate to use ahead of time.
Replacing the Service Communications Certificate
Normally the Service Communications certificate comes from a trusted third-party CA, like DigiCert or Verisign. This is a traditional SSL cert like you would use in IIS for any secure web server. You may use a ingle-name, subject alternative name (SAN), or wildcard cert for this purpose s long as it's valid and trusted by internal and exernal AD FS clients.
If you have more than one AD FS server in your environment you will run the following procedures from the primary AD FS server. The changes will replicate to all other AD FS servers in the farm.
- Request and install a new SSL certificate from a trusted third-party CA. Install this cert and private key in the local computer's Personal store on all AD FS servers in the farm.
- Logon to the primary AD FS server and open an elevated PowerShell prompt to run the following commands:
- Copy the thumbprint for the new SSL certificate you wish to use, then run:
Set-AdfsCertificate -CertificateType Service-Communications -Thumbprint thumbprint
Set-AdfsSslCertificate -Thumbprint thumbprint
If you receive any errors from this cmdlet you either haven't installed the new SSL certificate on all AD FS servers in the farm or you haven't installed the private key for the cert.
Replacing the Service Communications Certificate on WAP Servers
If your organization uses Web Application Proxy (WAP) servers for your AD FS deployment, you'll want to update them with the same SSL certificate.
- Install the new SSL certificate and private key in the local computer's Personal store on all WAP servers used by AD FS in your environment.
- Run the following to get the new certificate's thumbprint:
- Copy the thumbprint and run:
Set-WebApplicationProxySslCertificate -Thumbprint thumbprint
Repeat for each WAP server.
- Tip:Use the DigiCert SSL Installation Diagnostics Tool to confirm that the certificate and all intermediate certs are installed correctly, This tool works with any third-party CA certificate, not just DigiCert's.
Replacing the Token-Signing and Token-Decrypting Certificate
The Token-Signing and Token-Decrypting certificates are normally self-signed certificates good for one year, dated from the time the primary AD FS server was installed. The Office 365 portal will warn you when these certs are about to expire and that user access to all Office 365 services will fail.
By default, Token-Signing and Token-Decrypting Certificates will expire one year after your ADFS was setup. Near to the expiration period you will get the following notification on your Portal Admin Page.
This notification does not apply to SSL Certificate, also known as Service Communications Certificate.
The number of days represents the day where the service will stop. Due to certificate change.
How to calculate the effective day:
The new Certificate will be generated 20 days before the certificate expirations date:
1) Go to Powershell
4) Check [CertificateGenerationThreshold: 20]
The new certificate will be promoted to Primary after 5 days:
1) Go to Powershell
4) Check [CertificatePromotionThreshold: 5]
Knowing that AD FS Service only uses the primary certificate, as we will switch the certificates 15 days before the current primary certificates expires the service will stop 15 days before the current certificate expiration.
This is not true if the Relying party has been updated on the 5 days that exist between the new certificate creation and the promotion.
Certificate expires on 30-01-2014.
New certificate will be created on 10-01-1014 and will be marked as Secondary [20 days before expiration].
On the 15-01-2014 the Secondary Certificate is promoted to Primary [5 days after new certificate generation].
If we see the message on the portal on the day 05-01-2014 this should be informing that the service will stop in 10 days, if federation metadata information is not updated.
ADFS default configuration:
Default configuration on AD FS regarding Token Signing and Token Decrypting certificates includes an auto-renewal process, [AutoCertificateRollover].
If you did not change this value from “True” to “False”, no renewal operation regarding token certificates is needed, this will happen automatically based on triggers explained below.
Default values of ADFS - [see details below for default values]:
The Rollover interval is checked by the AD FS service every 720 minutes (12 hours).
If the existing primary certificate (Token Signing or Token Decryption) expiration time is within the window of the CertificateGenerationThreshold value (20 days), then a new certificate is generated and configured as the secondary certificate.
Noted by event ID 335 in the event logs: It will remain as the secondary certificate until the CertificatePromotionThreshold value is observed (5 days). So, 5 days after creation of the certificate, it will be promoted and the existing primary will be configured as the secondary until the next CertificateGenerationThreshold window is observed.
Once the Promotion event has occurred, the Token Service will sign/encrypt all issued tokens with the new primary certificate.
This does not cause a service outage of AD FS 2.0, but an application issue when the token is received and signed with something other than the expected certificate. This is true for O365 or any other application.
With AutoCertificateRollover enabled, AD FS 2.0 will continue to function as expected.
Validate your ADFS configuration:
To validate your configuration, connect to your primary ADFS Server and follow these PowerShell instructions:
Open the Windows PowerShell
CertificateCriticalThreshold: 2 - Days prior to expiry of the certificate before a new certificate is generated and promoted if AutoCertificateRollover has not performed naturally.
CertificateDuration: 365 - Validity period of the auto-generated Certificate.
CertificateGenerationThreshold: 20 - Days before expiration of current primary a new certificate will be generated.
CertficatePromotionThreshold: 5 - Days the newly generated certificate will exist before being promoted from secondary to primary.
CertificateRolloverInterval: 720 - Interval in minutes at which we check to see if a new certificate needs to be generated.
CertificateThresholdMulitplier: 1440 - Number of minutes used in calculation of other threshold counters (default value is 1440 minutes or 24 hrs. X 60 minutes, which makes threshold values equal to full days).
To have single sign on with ADFS the federation certificates need to be updated with the online platform. O365 is now automatically pulling the certificates from the AD FS server via the public metadata endpoint on a regular basis.
You may need to manually update the federation metadata using the PowerShell in complement to the Microsoft pull mechanism, as this will not pull the certificates on all scenarios.
To setup this to run automatically on your infrastructure implement the following script:
How to Enable and Immediately Use AutoCertificateRollover
If you have turned off AutoCertificateRollover in the past and you want to turn it back on, there are a few things you need to consider
- Simply turning AutoCertificateRollover back on via PowerShell will not immediately cause the self-signed certificates to be generated
- The self-signed certificates will only be generated once the critical threshold (close to expiration) of your existing certificates has been met
- There is a way to immediately cause the self-signed certificates to be generated, but this will cause service outage with your partners until they have refreshed from your federation metadata. We recommend causing the certificate generation after hours to avoid an outage.Alternatively, you could work closely with your partners to ensure that they are ready to immediately update via federation metadata (causing a short outage).
if you decide to let the existing certificates hit the critical threshold instead of invoking the certificate generation process, then you only need to re-enable AutoCertificateRollover.
If you decide that you want to immediately generate new self-signed certificates, then you need to first re-enable AutoCertificateRollover and then issue a PowerShell command to invoke immediate certificate generation.
PowerShell command to re-enable
Set-ADFSProperties -AutoCertificateRollover $true
PowerShell command to immediately generate new self-signed certificates:
NOTE: Be aware that there is an AD FS service outage incurred when the Token-Decrypting or Token-Signing certificates are updated because the relaying parties must update their configuration to expect the new certs. Do this work when users are least impacted by the outage.
Before you renew the Token-Signing and Token-Decrypting certificates I recommend that you increase the AD FS certificate lifetime for self-signed certs.
- Logon to the primary AD FS server and open an elevated PowerShell prompt. Run the following to configure the AD FS server to generate self-sign Token-Signing and Token-Decrypting certificates that last 10 years and enable Auto Certificate Rollover:
Set-ADFSProperties CertificateDuration 3650 -AutoCertificateRollover $true
- These cmdlets will generate new self-signed Token-Signing and Token-Decrypting certificates which will be promoted immediately and then disable auto certificate rollover again. Relay partners will need to update their metadata to accept the new signed claims:
Update-AdfsCertificate -CertificateType Token-Decrypting -Urgent
Update-AdfsCertificate -CertificateType Token-Signing -Urgent
Set-ADFSProperties -AutoCertificateRollover $false
- Update the Office 365 metadata using Windows Azure PowerShell:
Update-MsolFederatedDomain -DomainName domain.com -SupportMultipleDomain
- Remember that you'll need to update other relaying party metadata, if you use them. For example, Yammer on-prem (not Office 365) must be updated manually by Microsoft by opening a support ticket in the Office 365 portal. You will need to supply them with the Token-Signing and Token-Decrypting certificates (minus the private keys).
A Note About WAP Servers
If your organization uses Windows Application Proxy (WAP) servers for your AD FS deployment, there's nothing else you need to do regarding Token-Signing and Token-Decrypting certificates. WAP servers only use the Service Communications SSL cert.