Replacing the SSL certificate

1. Obtain a new certificate with the following requirements

    a. Enhanced Key Usage is at least Server Authentication. If you are obtaining this from an internal MS Enterprise 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 farm 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 certificate.



2. Bind the new SSL certificate to the web site in IIS which hosts the Federation Service (this includes all Federation Servers and Federation Server Proxies)

    a. In IIS6 on Windows Server 2003 R2, you will select the Properties of the web site, Directory Security tab, and select Server Certificate:

 

b. In IIS7 on Windows Server 2008 and Windows Server 2008 R2, you will select the web site, right-click, Edit Bindings, select the SSL port, Edit, and use the drop-down 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).



3. 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

1. 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 and your Resource Partner Federation Servers 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 and Resource Partner Federation Servers 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.



2. Send your new token-signing certificate public key (.cer file or .p7b if you wish to include the entire chain) to all of your Resource Partners.



3. Have your Resource Partners check to make sure that all of their Federation Servers trust the root of your new token-signing certificate

    a. The best way to check is to run the following command: certutil -verify -urlfetch path-to-your-new-ts-cert-cer-file > verify.txt



4. Once you confirm that all Resource Partners trust the token-signing root, have them import the .cer into the Verification Certificates tab on the Account Partner trust they have for you. They should leave your old certificate there for rollover purposes, and plan to remove the old certificate once it has expired.







5. Once all of your Resource Partners have imported your new certificate, you are ready to make the replacement. We recommend performing this step after hours to minimize any outage you experience with any applications that you host from your Federation Service.



6. Launch the AD FS MMC (ADFS.msc) console on one of your Federation Servers. Select Federation Service, right-click, and select Properties.



7. On the General tab, find the Token-signing certificate section, and click Select.







8. 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 store with private key associated, and b. the certificate has the Digital Signature KU.



9. 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).







10. Depending on your OS and the state of the private key ACL, you may receive a prompt stating that the Federation Service is running as an account that does not have access to the certificate priate key. You will want to answer Yes to this prompt.



.



11. Click OK on the Federation Service Properties.



12. Select the Trust Policy, right-click, select Properties, and select the Verification Certificates tab. This is where web servers (AD FS Web Agents) in your environment obtain their token-signing trust information for your Federation Service. You should never add a certificate to this tab in an attempt to replace the token-signing certificate. THIS IS NOT THE CORRECT LOCATION TO MAKE THE REPLACEMENT! You will notice that your new certificate is automatically placed here once you made the change in the Federation Service Properties. You'll also notice that the old token-signing certificate is kept in the list as well. This is for rollover purposes and should be left alone for now. You should plan to remove the old certificate from this list once it has expired.







13. If you have AD FS Web Agents deployed within your environment, they will automatically pick up the new token-signing certificate within 60 minutes. If you need to cause the AD FS Web Agents to immediately pull new trust information, a simple IISRESET on each web server hosting an agent will trigger a pull.



14. Test the new token-signing certificate to ensure that your internal AD FS Web Agents trust the new certificate. Also test access to any Resource Partner applications to ensure that all of your Resource Partners trust your new token-signing certificate.



Replacing the Federation Server Proxy certificate

1. Obtain a new certificate with the following requirements

    a. Enhanced Key Usage is at least Client Authentication. If you are obtaining this from an internal MS Enterprise CA, the Computer template will work fine.

    b. Subject and/or Subject Alternative Name (SAN) does not matter. We recommend using something like "AD FS Proxy Auth" or "Contoso SSO Proxy Auth" so that you know exactly what the certificate is used for when you see it.

    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 Proxy farm.

    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. When choosing an issuing CA, remember that only your Federation Servers and your Federation Server Proxy servers need to be able to chain to a trusted root certification authority when validating your Federation Server Proxy 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 Federation Server Proxy servers must trust your PKI root. If you choose to use a self-signed certificate, your Federation Servers and Federation Server Proxy servers must import the self-signed certificate to the Trusted Root Certification Authorities store in order to trust the self-signed certificate.



2. Export the Federation Server Proxy certificate public key to file (.cer or .p7b if you wish to export the entire chain).



3. Copy the exported public key file to your internal Federation Server.



4. Launch the AD FS MMC (ADFS.msc) console on a Federation Server. Select Trust Policy, right-click, and select Properties.



5. Select the FSP Certificates tab:







6. Click Add and select the exported public key file for the new Federation Server Proxy certificate.



7. Click OK.



8. Launch the AD FS MMC (ADFS.msc) console on the Federation Server Proxy (you will need to perform these steps for all Federation Server Proxy servers).



9. Select Federation Service Proxy, right-click, and select Properties.



10. On the General tab under FSP client authentication certificate, click Select.







11. You will be presented with a list of certificates that are valid for Federation Server Proxy. 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 store with private key associated, and b. the certificate has the Client Authentication EKU.



12. Select your new Federation Server Proxy certificate and click OK.



*Note: Be careful when making your certificate selection. Your old Federation Server Proxy certificate and new Federation Server Proxy 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).







13. On Federation Service Proxy Properties, click OK.



14. Test the new Federation Server Proxy certificate by authenticating to your Federation Service from a client who utilizes your Federation Server Proxy.



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.