Office
Sign in

How to configure Exchange Server on-premises to use Hybrid Modern Authentication

Hybrid Modern Authentication (HMA), is a method of identity management that offers more secure user authentication and authorization, and is available for Exchange server on-premises hybrid deployments.

FYI

Before we begin, I call:

  • Hybrid Modern Authentication > HMA

  • Exchange on-premises > EXCH

  • Exchange Online > EXO

Also, if a graphic in this article has an object that's 'grayed-out' or 'dimmed' that means the element shown in gray is not included in HMA-specific configuration.

Enabling Hybrid Modern Authentication

Turning HMA on means:

  1. Being sure you meet the prereqs before you begin.

    1. Since many prerequisites are common for both Skype for Business and Exchange, see the overview article for your pre-req checklist. Do this before you begin any of the steps in this article.

  2. Adding on-premises web service URLs as Service Principal Names (SPNs) in Azure AD.

  3. Ensuring all Virtual Directories are enabled for HMA

  4. Checking for the EvoSTS Auth Server object

  5. Enabling HMA in EXCH.

Note  Does your version of Office support MA? Check here.

Make sure you meet all the pre-reqs

Since many prerequisites are common for both Skype for Business and Exchange, see the overview article for your pre-req checklist. Do this before you begin any of the steps in this article.

Add on-premises web service URLs as SPNs in Azure AD

Run the commands that assign your on-premises web service URLs as Azure AD SPNs. SPNs are used by client machines and devices during authentication and authorization. All the URLs that might be used to connect from on-premises to Azure Active Directory (AAD) must be registered in AAD (this includes both internal and external namespaces).

First, gather all the URLs that you need to add in AAD. Run these commands on-premises:

  • Get-MapiVirtualDirectory | FL server,*url*

  • Get-WebServicesVirtualDirectory | FL server,*url*

  • Get-ActiveSyncVirtualDirectory | FL server,*url*

  • Get-OABVirtualDirectory | FL server,*url*

Ensure the URLs clients may connect to are listed as HTTPS service principal names in AAD.

  1. First, connect to AAD with these instructions.

  2. For your Exchange related URLs, type the following command:

  • Get-MsolServicePrincipal -AppPrincipalId 00000002-0000-0ff1-ce00-000000000000  | select -ExpandProperty ServicePrincipalNames

Take note of (and screenshot for later comparison) the output of this command, which should include an https://autodiscover.yourdomain.com and https://mail.yourdomain.com URL, but mostly consist of SPNs that begin with 00000002-0000-0ff1-ce00-000000000000/. If there are https:// URLs from your on-premises that are missing we will need to add those specific records to this list.

3. If you don't see your internal and external MAPI/HTTP, EWS, ActiveSync, OAB and Autodiscover records in this list, you must add them using the command below (the example URLs are 'mail.corp.contoso.com' and 'owa.contoso.com', but you'd replace the example URLs with your own):

  • $x= Get-MsolServicePrincipal -AppPrincipalId 00000002-0000-0ff1-ce00-000000000000

  • $x.ServicePrincipalnames.Add("https://mail.corp.contoso.com/")

  • $x.ServicePrincipalnames.Add("https://owa.contoso.com/")

  • $x.ServicePrincipalnames.Add("https://eas.contoso.com/")

  • Set-MSOLServicePrincipal -AppPrincipalId 00000002-0000-0ff1-ce00-000000000000 -ServicePrincipalNames $x.ServicePrincipalNames

4. Verify your new records were added by running the Get-MsolServicePrincipal command from step 2 again, and looking through the output. Compare the list / screenshot from before to the new list of SPNs (you may also screenshot the new list for your records). If you were successful, you will see the two new URLs in the list. Going by our example, the list of SPNs will now include the specific URLs https://mail.corp.contoso.com and https://owa.contoso.com.

Verify Virtual Directories are Properly Configured

Now verify OAuth is properly enabled in Exchange on all of the Virtual Directories Outlook might use by running the following commands;

  • Get-MapiVirtualDirectory | FL server,*url*,*auth*

  • Get-WebServicesVirtualDirectory | FL server,*url*,*oauth*

  • Get-OABVirtualDirectory | FL server,*url*,*oauth*

  • Get-AutoDiscoverVirtualDirectory | FL server,*oauth*

Check the output to make sure OAuth is enabled on each of these VDirs, it will look something like this (and the key thing to look at is 'OAuth');

[PS] C:\Windows\system32>Get-MapiVirtualDirectory | fl server,*url*,*auth*

Server                        : EX1

InternalUrl                   : https://mail.contoso.com/mapi

ExternalUrl                   : https://mail.contoso.com/mapi

IISAuthenticationMethods      : {Ntlm, OAuth, Negotiate}

InternalAuthenticationMethods : {Ntlm, OAuth, Negotiate}

ExternalAuthenticationMethods : {Ntlm, OAuth, Negotiate}

If OAuth is missing from any server and any of the four virtual directories then you need to add it using the relevant commands before proceeding.

Confirm the EvoSTS Auth Server Object is Present

Return to the on-premises Exchange Management Shell for this last command. Now you can validate that your on-premises has an entry for the evoSTS authentication provider:

  • Get-AuthServer | where {$_.Name -eq "EvoSts"}

Your output should show an AuthServer of the Name EvoSts and the 'Enabled' state should be True. If you don't see this, you should download and run the most recent version of the Hybrid Configuration Wizard.

Important  If you're running Exchange 2010 in your environment, the EvoSTS authentication provider won't be created.

Enable HMA

Run the following command in the Exchange Management Shell, on-premises

  • Set-AuthServer -Identity EvoSTS -IsDefaultAuthorizationEndpoint $true

  • Set-OrganizationConfig -OAuth2ClientProfileEnabled $true

Verify

Once you enable HMA, a client's next login will use the new auth flow. Note that just turning on HMA won't trigger a re-authentication for any client. The clients re-authenticate based on the lifetime of the auth tokens and/or certs they have.

You should also hold down the CTRL key at the same time you right click the icon for the Outlook client (also in the Windows Notifications tray) and click 'Connection Status'. Look for the client's SMTP address against an 'Authn' type of 'Bearer*', which represents the bearer token used in OAuth.

Note  Need to configure Skype for Business with HMA? You'll need two articles: One that lists supported topologies, and one that shows you how to do the configuration.

Link back to the Modern Authentication overview.

Expand your Office skills
Explore training
Get new features first
Join Office Insiders

Was this information helpful?

Thank you for your feedback!

Thank you for your feedback! It sounds like it might be helpful to connect you to one of our Office support agents.

×