Enabling Modern Auth in Exchange on-premises

Article
11/26/2024

Overview

Starting with 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.

Modern Auth in Exchange Server 2019 shouldn't be confused with Hybrid Modern Authentication (HMA), which uses Microsoft Entra ID for Modern Authentication. In fact, HMA is still the recommended method to enable Modern Auth for all on-premises and cloud users in an Exchange Hybrid configuration. This new feature enables the use of Modern Auth for organizations who do not have Microsoft Entra ID or are not 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. Exchange Server validates these access tokens 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 previous 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. It's unsupported to install and configure the ADFS role on an Exchange Server. For more information, see Plan Your AD FS Deployment Topology.

You may also need Web Application Proxy Server (on Windows Server 2019 or later) to enable client access from outside corporate network. Read the (Optional) Configure Web Application Proxy can be configured for Extranet Access section for more details.

Client prerequisites

To utilize Modern Auth, users require client applications, such as Outlook or other native operating system clients, which are compatible with Modern Auth via ADFS.

Outlook on Windows

Support for Modern Auth via ADFS is available in the following versions of Microsoft Outlook for Windows. The Microsoft Outlook Windows client, starting from build number 16.0.17628.10000, utilizes the latest MSAL library for authentication. To ensure you are using the most up-to-date authentication stack, it is recommended to install the latest version:

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)	Yes	2402	17328.20184
Semi-Annual Enterprise Channel	Yes	2402	17328.20452

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)	No	N/A	N/A
Outlook 2024 (Retail)	Yes	2410	18129.20158
Outlook 2024 (Volume)	Yes	2408	17932.20162

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

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.

Apple platforms

Support for Modern Auth via ADFS is also available in the Apple Mail app on macOS Sequoia and on iOS 17.6.1 or later.

Protocols that work with ADFS Modern Auth

The following table outlines the protocols that can be accessed by utilizing ADFS Modern Auth tokens. We're continuously working to add ADFS Modern Auth support to more Exchange Server protocols.

Protocol	ADFS Modern Auth Supported
MAPI over HTTP (MAPI/HTTP)	Yes
Outlook Anywhere (RPC/HTTP)	No
Exchange Active Sync (EAS)	Yes
Exchange Web Services (EWS)	Yes
Outlook on the Web (OWA)	Yes (claims-based authentication)
Exchange Admin Center (ECP)	Yes (claims-based authentication)
Offline Address Book (OAB)	Yes
IMAP	No
POP	No

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 approach ensures that initial client connections to Exchange 2019 use OAuth, and proxied connections to Exchange Server 2016 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.

BlockModernAuthActiveSync
BlockModernAuthAutodiscover
BlockModernAuthImap
BlockModernAuthMapi
BlockModernAuthOfflineAddressBook
BlockModernAuthPop
BlockModernAuthRpc
BlockModernAuthWebServices

After installing CU13 or later, any pre-existing auth policies (including the default authentication policy) have the parameters disabled. That means that if you're already using HMA you don't need to change the pre-existing auth policies.

No new authentication policy required for Exchange Hybrid

Existing Exchange Hybrid configurations should use Hybrid Modern Auth (HMA). Hybrid installations using HMA can leave the values of the BlockModernAuth* parameters at 0 to continue using HMA. The steps outlined for setting up Modern Auth with ADFS are only relevant for organizations who aren't using Exchange Hybrid and are purely on-premises.

Set up Active Directory Federation Services (ADFS)

You need to install and configure ADFS in the environment to allow Exchange clients to use Forms authentication (OAuth) to connect to Exchange Server. Refer to the Checklist: Setting Up a Federation Server to assist with your ADFS configuration.

The ADFS feature can be installed by running the following command from an elevated PowerShell window on the new server that becomes the ADFS server:

Install-WindowsFeature ADFS-Federation -IncludeManagementTools

Certificate requirements for ADFS configuration in Exchange Server Organization

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

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.
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're 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 process includes the signing of published federation metadata and artifact resolution requests. You can have multiple token-signing certificates configured in the ADFS 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 ADFS 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 certificate 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 in the Deploy an ADFS server and Configure and test the ADFS server documentation. Ensure that the federation metadata URL can be accessed in a web browser from both the Exchange server and at least one client machine.

The URL uses this syntax: https://<FederationServiceName>/federationmetadata/2007-06/federationmetadata.xml

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

Configure Authentication Method in ADFS

To use Modern Auth in Outlook on Windows, you need to configure the Primary Authentication Methods. We recommend choosing Forms Authentication for both Extranet and Intranet. This configuration can be done by running the following commands from a PowerShell window on the ADFS server:

Set-AdfsGlobalAuthenticationPolicy -PrimaryIntranetAuthenticationProvider FormsAuthentication
Set-AdfsGlobalAuthenticationPolicy -PrimaryExtranetAuthenticationProvider FormsAuthentication

Choose appropriate SSO Lifetime

Choose an appropriate Single Sign-On (SSO) lifetime so end users aren't required to frequently reauthenticate. To validate the current SSO lifetime configuration, open a new PowerShell window on the ADFS server and execute the following command:

Get-AdfsProperties | Format-List SsoLifetime, PersistentSsoLifetimeMins, KmsiLifetimeMins, DeviceUsageWindowInDays, KmsiEnabled, PersistentSsoEnabled, BrowserSsoEnabled

Use the Set-AdfsProperties cmdlet to configure the appropriate values for SsoLifetime, PersistentSsoLifetimeMins, KmsiLifetimeMins, and DeviceUsageWindowInDays. These settings should be adjusted to enable SSO and define its expiry. Depending on the SSO mode, such as Keep Me Signed In (KMSI) or Device registration, you may also need to enable KsmiEnabled and PersistentSsoEnabled. More details about ADFS SSO can be found in the AD FS 2016 Single Sign On Settings documentation.

Configure device registration in ADFS

It's recommended to enable the Device Registration feature in ADFS to benefit from an improved SSO experience. To enable Device Registration, follow the steps outlined in the Configure a federation server with Device Registration Service documentation.

Next, complete all the steps to configure Device Registration Service Discovery and the Device Registration Discovery Server SSL certificate, as described in the Configuring Device Registration documentation.

To use device registration, end users must join their device to a Workplace. More details can be found in the following documentations:

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.

Configure KSMI in ADFS

If you prefer not to use Device Registration or are unable to do so, you can enable the Keep Me Signed In feature instead. ADFS then creates a persistent cookie immediately after user authentication, eliminating the need for reauthentication in subsequent sessions, provided the cookie remains valid.

The expiration time of the refresh token is equal the persistent SSO cookie's lifetime for Keep me signed in. The persistent SSO cookie lifetime is one day by default with maximum of seven days. Otherwise, refresh token lifetime equals session SSO cookie lifetime (8 hours by default). More information about KSMI can be found in the AD FS single sign-on settings documentation.

KMSI is disabled by default and can be enabled by setting the ADFS property KmsiEnabled to True. Make sure to run the following steps from a PowerShell window on your ADFS server:

Set-AdfsProperties -EnableKmsi $true

With KMSI disabled, the default single sign-on period is 8 hours. The single sign-on period can be configured using the property SsoLifetime. The property is measured in minutes, so its default value is 480:

Set-AdfsProperties -SsoLifetime <LifetimeInMinutes>

With KMSI enabled, the default single sign-on period is 24 hours. The single sign-on period with KMSI enabled can be configured using the property KmsiLifetimeMins. The property is measured in minutes, so its default value is 1440:

Set-AdfsProperties -KmsiLifetimeMins <LifetimeInMinutes>

Create the ADFS Outlook Application Group

If this is your first time configuring ADFS Modern Authentication in Exchange on-premises, please follow the steps in this section of the guide. If you have an existing ADFS Modern Authentication configuration that was set up before support for clients other than Microsoft Outlook for Windows, refer to the steps in the Update the existing ADFS Outlook Application Group section of this documentation. The following PowerShell commands must be executed from a PowerShell window on your ADFS server. If you don't plan to use iOS and macOS applications, such as the native Apple Mail app, you can skip creating the ADFS native client application for iOS and macOS. However, we recommend creating them for the sake of completeness.

First, we're going to create the ADFS Application Group:

New-AdfsApplicationGroup -Name "Outlook" -ApplicationGroupIdentifier "Outlook" -Disabled:$false

Next we create three more Scopes - EAS.AccessAsUser.All, EWS.AccessAsUser.All and offline_access:

Add-AdfsScopeDescription -Name "EAS.AccessAsUser.All" -Description "EAS scope"
Add-AdfsScopeDescription -Name "EWS.AccessAsUser.All" -Description "EWS scope"
Add-AdfsScopeDescription -Name "offline_access" -Description "Offline Access"

Now, we're creating two Native Client Applications - Outlook - Native application and iOS and macOS - Native mail application:

Add-AdfsNativeClientApplication -Name "Outlook - Native application" -ApplicationGroupIdentifier "Outlook" -Identifier "d3590ed6-52b3-4102-aeff-aad2292ab01c" -RedirectUri @("ms-appx-web://Microsoft.AAD.BrokerPlugin/d3590ed6-52b3-4102-aeff-aad2292ab01c","msauth.com.microsoft.Outlook://auth","urn:ietf:wg:oauth:2.0:oob")
Add-AdfsNativeClientApplication -Name "iOS and macOS - Native mail application" -ApplicationGroupIdentifier "Outlook" -Identifier "f8d98a96-0999-43f5-8af3-69971c7bb423" -RedirectUri @("com.apple.mobilemail://oauth-redirect","com.apple.preferences.internetaccounts://oauth-redirect/","com.apple.Preferences://oauth-redirect/")

As a next step, we create Web Api Applications. We create one application per URI that is used in your Exchange Server environment. If you use, for example, autodiscover.contoso.com and mail.contoso.com, you must create two Web Api Applications. Make sure to replace the URIs in the following example with the URIs, which you use in your setup. It's important to make sure all client-facing URIs are covered. Include the trailing / and make sure that the URIs start with https://:

# Replace the URIs with your URIs
$exchangeServerServiceFqdns = @("https://autodiscover.contoso.com/","https://mail.contoso.com/")

$issuanceTransformRules = @"
@RuleName = "ActiveDirectoryUserSID"
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid"]
 => issue(claim = c);

@RuleName = "ActiveDirectoryUPN"
c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"]
 => issue(claim = c);

@RuleName = "AppIDACR"
 => issue(Type = "appidacr", Value = "2");

@RuleName = "SCP"
 => issue(Type = "scp", Value = "user_impersonation");

@RuleName = "SCPEAS"
 => issue(Type = "scp", Value = "EAS.AccessAsUser.All");

@RuleName = "SCPEWS"
 => issue(Type = "scp", Value = "EWS.AccessAsUser.All");

@RuleName = "offlineaccess"
 => issue(Type = "scp", Value = "offline_access");
"@
foreach ($fqdn in $exchangeServerServiceFqdns) {
    Add-AdfsWebApiApplication -Name "Outlook - Web API ($((New-Guid).ToString("N")))" -ApplicationGroupIdentifier "Outlook" -Identifier $fqdn -IssuanceTransformRules $issuanceTransformRules -AccessControlPolicyName "Permit Everyone"
}

As a last step, we add the client permissions for all of the Native Client Applications in the existing Web Api Applications:

$clientRoleIdentifier = @("f8d98a96-0999-43f5-8af3-69971c7bb423","d3590ed6-52b3-4102-aeff-aad2292ab01c")
(Get-AdfsWebApiApplication -ApplicationGroupIdentifier "Outlook") | ForEach-Object {
    [string]$serverRoleIdentifier = $_.Identifier
    foreach ($id in $clientRoleIdentifier) {
        Grant-AdfsApplicationPermission -ClientRoleIdentifier $id -ServerRoleIdentifier $serverRoleIdentifier -ScopeNames "winhello_cert","email","profile","vpn_cert","logon_cert","user_impersonation","allatclaims","offline_access","EAS.AccessAsUser.All","EWS.AccessAsUser.All","openid","aza"
    }
}

Update the existing ADFS Outlook Application Group

Important

Skip the steps in this section if you don't have an existing ADFS Outlook Application Group, which was configured before support for clients other than Microsoft Outlook for Windows was introduced.

If you have an existing ADFS Outlook Application Group configuration, which was set up before support for clients other than Microsoft Outlook for Windows was introduced, follow the steps here to enable support for other platforms. The following PowerShell commands must be executed from a PowerShell window on your ADFS server.

First we're creating three extra Scopes - EAS.AccessAsUser.All, EWS.AccessAsUser.All and offline_access:

Add-AdfsScopeDescription -Name "EAS.AccessAsUser.All" -Description "EAS scope"
Add-AdfsScopeDescription -Name "EWS.AccessAsUser.All" -Description "EWS scope"
Add-AdfsScopeDescription -Name "offline_access" -Description "Offline Access"

Now, we're creating a new Native Client Applications - iOS and macOS - Native mail application:

Add-AdfsNativeClientApplication -Name "iOS and macOS - Native mail application" -ApplicationGroupIdentifier "Outlook" -Identifier "f8d98a96-0999-43f5-8af3-69971c7bb423" -RedirectUri @("com.apple.mobilemail://oauth-redirect","com.apple.preferences.internetaccounts://oauth-redirect/","com.apple.Preferences://oauth-redirect/")

We update the existing Native Client Application - Outlook - Native application. Make sure to replace the TargetName with the target name that you're using in the existing configuration:

Set-AdfsNativeClientApplication -TargetName "Outlook - Native application" -RedirectUri @("ms-appx-web://Microsoft.AAD.BrokerPlugin/d3590ed6-52b3-4102-aeff-aad2292ab01c","msauth.com.microsoft.Outlook://auth","urn:ietf:wg:oauth:2.0:oob")

As a next step, we must create one Web Api Application for each Identifier (URI) which is used in your Exchange Server environment and exists in your current ADFS Modern Authentication configuration:

$duplicateFqdnHashSet = New-Object System.Collections.Generic.HashSet[string]
$issuanceTransformRules = @"
@RuleName = "ActiveDirectoryUserSID"
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid"]
 => issue(claim = c);

@RuleName = "ActiveDirectoryUPN"
c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"]
 => issue(claim = c);

@RuleName = "AppIDACR"
 => issue(Type = "appidacr", Value = "2");

@RuleName = "SCP"
 => issue(Type = "scp", Value = "user_impersonation");

@RuleName = "SCPEAS"
 => issue(Type = "scp", Value = "EAS.AccessAsUser.All");

@RuleName = "SCPEWS"
 => issue(Type = "scp", Value = "EWS.AccessAsUser.All");

@RuleName = "offlineaccess"
 => issue(Type = "scp", Value = "offline_access");
"@
(Get-AdfsWebApiApplication -ApplicationGroupIdentifier "Outlook") | ForEach-Object {
    if ($_.Identifier.Count -gt 1) {
        Write-Host "[+] More than one identifier was found in Web Api Application: $($_.Name)" -ForegroundColor Yellow
        $_.Identifier | Select-Object -Skip 1 | ForEach-Object {
            Write-Host "[+] Identifier $_ must be added to a new Web Api Application and will now be removed from the existing one" -ForegroundColor Yellow
            [void]$duplicateFqdnHashSet.Add($_)
        }

        Set-AdfsWebApiApplication -TargetName $_.Name -Identifier ($_.Identifier)[0] -IssuanceTransformRules $issuanceTransformRules -AccessControlPolicyName "Permit Everyone"
    }
}

foreach($identifier in $duplicateFqdnHashSet) {
    Write-Host "[+] Creating a new Web Api Application for: $identifier" -ForegroundColor Yellow
    Add-AdfsWebApiApplication -Name "Outlook - Web API ($((New-Guid).ToString("N")))" -ApplicationGroupIdentifier "Outlook" -Identifier $identifier -IssuanceTransformRules $issuanceTransformRules -AccessControlPolicyName "Permit Everyone"
    Write-Host "[+] Done!`r`n" -ForegroundColor Green
}

As a last step, we add the client permissions for all of the Native Client Applications in the existing Web Api Applications:

$clientRoleIdentifier = @("f8d98a96-0999-43f5-8af3-69971c7bb423","d3590ed6-52b3-4102-aeff-aad2292ab01c")
$requiredScopes = @("winhello_cert","email","profile","vpn_cert","logon_cert","user_impersonation","allatclaims","offline_access","EAS.AccessAsUser.All","EWS.AccessAsUser.All","openid","aza")

(Get-AdfsWebApiApplication -ApplicationGroupIdentifier "Outlook") | ForEach-Object {
    [string]$serverRoleIdentifier = $_.Identifier
    Write-Host "[+] Processing Server Role: $serverRoleIdentifier" -ForegroundColor Yellow
    foreach ($id in $clientRoleIdentifier) {
        Write-Host "[+] Processing Client Role: $id" -ForegroundColor Yellow
        $permissionEntry = Get-AdfsApplicationPermission | Where-Object { $_.ClientRoleIdentifier -eq $id -and $_.ServerRoleIdentifier -eq $serverRoleIdentifier }
        if ($null -eq $permissionEntry) {
            Write-Host "[+] No Application Permission found for Client Role: $id - Server Role: $serverRoleIdentifier" -ForegroundColor Yellow
            Grant-AdfsApplicationPermission -ClientRoleIdentifier $id -ServerRoleIdentifier $serverRoleIdentifier -ScopeNames $requiredScopes
        } else {
            Write-Host "[+] Application Permission found - validating Scopes" -ForegroundColor Yellow
            $missingScopesList = New-Object System.Collections.Generic.List[string]
            $requiredScopes | ForEach-Object {
                if ($_ -in $permissionEntry.ScopeNames) {
                    Write-Host "[+] Scope: $_ is already set!" -ForegroundColor Green
                } else {
                    Write-Host "[+] Scope: $_ is missing and must be added" -ForegroundColor Yellow
                    $missingScopesList.Add($_)
                }
            }

            if ($missingScopesList.Count -ge 1) {
                Write-Host "[+] The following Scopes will be added: $([string]::Join(", ", $missingScopesList))" -ForegroundColor Yellow
                Set-AdfsApplicationPermission -TargetClientRoleIdentifier $id -TargetServerRoleIdentifier $serverRoleIdentifier -AddScope $missingScopesList
                Write-Host "[+] Done!`r`n" -ForegroundColor Green
            } else {
                Write-Host "[+] There is nothing to do!`r`n" -ForegroundColor Green
            }
        }
    }
}

Remove existing ADFS Outlook Application Group

Caution

Following the steps in this section removes the existing ADFS Outlook Application Group configuration.

If you have an existing ADFS Outlook Application Group configuration and you want to remove it, follow the steps here to delete the existing configuration. All of the following PowerShell commands must be executed from a PowerShell window on your ADFS server.

First, we're going to delete the ADFS Application Group:

Remove-AdfsApplicationGroup -TargetApplicationGroupIdentifier "Outlook"

As a last step, we delete the custom Scopes which were added:

Remove-AdfsScopeDescription -TargetName "EAS.AccessAsUser.All"
Remove-AdfsScopeDescription -TargetName "EWS.AccessAsUser.All"
Remove-AdfsScopeDescription -TargetName "offline_access"

(Optional) Configure 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.

(Optional) Configure MFA for client access

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
Configure Access Control Policy requiring MFA.
- Access Control Policies in Windows Server 2016 AD FS

Create Authentication Policies for End Users

It's possible that not all users in your organization have email clients that support Modern Auth via ADFS. In this scenario, we recommend enabling Modern Authentication for users with supported clients and blocking it for those users without.

To enable Modern Authentication for a specific set of users and block it for the remaining users, you need to create at least two authentication policies.

Important

The new authentication policies become available as soon as the Active Directory is prepared by using the Exchange 2019 CU13 or later media.

An organization-wide policy to block Modern Authentication by default
A secondary policy to selectively allow Modern Authentication for specific users

The following PowerShell commands must be executed from an Exchange Management Shell (EMS) window on your Exchange server.

Create organization-level policy to block Modern Auth by default

Once Modern Authentication is enabled, all Outlook clients attempt to use OAuth tokens. However, some clients that are not compatible with ADFS Modern Authentication can only retrieve OAuth tokens from Microsoft Entra ID. So, these clients are unable to connect if Modern Authentication is enabled.

To prevent this scenario, you can implement an organization-wide policy to disable Modern Authentication. In the example, we create a new authentication policy named 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 Authentication. Assign this policy to all users with supported Outlook clients to allow their clients to use Modern Authentication.

In the example, 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

Verify if OAuth is enabled on the following virtual directories. If it's not enabled, do enable OAuth it for all these virtual directories:

Get-MapiVirtualDirectory | Format-List Server, *auth*
Get-WebServicesVirtualDirectory | Format-List Server, *auth*
Get-OabVirtualDirectory | Format-List Server, *auth*
Get-AutodiscoverVirtualDirectory | Format-List Server, *auth*
Get-ActiveSyncVirtualDirectory | Format-List Server, *auth*

The output appears as follows. The primary detail to focus on is OAuth, as previously mentioned:

Get-MapiVirtualDirectory | Format-List Server, *auth*

Server                        : EX1
IISAuthenticationMethods      : {Ntlm, OAuth, Negotiate}
InternalAuthenticationMethods : {Ntlm, OAuth, Negotiate}
ExternalAuthenticationMethods : {Ntlm, OAuth, Negotiate}

If OAuth is missing from any server or any of the five virtual directories, you need to add it using the relevant commands before proceeding: Set-MapiVirtualDirectory, Set-WebServicesVirtualDirectory, Set-OabVirtualDirectory, Set-AutodiscoverVirtualDirectory, and Set-ActiveSyncVirtualDirectory.

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.
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.
We need to run this command to enable Modern Auth at organization level:
```
Set-OrganizationConfig -OAuth2ClientProfileEnabled $true
```
Enable Modern auth for users with supported clients by assigning the Allow Modern Auth authentication policy:
```
Set-User -Identity User -AuthenticationPolicy "Allow Modern Auth"
```

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. Validate that your client supports ADFS Modern Auth. More details about the supported clients can be found in the Client prerequisites section.

Microsoft Windows

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

Create the following registry keys to make your ADFS domain a trusted domain. Make sure to add both keys with and without the / at the end of the ADFS domain:
- HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\AAD\AuthTrustedDomains\https://your-ADFS-domain/
- HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\AAD\AuthTrustedDomains\https://your-ADFS-domain
You can use PowerShell to create the registry keys or deploy them by the help of a Group Policy. Run the following commands from a PowerShell window on each client computer. Replace your-ADFS-domain with your ADFS domain.
```
New-Item -Path "HKLM:\SOFTWARE\Policies\Microsoft\AAD\AuthTrustedDomains" -Force
(Get-Item HKLM:).OpenSubKey("SOFTWARE\Policies\Microsoft\AAD\AuthTrustedDomains", $true).CreateSubKey("https://your-ADFS-domain/")
(Get-Item HKLM:).OpenSubKey("SOFTWARE\Policies\Microsoft\AAD\AuthTrustedDomains", $true).CreateSubKey("https://your-ADFS-domain")
```
To enable ADFS Modern Auth in Microsoft Outlook for Windows add the EnableExchangeOnPremModernAuth REG_DWORD value under HKCU\SOFTWARE\Microsoft\Office\16.0\Common\Identity\.

You can use PowerShell to create the registry value or deploy it via a Group Policy. Run the following command from a PowerShell window on each client computer.
```
Set-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Office\16.0\Common\Identity\" -Name "EnableExchangeOnPremModernAuth" -Value 1 -Type DWord
```

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

Users enabled for Modern Authentication who use multiple clients (for example, Outlook on Windows and Outlook Mobile) experience different behaviors across each client. In the following summary we describe the client behaviors when Modern Authentication is enabled, assuming Block Modern Auth is applied as the DefaultAuthenticationPolicy at the organization level.

Client	Behavior
Outlook for Windows (Classic)	Uses Modern Auth by default.
Outlook for Windows (New)	Tries to use Modern Auth but fails.
Outlook for Mac	Tries to use Modern Auth but will fail; support coming later.
Outlook iOS	Falls back to Basic auth.
Outlook Android	Falls back to Basic auth.
iOS Mail app	Uses Modern Auth.
macOS Mail app	Uses Modern Auth.
Gmail app	Falls back to Basic auth.
OWA/ECP	Doesn't use authentication policy. Depending on how it's configured, it uses 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	Uses Basic auth.

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

You may or may not be using ADFS claims-based authentication for Outlook on the web. The steps mentioned 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

If you're using Modern Auth with ADFS and later decide to configure Exchange Hybrid, you should transition to Hybrid Modern Auth. Detailed migration steps will be included in 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.

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}

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 it's 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.

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

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

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

Stage a variable containing the desired output path of your new certificate request:
```
$requestFile = "C:\temp\CertRequest.req"
```
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.
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.
Stage a variable containing the full path of the completed request:
```
$certFile = "C:\temp\ExchangeCert.p7b"
```

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

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

Stage variable for the password to protect the completed certificate:
```
$pw = Read-Host "Enter password" -AsSecureString
```

Export the certificate Binary into a variable:

$binCert = Export-ExchangeCertificate <Thumbprint> -BinaryEncoded

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

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

Export the completed request to be imported on other servers:

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

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 previous sample based on your previous certificates configuration.
Validate the certificate is working as intended by directing a client to the server for all client namespaces with a host file.
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.
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 previous 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.

Stage a variable containing the password for the certificate:
```
$pw = Read-Host "Enter password" -AsSecureString
```

Stage a variable containing the full path for the certificate:

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

Import the certificate into the personal store of the LocalMachine:

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

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.

Share via