Replacing the SSL and Service Communications certificate

*Note - Replacing the SSL and Service Communications certificates go hand-in-hand. Any time you are replacing one of these certificates, you must also replace the other. SSL certificates exist on all Federation Servers and Federation Server Proxy servers. Service Communications certificates only exist on Federation Servers.

1. Obtain a new certificate with the following requirements

    a. Enhanced Key Usage is at least Server Authentiation. If you are obtaining this from an internal MS Exterprise CA, the Web Server template will work fine.
    b. Subject or Subject Alternative Name (SAN) must contain the DNS name of your Federation Service or an appropriate wildcard name
           Example: sso.contoso.com or *.contoso.com
    c. You may wish to generate the certificate request and mark the private key exportable so that you can move the certificate from one server to others in the case when you have a Federation Server frarm or at least one Federation Server Proxy.
    d. Take note of which server was used to generate the certificate request. The private key is generated and stored here. When you receive the certificate from the issuing CA, you will need to bring that file back to the server where the request was initiated so that you can create a private/public key pair.
    e. The issuing CA that you choose is important because your Federation Server(s), Federation Server Proxy(ies), and all clients accessing your Federation Service must be able to chain to a trusted root certification authority when validating the SSL certificate. Customers will typically use a 3rd party, public CA for the SSL and Service Communications certificate.

2. ACL the SSL and Service Communications certificate to allow Read access for the AD FS 2.0 service account
*Note - This step must be completed on all Federation Servers only.

    a. Click Start, Run, type MMC.exe, and press Enter
    b. Click File, Add/Remove Snap-in
    c. Double-click Certificates
    d. Select Computer account and click Next
    e. Select Local computer and click Finish
    f. Expand Certificates (Local Computer), expand Personal, and select Certificates
    g. Right-click your new SSL and Service Communications certificate, select All Tasks, and select Manage Private Keys
    h. Add Read access for your AD FS 2.0 service account and click OK
    i. Close the Certificates MMC

3. Bind the new SSL and Service Communications certificate to the web site in IIS which hosts the Federation Service
*Note - This step must be completed on all Federation Servers and Federation Server Proxy servers.

    a. In IIS7 on Windows Server 2008 and Windows Server 2008 R2, you will select the web site, right-click, Edit Bindings, and select the SSL port, Edit, and use the drop-dwon to select the new SSL certificate:

       

*Note - Be careful when making your certificate selection. Your old SSL certificate and new SSL certificate will likely have the same subject name and/or friendly name, and this may make it difficult to differentiate between the two certificates. When in doubt, use thumbprint matching (see the Thumbprint Matching section at the end of this article).

4. Set a new Service Communications certificate in the AD FS 2.0 Management console
*Note - This step needs to be completed just one time on a single Federation Server in the farm. Proxies are not involved here, and other Federation Servers in a farm will pick up this change automatically.

    a. Launch AD FS 2.0 Management from the Administrative Tools menu
    b. Expand Service and select Certificates
    c. In the Actions pane, click Set Service Communications Certificate...



    d. You will be presented with a list of certificates that are valid for Service Communications. If you find that your new certificate is not being presented in the list, you need to go back and make sure that a. the certificate is in the local computer Personal store with private key associated, and b. the certificate has the Server Authentication EKU.
    e. Select your new Service Communiations certificate and click OK

* Note: Be careful when making your certificate selection. Your old Service Communications certificate and new Service Communications certificate might have the same subject name and/or friendly name, and this may make it difficult to differentiate between the two certificates. When in doubt, use thumbprint matching (see the Thumbprint Matching section at the end of this article).



5. Test SSL functionality for internal and external users to ensure that SSL is working as expected on the Federation Servers and the Federation Server Proxy servers.

Replacing the Token-Signing certificate

*Note - If you are utilizing the AutoCertificateRollover feature of AD FS 2.0, you do not need to manually replace the Token-Signing certificate. AutoCertificateRollover will create a self-signed Token-Signing certificate for you and set it as the Primary Token-Signing certificate when a time threshold has been met. The new Token-Signing certificate is published in your Federation Metadata, and Relying Party (RP) partners who can consume Federation Metadata will automatically pick up the change whenever they pull your Federation Metadata document. You should work with your RP partners to see how often they pull for Federation Metadata so that, in the event of a certificate replacement, they will experience little to no downtime before trusting your new certificate. If your RP partners cannot consume Federation Metadata, you should be aware of when AutoCertificateRollover will set a new Primary Token-Signing certificate and you will need to plan accordingly to send the public key portion of this certificate to your RP partners.

1. Check to see if you are utilizing AutoCertificateRollover

    a. Launch Powershell on a Federation Server
    b. Run the following commands:
        Add-Pssnapin Microsoft.Adfs.Powershell
        Get-ADFSProperties
    c. Look for the value of AutoCertificateRollover in the output. It will show True or False
    d. If the result of step c. is True, then you are finished, and you should take special note of everything in the *Note above. If the result of step c. is False, then you will need to maintain the Token-Signing certificate manually, and you should move on to the next step.

2. Obtain a new certificate with the following requirements

    a. It is common to think that a specific Enhanced Key Usage (EKU) is needed for the Token-Signing certificate, but this is, in fact, not correct. The only requirement for usage is that Key Usage (KU) must contain at least Digital Signature. We have seen a lot of customers go through the trouble of obtaining a Code Signing EKU certificate. Again, EKU is not required for Token-Signing.
    b. Subject and/or Subject Alternative Name (SAN) does not matter. We recommend using something like "AD FS Token-Signing" or "Contoso SSO Token-Signing" so that you know exactly what the certificate is used for when you see it.
    c. Take note of which server was used to generate the certificate request. The private key is generated and stored here. When you receive the certificate from the issuing CA, you will need to bring that file back to the server where the request was initiated so that you can create a private/public key pair.
    d. When choosing an issuing CA, remember that only your Federation Servers, your RP Federation Servers and RP applications need to be able to chain to a trusted root certification authority when validating your Token-Signing certificate. You could save on the cost of a 3rd party certificate by using an internal PKI-issued certificate or a self-signed certificate. If you choose to use an internal PKI, your Federation Servers, RP Federation Servers and RP applications must trust your PKI root. If you choose to use a self-signed certificate, your Federation Servers and Resource Partner Federation Servers must import the self-signed certificate to the Trusted Root Certification Authorities store in order to trust the self-signed certificate.

3. Decide how your RP partners will trust the new Token-Signing certificate



RP partners who can consume Federation Metadata

You should replace the Token-Signing certificate and instruct the RP partners to pull for your new Federation Metadata to pick up the new certificate.

RP partners who can NOT consume Federation Metadata

You must manually send them the public key of your new Token-Signing Certificate. Send your new Token-Signing certificate public key (.cer file or .p7b if you wish to include the entire chain) to all of your RPs. Have the partner implement changes on their side to trust the new certificate. If the RP partner is using AD FS 2.0, the following will apply.

On the RP partner AD FS 2.0 server:

    a. Launch AD FS 2.0 Management from the Administrative Tools menu
    b. Expand Trust Relationships, select Claims Provider Trusts, and select the trust that was created for you
    c. Right-click the trust name and select Properties
    d. Select the Certificates tab and Add the new Token-Signing certificate
    e. Click OK



4. Add the new Token-Signing certificate

    a. Launch AD FS 2.0 Management from the Administrative Tools menu
    b. Expand Service and select Certificates
    c. In the Actions pane, click Add Token-Signing Certificate...
    d. You will be presented with a list of certificates that are valid for Token-Signing. If you find that your new certificate is not being presented in the list, you need to go back and make sure that a. the certificate is in the local computer Personal store with private key associated, and b. the certificate has the Digital Signature KU.
    e. Select your new Token-Signing certificate and click OK

* Note: Be careful when making your certificate selection. Your old Token-Signing certificate and new Token-Signing certificate might have the same subject name and/or friendly name, and this may make it difficult to differentiate between the two certificates. When in doubt, use thumbprint matching (see the Thumbprint Matching section at the end of this article).



5. ACL the private key to allow Read access to the AD FS 2.0 service account

    a. When you add a new Token-Signing certificate, you receive a warning reading: "Ensure that the private key for the chosen certificate is accessible to the service account for this Federation Service on each server in the farm":



    b. Click Start, Run, type MMC.exe, and press Enter
    c. Click File, Add/Remove Snap-in
    d. Double-click Certificates
    e. Select Computer account and click Next
    f. Select Local computer and click Finish
    g. Expand Certificates (Local Computer), expand Personal, and select Certificates
    h. Right-click your new Token-Signing certificate, select All Tasks, and select Manage Private Keys
    i. Add Read access for your AD FS 2.0 service account and click OK
    j. Close the Certificates MMC

6. Set the new Token-Signing certificate as Primary

    a. With the Certificates node in AD FS 2.0 Management selected, you should now see two certificates listed under Token-Signing:
        i.  Your old Token-Signing certificate
        ii. Your new Token-Signing certificate
    b. Select your new Token-Signing certificate, right-click, and select Set as primary
    c. Leave the old certificate as secondary for rollover purposes. You should plan to remove the old certificate once you are confident it is no longer needed for rollover, or when the certificate has expired.
            i. Current users' SSO sessions are signed and possibly also encrypted using the OLD certificate
            ii. Current AD FS 2.0 Proxy Trust relationships utilize tokens that are signed and encrypted using the OLD certificate



 
7. Test the new Token-Signing certificate by sending a SAML assertion to your RP partners and RP applications

Replacing the Token-Decrypting certificate

*Note - If you are utilizing the AutoCertificateRollover feature of AD FS 2.0, you do not need to manually replace the Token-Decrypting certificate. AutoCertificateRollover will create a self-signed Token-Decrypting certificate for you and set it as the Primary Token-Decrypting certificate when a time threshold has been met. The new Token-Decrypting certificate is published in your Federation Metadata, and Claims Provider (CP) partners who can consume Federation Metadata will automatically pick up the change whenever they pull your Federation Metadata document. You should work with your CP partners to see how often they pull for Federation Metadata so that, in the event of a certificate replacement, they will experience little to no downtime before utilizing your new certificate for token encryption. If your CP partners cannot consume Federation Metadata, you should be aware of when AutoCertificateRollover will set a new Primary Token-Decrypting certificate and you will need to plan accordingly to send the public key portion of this certificate to your CP partners.

1. Check to see if you are utilizing AutoCertificateRollover

    a. Launch Powershell on a Federation Server
    b. Run the following commands:
        Add-Pssnapin Microsoft.Adfs.Powershell
        Get-ADFSProperties
    c. Look for the value of AutoCertificateRollover in the output. It will show True or False
    d. If the result of step c. is True, then you are finished, and you should take special note of everything in the *Note above. If the result of step c. is False, then you will need to maintain the Token-Decrypting certificate manually, and you should move on to the next step.

2. Obtain a new certificate with the following requirements

    a. It is common to think that a specific Enhanced Key Usage (EKU) is needed for the Token-Decrypting certificate, but this is, in fact, not correct. The only requirement for usage is that Key Usage (KU) must contain at least Key Encipherment. We have seen a lot of customers go through the trouble of obtaining a Code Signing EKU certificate. Again, EKU is not required for Token-Decrypting.
    b. Subject and/or Subject Alternative Name (SAN) does not matter. We recommend using something like "AD FS Token-Decrypting" or "Contoso SSO Token-Decrypting" so that you know exactly what the certificate is used for when you see it.
    c. Take note of which server was used to generate the certificate request. The private key is generated and stored here. When you receive the certificate from the issuing CA, you will need to bring that file back to the server where the request was initiated so that you can create a private/public key pair.
    d. When choosing an issuing CA, remember that only your Federation Servers and CP partners need to be able to chain to a trusted root certification authority when validating your Token-Decrypting certificate. You could save on the cost of a 3rd party certificate by using an internal PKI-issued certificate or a self-signed certificate. If you choose to use an internal PKI, your Federation Servers and CP partners must trust your PKI root. If you choose to use a self-signed certificate, your Federation Servers and CP partners must import the self-signed certificate to the Trusted Root Certification Authorities store in order to trust the self-signed certificate.

3. Decide how your CP partners will trust the new Token-Decrypting certificate

CP partners who can consume Federation Metadata

You should replace the Token-Decrypting certificate and instruct the CP partners to pull for your new Federation Metadata to pick up the new certificate. 

 CP partners who can NOT consume Federation Metadata

You must manually send them the public key of your new Token-Decrypting certificate. Send your new Token-Decrypting certificate public key (.cer file or .p7b if you wish to include the entire chain) to all of your CPs. Have the partner implement changes on their side to trust the new certificate. If the CP partner is using AD FS 2.0, the following will apply.

On the CP partner AD FS 2.0 server:

    a. Launch AD FS 2.0 Management from the Administrative Tools menu
    b. Expand Trust Relationships, select Relying Party Trusts, and select the trust that was created for you
    c. Right-click the trust name and select Properties
    d. Select the Encryption tab and click Browse... to select the new Token-Decrypting certificate
    e. Click OK



4. Add the new Token-Decrypting certificate

    a. Launch AD FS 2.0 Management from the Administrative Tools menu
    b. Expand Service and select Certificates
    c. In the Actions pane, click Add Token-Decrypting certificate...
    d. You will be presented with a list of certificates that are valid for Token-Decrypting. If you find that your new certificate is not being presented in the list, you need to go back and make sure that a. the certificate is in the local computer Personal store with private key associated, and b. the certificate has the Key Encipherment KU.
    e. Select your new Token-Decrypting certificate and click OK

* Note: Be careful when making your certificate selection. Your old Token-Decrypting certificate and new Token-Decrypting certificate might have the same subject name and/or friendly name, and this may make it difficult to differentiate between the two certificates. When in doubt, use thumbprint matching (see the Thumbprint Matching section at the end of this article).



5. ACL the private key to allow Read access to the AD FS 2.0 service account

    a. When you add a new Token-Decrypting certificate, you receive a warning reading: "Ensure that the private key for the chosen certificate is accessible to the service account for this Federation Service on each server in the farm":



   b. Click Start, Run, type MMC.exe, and press Enter
    c. Click File, Add/Remove Snap-in
    d. Double-click Certificates
    e. Select Computer account and click Next
    f. Select Local computer and click Finish
    g. Expand Certificates (Local Computer), expand Personal, and select Certificates
    h. Right-click your new Token-Decrypting certificate, select All Tasks, and select Manage Private Keys
    i. Add Read access for your AD FS 2.0 service account and click OK
    j. Close the Certificates MMC

6. Set the new Token-Decrypting certificate as Primary

    a. With the Certificates node in AD FS 2.0 Management selected, you should now see two certificates listed under Token-Decrypting:
        i.  Your old Token-Decrypting certificate
        ii. Your new Token-Decrypting certificate
    b. Select your new Token-Decrypting certificate, right-click, and select Set as primary
    c. Leave the old certificate as secondary for rollover purposes. You should plan to remove the old certificate once you are confident it is no longer needed for rollover, or when the certificate has expired.
            i. Current users' SSO sessions are signed and possibly also encrypted using the OLD certificate
            ii. Current AD FS 2.0 Proxy Trust relationships utilize tokens that are signed and encrypted using the OLD certificate



7. Test the new Token-Decrypting certificate by having your CP partners send you an encrypted SAML assertion

More Information

Thumbprint Matching
1. View the properties of the certificate (double-click the certificate in the Certificates MMC or in Windows Explorer. Within an application interface, you may be presented with a control to View Certificate or similar).
2. Select the Details tab
3. Scroll down to the Thumprint property and select it:



4. Take note of the first 4 characters and the last 4 characters (this usually gives us a good idea of thumbprint uniqueness)
    Example from the screenshot above: 92 e3 and d8 6c

5. Repeat steps 1-4 on another certificate and compare the noted values

Were you looking for AD FS 1.x information regarding certificate replacement?

AD FS 1.0 and 1.1: How to Replace the SSL, Token-Signing, and Federation Server Proxy Certificates - http://social.technet.microsoft.com/wiki/contents/articles/ad-fs-1-0-and-1-1-how-to-replace-the-ssl-token-signing-and-federation-server-proxy-certificates.aspx

Have you recently enabled AutoCertificateRollover and you need to immeditately self-sign new Token-Signing and Token-Decrypting certificates?

AD FS 2.0: How to Enable and Immediately Use AutoCertificateRollover - http://social.technet.microsoft.com/wiki/contents/articles/ad-fs-2-0-how-to-enable-and-immediately-use-autocertificaterollover.aspx