How to Update Certificates for AD FS


How to Update Certificates for AD FS

Active Directory Federation Services (AD FS) 3.0 is a server role included in Windows Server 2012 R2.
Active Directory Federation Services (AD FS) 4.0 is a server role included in Windows Server 2016.

Certificates used by federation servers

Each federation server is required to have a server authentication certificate and a token-signing certificate before it can participate in AD FS communications. The trust policy requires an associated certificate, known as a verification certificate, which is the public key portion of the token-signing certificate.

Server authentication certificates The federation server uses Secure Sockets Layer (SSL) server authentication certificates to secure Web services traffic for communication with Web clients or the federation server proxy. These certificates are requested and installed through the Internet Information Services (IIS) snap-in.
Token-signing certificates Each federation server uses a token-signing certificate to digitally sign all security tokens that it produces. Because each security token is digitally signed by the account partner, the resource partner can verify that the security token was in fact issued by the account partner and that it was not modified. This helps prevent attackers from forging or modifying security tokens to gain unauthorized access to resources.

Digital signatures on security tokens are also used in the account partner when there is more than one federation server. In this situation, the digital signatures verify the origin and integrity of security tokens that are issued by other federation servers in the account partner. The digital signatures are verified with verification certificates.

    Replacing the SSL Certificate for an AD FS farm

    Normally the SSL certificate for the AD FS farm 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 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. You can find more information about the certificate requirements here.

    Now you can use Azure AD Connect Tool to update the SSL certificate for an Active Directory Federation Services (AD FS) farm. AD Connect is the preferred method for changing the SSL certificate. 

    You can perform the whole operation of updating SSL certificate for the AD FS farm across all federation and Web Application Proxy (WAP) servers in three simple steps:

    1. Provide ADFS Farm Information
    2. Provide new SSL Certificate
    3. Select Servers for update

    Prerequisites

    • AD FS Farm: Make sure that your AD FS farm is Windows Server 2012 R2-based or later.
    • Azure AD Connect: Ensure that the version of Azure AD Connect is 1.1.553.0 or higher. You'll use the task Update AD FS SSL certificate

    Update SSL task

    Step 1: Provide AD FS farm information

    Azure AD Connect attempts to obtain information about the AD FS farm automatically by:

      1. Querying the farm information from AD FS (Windows Server 2016 or later).
      2. Referencing the information from previous runs, which are stored locally with Azure AD Connect.

    You can modify the list of servers that are displayed by adding or removing the servers to reflect the current configuration of the AD FS farm. As soon as the server information is provided, Azure AD Connect displays the connectivity and current SSL certificate status.

    AD FS server info

    If the list contains a server that's no longer part of the AD FS farm, click Remove to delete the server from the list of servers in your AD FS farm.

    Offline server in list

    NoteRemoving a server from the list of servers for an AD FS farm in Azure AD Connect is a local operation and updates the information for the AD FS farm that Azure AD Connect maintains locally. Azure AD Connect doesn't modify the configuration on AD FS to reflect the change.

    Step 2: Provide a new SSL certificate

    After you've confirmed the information about AD FS farm servers, Azure AD Connect asks for the new SSL certificate. Provide a password-protected PFX certificate to continue the installation.

    SSL certificate

    After you provide the certificate, Azure AD Connect goes through a series of prerequisites. Verify the certificate to ensure that the certificate is correct for the AD FS farm:

      • The subject name/alternate subject name for the certificate is either the same as the federation service name, or it's a wildcard certificate.
      • The certificate is valid for more than 30 days.
      • The certificate trust chain is valid.
      • The certificate is password protected.

    Step 3: Select servers for the update

    In the next step, select the servers that need to have the SSL certificate updated. Servers that are offline can't be selected for the update.

    Select servers to update

    After you complete the configuration, Azure AD Connect displays the message that indicates the status of the update and provides an option to verify the AD FS sign-in.

    Configuration complete

     

    • 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
    2) Connect-MsolService
    3) Get-MsolFederationProperty
    4) Check [CertificateGenerationThreshold: 20]

    The new certificate will be promoted to Primary after 5 days:

    1) Go to Powershell
    2) Connect-MsolService
    3) Get-MsolFederationProperty
    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.

    Example:

    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
    Add-PSSnapin Microsoft.ADFS.PowerShell
    Get-ADFSProperties

    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.

     

    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
    AutoCertificateRollover:

    Add-PSSnapin Microsoft.Adfs.Powershell

    Set-ADFSProperties -AutoCertificateRollover $true

    PowerShell command to immediately generate new self-signed certificates:

    Add-PSSnapin Microsoft.Adfs.Powershell

    Update-AdfsCertificate -Urgent

    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:

    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.

     

    Comments (37)

    1. Nathan says:

      The last PowerShell statement: "Update-MsolFederatedDomain DomainName domain.com -SupportMultipleDomain" has a typo.  It should read: "Update-MsolFederatedDomain -DomainName domain.com -SupportMultipleDomain"

    2. Dan Schultz says:

      Excellent write-up, Vinayak! It's good to see more content published that's specific to v3.0.

    3. Bairu Sarat says:

      excellent article my 3 hours struggle solved, thanks Vinayak

    4. Matthew Dreher says:

      Just a note, if you use the GUI in ADFS to replace the certificate, it will not be fully operational.  You have to use the PowerShell cmdlet so that it can update it fully.   Took me a while to figure out why it wasn't updating.

    5. TheaNova says:

      When the communications service certificate is replaced; what, if anything, needs to be communicated to the replying parties? This will be my first time renewing this certificate and I want to make sure I am communicating clearly with RP’s.

      1. iVinayak says:

        @TheaNova, you’ll need to update other relaying party metadata, if you use them. For example, Yammer 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).
        For Office 365 see this link -https://support.microsoft.com/en-in/kb/2647048

    6. Donald says:

      The command: Set-ADFSProperties CertificateDuration 36500 -AutoCertificateRollover $true
      should be Set-ADFSProperties -CertificateDuration 3650 -AutoCertificateRollover $true

      1. iVinayak says:

        @Donald, Thanks for pointing out I will have this updated.

        1. WouterH says:

          Still forgot the ‘-‘ in front of CertificateDuration

          1. Kit Chung says:

            still missing the dash

    7. Brandon Fox says:

      Please update the first command, it should be:

      Set-AdfsCertificate -CertificateType Service-Communications -Thumbprint thumbprint

      Please adjust, thanks!

      1. iVinayak says:

        @Brandon, Thanks.. you can use both these commands on the primary server to update the SSL certificate:
        Set-AdfsCertificate -CertificateType Service-Communications -Thumbprint thumbprint
        Set-AdfsSslCertificate -Thumbprint thumbprint

    8. Ville-Veikko Nissinen says:

      Please add information that if you renew token certificates and then try connecting using Connect-MsolService, you can’t use federated accounts because federation is not working because of the certificate mismatch (you just renewed certs). Use Cloud Only Global Admin account to establish connection for updating certificates to O365 side. I’m not sure would it work if you establish connection to O365 services using Connect-MsolService before running certificate update commands.

      1. iVinayak says:

        Good point. It’s always recommend to use your admin account with onmicrosoft.com account.

        1. Ville-Veikko Nissinen says:

          You can use federated account when renewing token certs, but you have to use Connect-MsolService command before you make the changes. I have tested this and it works.

    9. Gururaj Meghraj says:

      Thanks Vinayak for the write-up.

      how can we replace Token Signing certificate with a certificate issued by a CA ?

    10. Noure says:

      Hi iVinayak,

      thanks for your article.
      Do you still need to update office 365 metadata if you just renew a certificate without changing Federation name, the domain nor the subject aletrnative names?

      Thanks again

      1. iVinayak says:

        You will have to update the O365 metadata after replacing the certs /names

        1. Poojita says:

          Hi everyone,
          I am new to ADFS platform and learning things. May I know, why should we update only O365 metadata and why not for other relying parties.

    11. Pradeep Mishra says:

      Thanks Vinayak. It’s excellent article

    12. Mike A says:

      Thanks Vinayak – I’ve always struggled with ADFS when you have to jump between the MMC and powershell, worked a treat.

    13. Kailash Chander says:

      hi vinayak,

      I have a query about token signing certificate.

      we are migrating out on-premise ADFS environment to Azure by spinning new ADFS & WAP servers in Azure. We plan to use existing SSL certificate for service communication by importing/exporting it to Azure ADFS servers. The question I have is around ‘Token Signing’ certificate. This is a self-signed cert in on-premise setup. In azure we will install new ADFS environment, which will have a new ‘Token Signing’ self-signed cert. Can you tell me, will this cause any outage? I have many apps like salesforce, concur, workday , o365 etc federated, do I need to share the new self-signed ‘Token signing’ certificate with these RP?

      1. iVinayak says:

        Yes. there will be outage as you will have to update federation metadata to RPs

    14. FR says:

      Hi, extra write-up, many thanks. i’v a question.
      I’v on premise ADFS with APFS proxy, i have to change ms SSL certificates (commmunication) , i know how i do this.

      but i’ts obligatory to update federation with Update-MsolFederatedDomain -DomainName or jsute change the SSL certificate on ADFS server en adfs proxy server ?

      Thx

      1. iVinayak says:

        Yes. It’s mandatory to Update-MsolFederatedDomain -DomainName

    15. Anonymous says:

      Hello Vinayak,
      While replacing the Service Communications certificate, when I run thecommand on an elevated powerShell, Set-AdfsCertificate -CertificateType Service-Communications -Thumbprint command, where I get an error, I have right permissions, and AD FS service has read access to the private key of the SSL certificate.
      PS C:\Windows\system32> Set-AdfsCertificate -CertificateType Service-Communications -Thumbprint XXXXXXXXXX
      Set-AdfsCertificate : The specified directory service attribute or value does not exist.
      At line:1 char:1
      + Set-AdfsCertificate -CertificateType Service-Communications -Thumbprint XX …
      + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      + CategoryInfo : InvalidData: (:) [Set-AdfsCertificate], COMException
      + FullyQualifiedErrorId : The specified directory service attribute or value does not exist.
      ,Microsoft.IdentityServer.Management.Commands.SetCertificateCommand
      any ideas?
      thanks in advance

      1. Ramin Heidari says:

        After Install certificate you should grant Read permission to ADFS service account to read certificate Private key.

        Go to
        mmc > Certificate > Local Machine > Personal

        Right Click on specific certificate and click on Manage Private Keys

        Then grand Full permission to ADFS Service Account.

        It should be work after this setting.

    16. tony says:

      Please clarify
      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.

      Set-AdfsSslCertificate -Thumbprint thumbprint also needs to be ran on each node of the farm.

      1. tony says:

        The following command needs to be ran on each ADFS server in the farm <-This should be added.
        Set-AdfsSslCertificate -Thumbprint thumbprint

        1. SamF says:

          What tony Said,

          You have to set the adfssslcertificate on all nodes in the cluster after you import the certificate

    17. John says:

      It seems that all this stems from a replacement of the SSL certificate. Is there a process for RENEWING this third part cert? In other words, my SSL will expire in 60 days and I received the renewal last week.

    18. The modern Mailman says:

      Thanks very much. These article has helped me a lot to implement the process and document it in my clients.

    19. Nelson Vieira says:

      Quick question:
      When updating the Token-Decrypting and Token-Signing cert on the farm, do you need to just do this on one node?
      Also, I left mine as the default, but this seems to be a real major pain to remember. I plan on switching the duration to the “3650” value, but is it necessary to disable the autorenew after? Cant you set it to “3650” and leave it to auto renew ?

      Thanks, I found this by fluke investigating something else and noticed that these certs are going to expire in 13 days!

    20. Caio Bauab says:

      The Set-AdfsSslCertificate -Thumbprint thumbprint command must be run on each AD FS server, once it is a per server http.sys bind configuration.

    21. Piyumi says:

      My customer’s ADFS primary certificate expires on 14th of Nov. According to the article a new certificate will be created before 20 days (25th of Oct) of the expiration of primary certificate and marked as secondary certificate. After 5 days of the creation of new ADFS secondary certificate, the new secondary certificate is marked as primary. That’s mean on 30th of Oct the newly secondary is prompted as primary.

      Can we change the newly created secondary cert into primary on 26th of Oct (within these 5 days after new cert generation) ? If can ,what will be the impact for ADFS services?or Do we need to change the newly created secondary to primary on 30th Oct?

    22. iVinayak says:

      Update – Using AD Connect tool update the SSL Cert. The new guidance is to use Azure AD Connect as the preferred method for changing the SSL certificate

    23. Dan says:

      The text in the sections for “Server authentication certificates” and “Token-signing certificates”, right near the top of the page, appears to extend past the viewable area of the page.

    Skip to main content