Office 365 AD FS Token Signing Certificates Rollover & Trust Properties
Active Directory Federation Services – Token Signing Certificates still continues to be something that catches out a lot of people, especially in the Office 365 space. The aim of me writing this article to explain how the token signing certificate configuration works and furthermore what you should do in order to deal with this scenario and what you should be careful off before making any changes to prevent you from locking yourself out of your Office 365 Tenant.
For those of you who have been using federated identity for more than 12 months you have possibly seen this alert before, but for those of you who haven’t when your token-signing certificates expire within 30 days administrators will start to see the following alert appear in the portal. {you will also be e-mailed)
If you keep the default configuration below on your AD FS servers then the day that is referred to in the alert will always be 15 days prior to when the certificate actually expires, and the reason for this is 20 DAYS prior to the token-signing certificate expiring new token-signing/decrypting certificates are generated, and then 5 days after they have been generated the federation service will promote the new certificates to be the primary.
If the trust properties on the Office 365 side are not updated at this point then this will result in loss of access for your users and so therefore it is important that you either
1) ensure that your federation metadata is accessible externally & the following check-box is checked within the relying party configuration.
2) you manually update the federation trust by running Update-MsolFederatedDomain*
* you need to ensure that you login with your office 365 global admin account that uses a managed domain namespace, for example: onmicrosoft.com
- script to automatically update office 365 federation metadata can be found here: https://gallery.technet.microsoft.com/scriptcenter/Office-365-Federation-27410bdc
The below table will give you simple meanings to the configurable attributes for the set-adfsproperties that relate to token-signing and token-decrypting certificates.
| Attribute | Default Value | |
| AutoCertificateRollover | True | determines weather the certificates are auto generated and promoted ($true) or if the administrator wishes to do this themselves ($false) |
| CertificateCriticalThreshold | 2 | The period of time, in days, prior to the expiration of a current primary signing or decryption certificate. When a certificate reaches this threshold, the Federation Service initiates the automatic certificate rollover service, generates a new certificate, and promotes it as the primary certificate. This rollover process occurs even if the critical threshold interval does not provide sufficient time for partners to replicate the new metadata. |
| CertificateDuration | 365 | 365 is the default length of time the certificates are generated for {1 year}. |
| CertificateGenerationThreshold | 20 | 20 days before the certificate expires, new token-signing certificates are generated. |
| CertificatePromotionThreshold | 5 | 5 days after the new certificates are generated, they are promoted to primary. |
| CertificateRolloverInterval | 720 | Specifies the certificate rollover interval, in minutes. This value determines the frequency at which the Federation Service initiates the rollover service by polling to check whether new certificates need to be generated |
You can find out more details information about these attributes in the following TechNet article: https://technet.microsoft.com/en-us/library/dn479342.aspx
Example Configuration: {AutoCertificateRollOver=Enabled}
in this example, the default configuration is in place as per the above table.
- Current Day = 01-07-2014 (1st July 2014)
- Token Signing Certificate Expires: 25-07-2014
- Office 365 Portal indicates that service will be affected in 10 days (10-07-2014) if the trust properties are not updated.
- because if the federation trust is not updated with the new token-signing certificates prior to this date when the new certificate is promoted to primary SAML tokens issued won’t be valid.
- 05-07-2014 is when the federation service generates new token-signing/decrypting certificates
- because the certificategenerationthreshold is equal to 20 which means 20 days prior to the current certificate expiring new certificates are generated.
- 10-07-2014 is when the newly generated certificate will be promoted to primary
- because the certificatepromotionthreshold is equal to 5 which means 5 days after the new certificates are generated.
Important Recommendations
- It is always recommended that you have at least 1 global administrator that uses the managed domain name space such as *onmicrosoft.com.
- the reason for this is if you should have any issues with the relying partying not having the updating token-signing certificate, or if you force the creation & promotion by accident or/ if the autorollover kicks in without the trust properties being updated you won’t lock yourself out of your Office 365 Tenant.
If you lock yourself out of the tenant, you won’t be able to login to powershell to carry out the manual update, and so therefore you would have to open a case for Microsoft Support Team to help you out of this situation.
Appendix
if you should wish to check your existing configuration, you can run the following command on your AD FS Primary Server connected to the Microsoft Online Service
- Launch PowerShell Console
- Type {connect-msolservice) and press enter, type in your global administrator credentials
- Type {Get-MsolFederatedProperty –DomainName contoso.com}
in the output you want to compare the data in the following sources:
Source : ADFS Server
Source : Microsoft Office 365
- TokenSigningCertificate
- thumbprint
- they need to match in both sources in context of them being the current token-signing certificate.
- NextTokenSigningCertificate
- thumbprint
- they need to match in both sources in context of them being the current token-signing certificate.
I hope that this article helps you understand the process much more clearer, and ensures that you do not have any issues when this happens in your environment.
If you have any questions, please be sure to let me know.
Thanks
James.