How To: Replace the O365 Signing Certificate

Version Affected: All

 

Overview

Office 365 (O365) realms use a signing certificate that is configured both on the IdP and within O365 itself. This article explains how to replace that certificate, using Office 365's ability to trust an old and new signing certificate at the same time so the rollover can happen with minimal or no downtime.

Microsoft deprecated the Azure AD PowerShell and MSOnline PowerShell modules on March 30, 2024, and has stated the MSOnline module may not remain available for updating federation settings in the future.

• Use Method 1 if the MSOnline module is still available in your environment.
• Use Method 2, the Microsoft Entra module, going forward — it is Microsoft's supported replacement for MSOnline.
   

In this article

• Method 1: Using the MSOnline Module (Deprecated)
• Method 2: Using the Microsoft Entra Module

Method 1: Using the MSOnline Module (Deprecated)

The MSOnline module has been deprecated by Microsoft and may stop working at any time; use Method 2 if it is no longer available in your environment.

1. On the IdP, open the Certificates MMC snap-in and import the new certificate into the same certificate store as the original certificate, then set its private key permissions to match the original certificate. See Digital Certificate Private Key Management and Grant Permission to Use Signing Certificate Private Key for the detailed steps.
2. On the IdP, open PowerShell and run the following, replacing 0086FF183C146A803C with the serial number or thumbprint of the new certificate:
   

   $CertToFind = '0086FF183C146A803C'
   $Cert = gci cert:\localmachine\my | ?{$_.thumbprint -eq $CertToFind -or $_.serialnumber -eq $CertToFind}
   $Cert | fl Subject,Issuer,FriendlyName,NotBefore,NotAfter,ThumbPrint,SerialNumber
   $O365Cert = [system.convert]::ToBase64String($cert.GetRawCertData()); $O365Cert
   $O365Cert | Out-File -FilePath .\O365Cert.txt -Force

3. Check the output to confirm it found the correct certificate. If it didn't, check the serial number or thumbprint and try again.
4. If the Microsoft Online Services Module for Windows PowerShell is installed on the IdP, skip to the next step. Otherwise, copy O365Cert.txt to the machine where that module is installed, and open PowerShell there.
5. On the machine with the MSOL module, change to the directory containing O365Cert.txt and run:
   

   $O365Cert = Get-Content -Path .\O365Cert.txt

6. Run Connect-MsolService, then update the domain's federation settings with the new certificate. Which command to use depends on whether the old signing certificate has already expired:
   • If the old certificate has not yet expired, queue the new certificate so O365 accepts either one until the old certificate expires:
     

     Connect-MsolService
     Set-MsolDomainFederationSettings -DomainName domainname.com -NextSigningCertificate $O365Cert

   • If the old certificate has already expired, set the new certificate immediately instead:
     

     Connect-MsolService
     Set-MsolDomainFederationSettings -DomainName domainname.com -SigningCertificate $O365Cert

   Replace domainname.com with the O365 domain being updated in both cases.
7. Verify the new settings have taken effect:
   

   Get-MsolDomainFederationSettings -DomainName domainname.com

8. If you used -NextSigningCertificate, Office 365 now accepts either the old or new signing certificate. Prior to the old certificate's expiry date, and when you're ready to complete the rollover, change the signing certificate on the Post Authentication tab of each affected O365 realm on the IdP:
   
9. Test that the new signing certificate works. If you receive an error, run IISRESET on the IdP and test again.

Method 2: Using the Microsoft Entra Module

This is Microsoft's supported replacement for the deprecated MSOnline module.

1. Install the required module:
   

   Install-Module -Name Microsoft.Entra -AllowClobber

2. Sign in and accept the consent prompt. If you don't have permission, contact your global administrator:
   

   Connect-Entra -Scopes 'Domain.ReadWrite.All', 'Directory.AccessAsUser.All'

3. Run the following and copy the value of the Id property:
   

   Get-EntraFederationProperty -DomainName your_domain.com | fl Id

4. Export the new signing certificate in base64 format, then remove the begin/end certificate lines and any line breaks so it is a single line with no spaces:
   

   $cert = "<CERT VALUE>"

5. Update the signing certificate, using the Id value from the earlier step:
   

   Update-MgDomainFederationConfiguration -DomainId your_domain.com -InternalDomainFederationId Id_from_step_3 -SigningCertificate $cert

6. Confirm the signing certificate was updated:
   

   Get-EntraFederationProperty -DomainName your_domain.com | fl id, displayname, signingcertificate

SecureAuth Knowledge Base Articles provide information based on specific use cases and may not apply to all appliances or configurations. Be advised that these instructions could cause harm to the environment if not followed correctly or if they do not apply to the current use case.

Customers are responsible for their own due diligence prior to utilizing this information and agree that SecureAuth is not liable for any issues caused by misconfiguration directly or indirectly related to SecureAuth products.