Enabling Modern Auth in Exchange on-premises

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 Microsoft Entra ID 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 Microsoft Entra ID 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.

Exchange Configuration	Is this feature applicable?	Remarks
On-premises Exchange organization with only Exchange Server 2019	Yes	N/A
On-premises Exchange organization with mix of Exchange Server 2019, Exchange Server 2016, and Exchange Server 2013	No	Exchange Server 2013 is out of support.
On-premises Exchange organization with mix of Exchange Server 2019 and Exchange Server 2016	Yes	Only Exchange 2019 servers can be used as Front-End (Client Access) Servers.
Exchange Hybrid organization using HMA	No	HMA using Microsoft Entra ID is the preferred solution. Refer to the guidance on using new auth policies.
Exchange Hybrid organization without HMA	No	Use HMA with Microsoft Entra ID.

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.

Note

The ADFS role cannot be configured on an Exchange Server. For more information, see Plan Your AD FS Deployment Topology

Client Prerequisites

Outlook on Windows

Support for Modern Auth via ADFS is available in the following versions of Microsoft Outlook.

Outlook in Microsoft 365 Apps:

Channel	Supported	Version	Build (or later)
Insider Channel	Yes	2304	16327.20200
Current Channel	Yes	2304	16327.20214
Monthly Enterprise Channel	Yes	2304	16327.20324
Semi-Annual Enterprise Channel (Preview)	No	N/A	N/A
Semi-Annual Enterprise Channel	No	N/A	N/A

Outlook for Windows (volume license & retail):

Version	Supported	Version	Build (or later)
Outlook 2016 (Any version)	No	N/A	N/A
Outlook 2019 (Any version)	No	N/A	N/A
Outlook 2021 (Retail)	Yes	2304	16327.20214
Outlook 2021 (Volume license)	No	N/A	N/A

You can check the build number of your Office by following steps mentioned here.

Note

Support for other clients such as Outlook on Mac, Outlook mobile, iOS mail app, etc., will be added later.

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.

Note

Configuring Modern auth is supported only on Exchange Server 2019 CU13 and later.

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.

Note

The following steps to configure Modern auth using ADFS are applicable only for non-Exchange Hybrid (pure on-premises) customers.

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:

Common name (CN) in the certificate (in the Subject, Subject Alternative Name, or a wildcard certificate match)	Type	Required on servers	Comments
adfs.contoso.com enterpriseregistration.contoso.com	Issued by a CA	ADFS server, Web Application Proxy server (optional)	Federation servers use an SSL certificate to secure Web services traffic for SSL communication with clients and with federation server proxies. Because the SSL certificate must be trusted by client computers, we recommend that you use a certificate that is signed by a trusted CA. All certificates that you select must have a corresponding private key.
ADFS Token Signing - adfs.contoso.com	Self-signed or issue by a CA	ADFS server, Web Application Proxy server (optional)	A token-signing certificate is an X509 certificate. Federation servers use associated public/private key pairs to digitally sign all security tokens that they produce. This includes the signing of published federation metadata and artifact resolution requests. You can have multiple token-signing certificates configured in the AD FS Management snap-in to allow for certificate rollover when one certificate is close to expiring. By default, all the certificates in the list are published, but only the primary token-signing certificate is used by AD FS to actually sign tokens. All certificates that you select must have a corresponding private key. You can obtain a token-signing certificate by requesting one from an enterprise CA or a public CA or by creating a self-signed certificate.
mail.contoso.com autodiscover.contoso.com	Issued by a CA	Exchange servers, Web Application Proxy server (optional)	This is the typical certificate that's used to encrypt external client connections to Outlook on the web (and other Exchange services). For more information, see Certificate requirements for Exchange services.

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](/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/dn614658(v=ws.11).

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's 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:

Claim Rule Name	Custom Rule
ActiveDirectoryUserSID	c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid"] => issue(claim = c);
ActiveDirectoryUPN	c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"] => issue(claim = c);
AppIDACR	=> issue(Type = "appidacr", Value = "2");
SCP	=> issue(Type = "http://schemas.microsoft.com/identity/claims/scope", Value ="user_impersonation");

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. 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 Microsoft Entra ID. 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> | Format-List *auth*
   
   Get-WebServicesVirtualDirectory -Server <ExchangeServerName> | Format-List *auth*
   
   Get-OabVirtualDirectory -Server <ExchangeServerName> | Format-List *auth*
   
   Get-AutodiscoverVirtualDirectory -Server <ExchangeServerName> | Format-List *auth*
   

2. Run the following command:

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

   This command 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 the following command:

   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.

Note

The following table assumes that Block Modern auth is applied as DefaultAuthenticationPolicy at org level.

Client	Behavior
Outlook on Windows (new versions)	Uses Modern auth by default.
Outlook on Windows (old versions)	Will try to use Modern auth but will fail.
Outlook Mac	Will try to use Modern auth but will fail; support coming later.
Outlook iOS	Will fall back to Basic auth.
Outlook Android	Will fall back to Basic auth.
iOS Mail app	Will fall back to Basic auth.
Gmail app	Will fall back to Basic auth.
OWA/ECP	Doesn't use authentication policy. Depending on how it's configured, will use either Modern auth or Basic auth.
Windows Mail app	Doesn't fall back to Basic auth.
Thunderbird client	Doesn't fall back to basic auth.
PowerShell	Will use Basic auth.

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"} | Format-Table Thumbprint, Services, RootCAType, Status, NotAfter, Issuer -AutoSize -Wrap}
   

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

   Get-AdfsCertificate | Format-Table 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 "Enter password" -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 "Enter password" -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.

Note

Using the default self-signed certificate for Token-Signing in ADFS claims-based authentication for Outlook on the web requires the certificate to be installed on the Exchange Servers.