There are three certificates used by ADFS for SSO:
- Service Communications -- This SSL cert is used to encrypt all client connectivity to the AD FS server.
- Token-Signing -- This x.509 cert is used to sign the token sent to the relaying party to prove that it indeed came from AD FS.
- Token-Decrypting -- This x.509 cert used to encrypt the payload of a SAML token before its encrypted again at the SSL transport layer. It is rarely used.
Replacing the Service Communications Certificate
Normally the Service Communications certificate comes from a trusted third-party CA, like DigiCert or GoDaddy. This is a traditional SSL cert like you would use in IIS for any secure web server. You may use a single-name, subject alternative name (SAN), or wildcard cert for this purpose as long as it's valid and trusted by internal and external AD FS clients.
If you have more than one AD FS server in your environment you will run the second half of these 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 each AD FS server and open an elevated PowerShell prompt to run the following commands:
dir cert:\LocalMachine\My
- Copy the thumbprint for the new SSL certificate you wish to use, then run:
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:
dir cert:\LocalMachine\My
- Copy the thumbprint and run:
Set-WebApplicationProxySslCertificate -Thumbprint thumbprint
- Repeat for each WAP server.
- PowerTip: 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.
Although you can use public certs for Token-Signing and Token-Decrypting, I don't recommend it because it's a waste of time and money. You also should not use the same SSL cert that you use for Service Communications for Token-Decrypting or Token-Signing. As mentioned earlier, the Token-Decrypting certificate is rarely used, but I include it here so that Office 365 doesn't warn about it.
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 100 years and enable Auto Certificate Rollover:
Set-ADFSProperties -CertificateDuration 36500 -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:
Connect-MsolService
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.
No comments:
Post a Comment
Thank you for your comment! It is my hope that you find the information here useful. Let others know if this post helped you out, or if you have a comment or further information.