Enable Modern Auth in Exchange Server on-premises (2023)

Overview

With the release of Exchange Server 2019 CU13, Exchange Server supports OAuth 2.0 (also known as Modern authentication) for pure on-premises environments using ADFS as a security token service (STS). This document provides the prerequisites and steps to enable this feature.

To use modern auth, users need clients (Outlook or any other native OS clients) that support Modern auth using ADFS. Initially, this feature is available only for Outlook on Windows, but support for modern auth will be added to other Outlook clients in the future.

Modern auth in Exchange Server 2019 shouldn't be confused with Hybrid Modern Authentication, which uses Azure AD for modern authentication. In fact, HMA is still the only recommended method to enable Modern auth for all on-premises and cloud users in an Exchange Hybrid configuration. This new feature allows Modern auth use by customers who don’t have Azure AD or aren't in an Exchange Hybrid configuration.

How will Modern Authentication work and is this feature applicable to me?

With Modern auth, users can authenticate to Exchange using ADFS. When Modern auth is enabled for a user, their Outlook client is redirected to ADFS. Users can then authenticate by providing credentials or performing multi-factor authentication. Once ADFS authenticates a user, it generates access tokens. These access tokens are validated by Exchange Server to provide client access to the user’s mailbox.

The following diagram illustrates the coordination between Exchange Server, ADFS and Outlook to authenticate a user using Modern auth.

In the above chart, steps 3a, 4a, 5a and 6a take place when Modern auth is enabled for the end user. Steps 3b, 4b occur when Modern auth is disabled for a user.

Refer to the following table to evaluate if this feature is applicable for you.

Prerequisites to enable Modern Authentication in Exchange

Exchange Server 2019 CU13 or later

To use Modern auth, all servers used for client connections must have Exchange Server 2019 CU13 installed.

ADFS 2019 or later

To enable Modern auth in an on-premises Exchange environment, Active Directory Federation Services (ADFS) on Windows Server 2019 or later is required.

You may also need Web Application Proxy Server (on Windows Server 2019 or later) to enable client access from outside corporate network.

Client Prerequisites

Outlook on Windows

Support for Modern Auth via ADFS is available for Outlook in Microsoft 365 apps on the Insider channel and Current channel. The Outlook build number must be 16327.20200 or later. You can check the build number of your Office by following steps mentioned here.

If you're using retail versions of Office 2021, such as Office Home & Business 2021 or Office Professional 2021, you must use a build later than 16327.20200.

Windows OS

The Windows client must be Windows 11 22H2 or later and it must have the March 14, 2023 update installed.

You can review Windows Update history to verify that KB5023706 is installed.

Steps to configure Modern Authentication in Exchange Server using ADFS as STS

This section provides details on to implement Modern auth in Exchange Server 2019 CU13.

Install Exchange 2019 CU13 on all FE Servers (at least)

All servers used for client connections must be upgraded to Exchange 2019 CU13. This ensures that initial client connections to Exchange 2019 use OAuth, and proxied connections to Exchange Server 2016 will use Kerberos.

Exchange 2019 CU13 adds support for new authentication policies to allow or block Modern auth at user level. Blocking Modern auth is used to ensure clients that don’t support Modern auth can still connect.

Running /PrepareAD with Setup is required to add several new authentication policy parameters to Exchange Server.

1. BlockModernAuthActiveSync
2. BlockModernAuthAutodiscover
3. BlockModernAuthImap
4. BlockModernAuthMapi
5. BlockModernAuthOfflineAddressBook
6. BlockModernAuthPop
7. BlockModernAuthRpc
8. BlockModernAuthWebServices

After installing CU13, any pre-existing auth policies (including the default authentication policy) will have the above parameters disabled. This means that customers using HMA don't need to change their pre-existing auth policies.

No new authentication policy required for Exchange Hybrid customers

Existing Exchange Hybrid customers should use Hybrid Modern Auth. Hybrid customers using HMA can leave the values of the BlockModernAuth* parameters at 0 to continue using HMA.

Set up Active Directory Federation Services (ADFS)

Customers need to install and configure ADFS in the environment to allow Exchange clients to use Forms authentication (OAuth) to connect to Exchange Server.

Certificate requirements for ADFS configuration in Exchange Server Organization

ADFS requires two basic types of certificates (refer this article for detailed information):

1. A service communication Secure Sockets Layer (SSL) certificate for encrypted web services traffic between the ADFS server, clients, Exchange servers, and the optional Web Application Proxy server. We recommend that you use a certificate that's issued by an internal or commercial certification authority (CA), because all clients need to trust this certificate.
2. A token-signing certificate for encrypted communication and authentication between the ADFS server, Active Directory domain controllers, and Exchange servers. You can obtain a token-signing certificate by requesting one from a CA or by creating a self-signed certificate.

For more information about creating and importing SSL certificates in Windows, see Server Certificates.

Here's a summary of the certificates that we are using in this scenario:

Deploy and Configure ADFS Server

Use Windows Server 2019 or later to deploy an ADFS server. Follow the steps: Deploy an ADFS server and Configure and test the ADFS server. Verify that you can open the URL of federation metadata in a web browser from the Exchange server and at least one client machine.

The URL uses the syntax:

https://<FederationServiceName>/federationmetadata/2007-06/federationmetadata.xml

For example,

https://adfs.contoso.com/federationmetadata/2007-06/federationmetadata.xml

Choose appropriate SSO Lifetime

Choose an appropriate SSO lifetime so end users aren't required to frequently reauthenticate. To configure an SSO lifetime, open ADFS management on the ADFS server and choose Edit Federation Service Properties in Actions (present on the right side of the ADFS management window).

Enter the Web SSO lifetime (minutes), which is the maximum time after which users need to reauthenticate.

Configure Authentication Method in ADFS

To use Modern auth in Outlook on Windows, you need to configure Primary Authentication Methods. We recommend choosing Forms Authentication for both Extranet and Intranet, as shown below.

Enable device registration in ADFS

Verify that device registration is configured, and device authentication is enabled by checking the Device Registration Overview.This step is recommended to reduce the number of authentication prompts for users and can help enforce Access Control Policies in ADFS.

Complete all the steps to configure Device Registration Service Discovery and the Device Registration Discovery Server SSL certificate, as detailed here.

Create ADFS Application Group for Outlook

1. Right click on Application Groups and click Add Application Group.

2. Select Native Application accessing a web API.

3. Type a name such as Outlook and click next.

4. On the Native application page, add the following client identifier and redirect Uri for Outlook and click Next.

   • Client Identifier: d3590ed6-52b3-4102-aeff-aad2292ab01c

   • Redirect URI (add the following two URIs):

     urn:ietf:wg:oauth:2.0:oob

     ms-appx-web://Microsoft.AAD.BrokerPlugin/d3590ed6-52b3-4102-aeff-aad2292ab01c

5. In the Configure Web API tab, add all FQDNs used by your Exchange environment, including Autodiscover, load balancing FQDNs, server FQDNs, etc. For example:

   • https://autodiscover.contoso.com/
   • https://mail.contoso.com/

   Important

   It is important here to make sure all client-facing URLs are covered, or it won't work. Include the trailing /'s and ensure the URLs start with https://.

6. In the Apply Access Control Policy tab, Permit everyone to start with and then change later if needed. Don't check the checkbox at the bottom of the page.

7. In Configure Application Permissions, choose Native Application app, and under Permitted Scopes check user_impersonation in addition to openid, which is checked by default.

8. Complete the assistant.

Add Issuance Transform Rules in Outlook Application Group

For the above created application group Outlook, add Issuance Transform Rules. Right click on the Outlook application group and select properties.

Edit the Web API settings, and under Issuance Transform Rules add the following custom rules:

After adding the rules, the Outlook - Web API Properties should look as follows:

Optionally Web Application Proxy can be configured for Extranet Access

Web Application Proxy is part of the Remote Access server role in Windows Server. It provides reverse proxy functionality to allow users to access your web applications from outside the corporate network. Web Application Proxy preauthenticates access to web applications by using ADFS, and functions as an ADFS proxy.

If you plan to use Web Application proxy, use steps mentioned in Install and Configure the Web Application Proxy Server to configure it. Once configured, you can publish rules for Autodiscover.contoso.com or/and mail.contoso.com using the steps mentioned in Publish an Application that uses OAuth2.

Optionally, MFA can also be configured for client access

1. Refer to the following links to configure ADFS with an MFA provider of your choice.

   • Configure 3rd party authentication providers as primary authentication in AD FS 2019
   • Configure Azure MFA as authentication provider with AD FS

2. Configure Access Control Policy requiring MFA.

   • Access Control Policies in Windows Server 2016 AD FS

Client-Side Modern Authentication configuration

We recommend testing Modern auth with few users before deploying to all users. Once a pilot group of users can use Modern auth, more users can be deployed.

1. Client upgrade and OS upgrade:

   As outlined in the Client prerequisites section, Modern auth is supported only for Outlook on Windows. To use Modern auth, the Outlook client Insider Channel must be installed on Windows 11 OS 22H2 with the March 14, 2023 update or later.

2. Registry changes in client machines:

   Admins need to configure registry values for users.

   Enable Modern auth and add your ADFS domain as trusted domain in Outlook:

   1. Add following keys to add ADFS domain as trusted domain:

      HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\AAD\AuthTrustedDomains\https://ADFS domain/HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\AAD\AuthTrustedDomains\https://ADFS domain

      Note

      Add two keys with and without “/” at the end of ADFS domain.

   2. ii.To enable Modern auth via ADFS in Outlook on Windows add following REG_DWORD value in HKCU\SOFTWARE\Microsoft\Office\16.0\Common\Identity\:

      Name	Value
      EnableExchangeOnPremModernAuth	1

      For ease of deployment, these registry changes can be configured using Group Policy. If Group Policy isn't used by your organization, users have to configure their registry manually (or with a script you provide).

Create Authentication Policies for End Users

It's possible that all users in your organization don’t have email clients that support Modern authentication using ADFS. In this scenario, we recommend that you enable Modern auth for users who have supported clients and block Modern auth users who don't.

To enable Modern auth for a set of users and block Modern auth for your remaining users, you need to create at least two authentication policies:

• Org-wide policy to block Modern auth by default.
• Second policy to selectively allow Modern auth for some users.

Create organization-level policy to block Modern auth by default

After Modern auth is enabled, all Outlook clients will try to use OAuth tokens, but some clients (for example, Outlook on Mac) can fetch OAuth tokens only from Azure Active Directory. Thus, if Modern auth is enabled, these clients won't be able to connect.

To avoid this scenario, you can set an organization-level policy to disable Modern auth. In the example below, we create a new authentication policy called Block Modern auth.

New-AuthenticationPolicy "Block Modern auth" -BlockModernAuthWebServices -BlockModernAuthActiveSync -BlockModernAuthAutodiscover -BlockModernAuthImap -BlockModernAuthMapi -BlockModernAuthOfflineAddressBook -BlockModernAuthPop -BlockModernAuthRpc

This policy can be set at Org level using the following command.

Set-OrganizationConfig -DefaultAuthenticationPolicy "Block Modern auth"

Create user-level authentication policy to enable Modern auth

Next, create a second authentication policy that enables Modern auth. All users with a supported Outlook client are assigned this authentication policy to enable their client to use Modern auth.

In the example below, we create a new authentication called Allow Modern auth using following command:

New-AuthenticationPolicy "Allow Modern auth"

Configure Exchange Server to use ADFS OAuth tokens

1. Verify if oauth is enabled on the following virtual directories. If not enabled, do enable oauth in all these virtual directories:

   Get-MapiVirtualDirectory -Server <ExchangeServerName> | fl *auth*Get-WebServicesVirtualDirectory -Server <ExchangeServerName> | fl *auth*Get-OabVirtualDirectory -Server <ExchangeServerName> | fl *auth*Get-AutodiscoverVirtualDirectory -Server <ExchangeServerName> | fl *auth*

2. Run:

   New-AuthServer -Type ADFS -Name MyADFSServer -AuthMetadataUrl https://<adfs server FQDN>/FederationMetadata/2007-06/FederationMetadata.xml

   This is required to create a new auth server object in Exchange Server for ADFS. Auth server objects are a list of trusted issuers. Only OAuth tokens from these issuers are accepted.

3. Run:

   Set-AuthServer -Identity MyADFSServer -IsDefaultAuthorizationEndpoint $true

   Set the Auth server we just added as the DefaultAuthorizationEndpoint. When advertising the Modern auth header, Exchange Server advertises the auth URL of the DefaultAuthorizationEndpoint. This is how clients know which endpoint to use for authentication.

4. We need to run this command to enable Modern Auth at organization level:

   Set-OrganizationConfig -OAuth2ClientProfileEnabled $true

5. Enable Modern auth for users with supported clients by assigning the Allow Modern auth authentication policy:

   Set-User -Identity User -AuthenticationPolicy "Allow Modern auth"

Verify Modern auth flow

Once configured correctly, users experience the ADFS login prompt when they connect to an Exchange server.

Effect on other clients when Modern auth is enabled for a user

Users enabled for Modern auth that have multiple clients (for example, Outlook on Windows and Outlook mobile) will have different experiences for each client. Here's a summary of how clients behave when Modern auth is enabled.

Effect on OWA/ECP when Modern auth is enabled for other clients

Customers may or may not be using ADFS claims-based authentication for Outlook on the web. The steps mentioned above are required to enabled OAuth for other clients, and doesn't affect how OWA/ECP is configured.

Use AD FS claims-based authentication with Outlook on the web

Wait time after change authentication policy

After changing the authentication policy to allow Modern auth or block legacy auth:

• Wait 30 minutes for new policies to be read by front-end servers

  or

• Perform an IIS reset on all front-end servers.

Migrating to Hybrid Modern Auth after using enabling Modern auth for Exchange Server

Customers using Modern auth with ADFS that later decides to configure Exchange Hybrid should move to Hybrid Modern Auth. Detailed steps to migrate will be added to a future version of this document.

Renewing certificates

Evaluate current certificate configuration

When it comes to client connections to Exchange Server, the certificate that should be evaluated is the one bound to the Frontend IIS Site. For an ADFS server, ensuring that all certificates returned in Get-AdfsCertificate are current is ideal.

1. To identify the relevant certificate on an Exchange Server, perform the following within Exchange Management Shell:

   Import-Module WebAdministration(Get-ChildItem IIS:SSLBindings | Where-Object {($_.Sites -ne $null) -and ($_.Port -eq "443")}).Thumbprint | ForEach-Object {Get-ExchangeCertificate $_ | Where-Object {$_.Services -Match "IIS"} | ft Thumbprint, Services, RootCAType, Status, NotAfter, Issuer -AutoSize -Wrap} 

2. To review active certificates on an ADFS Server, perform the following within PowerShell:

   Get-AdfsCertificate | ft CertificateType, Thumbprint, Certificate -AutoSize -Wrap

Update certificates on Exchange Server

If its been found that the Exchange certificate needs to be updated for client connectivity, a new certificate must be issued and imported onto the Exchange Servers. Afterwards, the certificate should be enabled for IIS at minimum. Evaluate if other services should be enabled for the new certificate based on your configuration.

Below is a sample on creating, completing, enabling, and importing a new certificate across all servers based on the existing certificate within the Exchange Management Shell:

1. Generate a new certificate request within the Exchange Management Shell based on your existing certificate:

   $txtrequest = Get-ExchangeCertificate <Thumbprint> | New-ExchangeCertificate -GenerateRequest -PrivateKeyExportable $true

2. Stage a variable containing the desired output path of your new certificate request:

   $requestFile = "C:\temp\CertRequest.req"

3. Create the certificate request file:

   [System.IO.File]::WriteAllBytes($requestFile, [System.Text.Encoding]::Unicode.GetBytes($txtrequest))

   Note

   The folder path for the certificate request must already exist.

4. Share the request file with your Certificate Authority (CA). The steps required to get a completed certificate varies based on your CA.

   Note

   .p7b is the preferred format for the completed request.

5. Stage a variable containing the full path of the completed request:

   $certFile = "C:\temp\ExchangeCert.p7b"

6. Import the request onto the server that originally generated the request:

   Import-ExchangeCertificate -FileData ([System.IO.File]::ReadAllBytes($certFile)) -PrivateKeyExportable $true

7. Stage variable for the password to protect the completed certificate:

   $pw = Read-Host -AsSecureString

8. Export the certificate Binary into a variable:

   $binCert = Export-ExchangeCertificate <Thumbprint> -BinaryEncoded

9. Stage variable for the desired output path of the completed certificate:

   $certificate = "\\$env:computername\c$\temp\CompletedExchangeCert.pfx"

10. Export the completed request to be imported on other servers:

    [System.IO.File]::WriteAllBytes($certificate, $binCert.FileData)

11. Enable the services that should be bound to the certificate:

    Enable-ExchangeCertificate <Thumbprint> -Services IIS 

    Note

    You may need to add more services to the above sample based on your previous certificates configuration.

12. Validate the certificate is working as intended by directing a client to the server for all client namespaces with a host file.

13. Import the Exchange certificate on all other Exchange servers:

    Import-ExchangeCertificate -PrivateKeyExportable $true -FileData ([System.IO.File]::ReadAllBytes($certificate)) -Password $pw -Server <Server-Name>

    Note

    Including the -PrivateKeyExportable parameter is optional when importing to other Exchange servers.

14. Enable the Exchange certificate for needed Exchange services on all other Exchange servers:

    Enable-ExchangeCertificate <Thumbprint> -Services IIS -Server <Server-Name>

    Note

    You may need to add more services to the above sample based on your previous certificates configuration.

Update certificate on ADFS

Depending on the certificate type that requires update on ADFS determines if you need to follow the steps described below.

Service-Communications certificate

This sample provides the PowerShell required to import a certificate in .pfx format, such as the one generated by following the Exchange Server certificate steps. Ensure you're logged on the primary ADFS server.

1. Stage a variable containing the password for the certificate:

   $pw = Read-Host -AsSecureString

2. Stage a variable containing the full path for the certificate:

   $certificate = "\\E2k19-1\c$\temp\CompletedExchangeCert.pfx"

3. Import the certificate into the personal store of the LocalMachine:

   Import-PfxCertificate -FilePath $certificate -CertStoreLocation Cert:\LocalMachine\my -Password $pw

4. Update the Service-Communications certificate:

   Set-AdfsSslCertificate -Thumbprint <Thumbprint>

Token-Signing and Token-Decryption certificates

Follow the steps outlined in the Obtain and Configure TS and TD Certificates for AD FS documentation.