Jaa

Maintain the Exchange Server OAuth certificate

  • Artikkeli

General information

This documentation describes the required steps to rotate the Exchange Server Auth Certificate without interrupting the Exchange service and before the current one expires.

Tip

You can also use the MonitorExchangeAuthCertificate script. It performs the necessary steps of rotating the OAuth certificate automatically. It can also help you to replace the OAuth certificate if it has already expired.

The Auth Configuration and Auth Certificate are used by Microsoft Exchange server to enable server-to-server authentication using the Open Authorization (OAuth) protocol standard. You can find more information about it in the following article: Plan Exchange integration with SharePoint and Skype for Business

The Auth Certificate is also used by several Exchange Server security features.

During the installation of the first Exchange server, the setup routine generates a self-signed certificate with the friendly name Microsoft Exchange Server Auth Certificate, which is then added to a new Auth Configuration. This certificate is automatically replicated to all front-end servers in the Exchange organization. Exchange certificate servicelet performs the replication, which is part of the MSExchangeServiceHost process. If you add more servers to your Exchange organization, the servicelet takes care of replicating the certificate to all Exchange servers, which were added to the organization.

The certificate, which is configured as current Auth Certificate can be queried by running the following PowerShell (must be executed in Exchange Management Shell) query:

(Get-AuthConfig).CurrentCertificateThumbprint | Get-ExchangeCertificate | Format-List Subject, Thumbprint, NotAfter, NotBefore

If the call fails with the following warning, it means that the current Auth Certificate is missing on the server.

A special Rpc error occurs on server <Servername>: The certificate with thumbprint <AuthCertificateThumbprint> was not found.

Follow the instructions mentioned in the "What are the steps to follow if the current certificate has already expired or is missing" section to fix.

The certificate, which is configured as next Auth Certificate can be queried as followed:

(Get-AuthConfig).NextCertificateThumbprint | Get-ExchangeCertificate | Format-List Subject, Thumbprint, NotAfter, NotBefore

If the call fails with the same warning as for the current Auth Certificate, it means that the next Auth Certificate isn't configured or is missing on the server.

Follow the instructions outlined in the "How to rotate the Exchange Server Auth Certificate" if the current Auth Certificate is about to expire.

What are the steps to follow if the current certificate has already expired or is missing?

In this case, it's required to immediately replace the old Auth Certificate with a new one. Follow the instructions outlined in the resolutions section of the following support article: Can't sign in to Outlook on the web or EAC if Exchange Server OAuth certificate is expired

How to rotate the Exchange Server Auth Certificate

It's important to replace the active Auth Certificate with a new one, before it expires. Doing so ensures a smooth transition to a new certificate without interrupting the Exchange service. You can follow the steps below to prepare and stage a new Auth Certificate.

Important

Please make sure that you have the latest Exchange Server Cumulative Update (CU) installed because it contains fixes that affect the corresponding Exchange feature.

  1. Generate a new Auth Certificate by running the following command:

    $newAuthCertificate = New-ExchangeCertificate -KeySize 2048 -PrivateKeyExportable $true -SubjectName "cn=Microsoft Exchange Server Auth Certificate" -FriendlyName "Microsoft Exchange Server Auth Certificate" -DomainName @()

  2. Don't overwrite the existing default SMTP certificate (Type 'N' and press enter):

    Confirm
Overwrite the existing default SMTP certificate?

Current certificate: '<DefaultSMTPCertificateThumbprint>' (expires 12/30/2027 2:39:08 PM)
Replace it with certificate: '<NewCertificateThumbprint>' (expires 1/5/2028 9:04:48 AM)
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [?] Help (default is "Y"): N

  3. Configure the Auth Certificate to become the new active one in 49 hours at the earliest:

    Set-AuthConfig -NewCertificateThumbprint $newAuthCertificate.Thumbprint -NewCertificateEffectiveDate (Get-Date).AddHours(49)

Depending on the size of your Exchange organization it might take some time for the new Auth Certificate to be deployed to all Exchange servers. Our recommendation is to plan for at least 48 hours before the newly generated Auth Certificate becomes active. In large Exchange environment it can take even longer.

A reference to the Auth Certificate is cached by the MSExchangeOWAAppPool and MSExchangeECPAppPool application pool. You can recycle those application pools to refresh this reference. You can do so by running the following commands from an elevated PowerShell window:

Restart-WebAppPool MSExchangeOWAAppPool
Restart-WebAppPool MSExchangeECPAppPool

The Exchange AuthAdmin servicelet, which is also a part of the MSExchangeServiceHost process, is responsible for the final Auth Certificate publishing process. The servicelet is executed immediately if the MSExchangeServiceHost service is restarted. Afterwards it's executed every 12 hours and if it detects that the NewCertificateEffectiveDate is reached, it then publishes the new Auth Certificate to make it the new active one.

To ensure that the AuthAdmin servicelet can start, you must enable the AuthAdminReadSession when your Exchange Servers are installed in a child domain and the system mailbox is located in the root domain. Otherwise, the AuthAdmin servicelet can't start. Run the following PowerShell cmdlet if your Exchange servers are installed in the described constellation:

Set-OrganizationConfig -EnableAuthAdminReadSession:$true

You can query the last runtime of the AuthAdmin servicelet by running the following PowerShell cmdlets:

[xml]$xml = Get-ExchangeDiagnosticInfo -Process "Microsoft.Exchange.ServiceHost"
$xml.Diagnostics.Components.AnchorApplication.AnchorServiceComponents.CacheScheduler.lastRunTime

Each run of the AuthAdmin servicelet is logged to the following directory: <ExchangeInstallPath>\Logging\AuthAdminLogs

The servicelet generates a new event log entry when the rotation of the Auth Certificate is successfully completed:

Log Name:      Application
Source:        MSExchange AuthAdmin
Date:          12/29/2022 5:56:13 AM
Event ID:      2014
Task Category: General
Level:         Information
Keywords:      Classic
User:          N/A
Description:   The current signing certificate for Exchange has been updated to certificate with thumbprint <NewExchangeCertificateThumbprint>.

Frequently asked questions

Question: Is it required to rerun the Hybrid Configuration Wizard (HCW) after the Auth Certificate is replaced?

Answer: Yes, we strongly recommend running the Hybrid Configuration Wizard (HCW) after the active Auth Certificate is replaced.

Question: What should I do if the new Auth Certificate is missing on an Exchange server in a different Active Directory (AD) site?

Answer: You can export the certificate by using the Export-ExchangeCertificate cmdlet and import it via Import-ExchangeCertificate on a server in the other AD site. The certificate servicelet takes care of the replication to the remaining Exchange servers located within the AD site.