M365 Exchange Online | Set up OAuth migration endpoint for MRS

M365 Exchange Online | Set up OAuth migration endpoint for MRS

Configuration and Prerequisites Overview

The Exchange team announced on November 9, 2026, that the Mailbox Replication Service (MRS) in Microsoft 365 now supports OAuth when moving mailboxes between Exchange Server and Exchange Online. This applies to both hybrid and non-hybrid environments.

Previously, MRS authenticated with the MRS Proxy using Basic Authentication with the credentials stored in the migration endpoint. With OAuth, MRS instead authenticates using its own app identity in Microsoft Entra ID, and Exchange Server validates the token against a list of authorized entries.

Basic Authentication remains permitted. Microsoft explicitly describes OAuth as an optional alternative, not a replacement. Existing endpoints and ongoing migrations are unaffected, and according to the announcement, no action is required. Microsoft does not specify a deprecation date for Basic Auth at the MRS Proxy.

Prerequisites

The feature is available in Microsoft 365’s global multi-tenant environment. For other clouds, the Exchange team has announced updates in the coming months. For on-premises, you’ll need one of these versions:

This requires access to Microsoft Entra ID as a tenant admin, as well as an on-premises domain registered in the tenant and used for migration. For the PowerShell steps, you need the Microsoft Graph PowerShell module, the Exchange Management Shell, and the Exchange Online PowerShell module.

Important for context: This process is not Hybrid Modern Authentication. HMA governs user sign-in. The OAuth endpoint for MRS uses a separate, app-based authorization model tied to the Object ID of the MRS service principal in your tenant.

Step by step

Register on-premises API in Entra ID

In the Microsoft Entra admin center, open **App registrations** and create a new app via **New registration**. For supported account type, select **Single tenant only**.

In the app, select Add an Application ID URI. The URI must be in all lowercase letters. You can use the URI of your existing migration endpoint or follow Microsoft’s recommended scheme using the Application (client) ID:

https://[Application (client) ID].contoso.com/ews/mrsproxy.svc

The domain in the URI must be registered in your Entra tenant.

Under API permissions, remove all Microsoft Graph permissions using the Remove all permissions option in the menu. Then, under App roles, create a role using Create an app role. In the example, Microsoft uses the display name “MRS Onprem Onboarding” and the value MRS.Onprem.Onboarding. For Allowed member types, select Applications and enable the role.

Under Token configuration, add an optional claim for the token type Access and enable idtyp.

In the manifest, check that optionalClaims.accessToken contains the entry idtyp, and add a second entry:

{
   "additionalProperties": [],
   "essential": false,
   "name": "xms_aud_guid",
   "source": null
}

After saving, accessToken contains exactly two entries: idtyp and xms_aud_guid.

2: Create MRS service principal and assign role

The Microsoft 365 Mailbox Replication Service has the fixed app ID dbcda063-249e-42b8-84a1-5c1b9298c1f3.

Use Microsoft Graph PowerShell to create a service principal in your tenant:

Connect-MgGraph
$spn1P = New-MgServicePrincipal -AppId dbcda063-249e-42b8-84a1-5c1b9298c1f3
$spn1P | fl DisplayName, AppDisplayName, AppId, Id, ServicePrincipalNames, ServicePrincipalType, AppOwnerOrganizationId

The DisplayName appears as "Mailbox Replication Service". The returned Id is the Object ID that you will need later on the Exchange Server. Next, you assign the app role of your on-premises API to this service principal.

Copy the Application (client) ID and the app role value from the Entra Admin Center beforehand:

$appId = "Application (client) ID"
$role  = "App role Value"

$app     = Get-MgApplication -Filter "AppId eq '$appId'"
$appRole = $app.AppRoles | ?{$_.Value -eq $role}

$spn1P  = Get-MgServicePrincipalByAppId -AppId 'dbcda063-249e-42b8-84a1-5c1b9298c1f3'
$spnApp = Get-MgServicePrincipalByAppId -AppId $appId

$entry = New-MgServicePrincipalAppRoleAssignedTo -ResourceId $spnApp.Id -ServicePrincipalId $spnApp.Id -AppRoleId $appRole.Id -PrincipalId $spn1P.Id
$entry | fl AppRoleId, PrincipalDisplayName, PrincipalId, PrincipalType, ResourceDisplayName, ResourceId

If PrincipalDisplayName shows 'Mailbox Replication Service', that's where the assignment is.

3: Configure Exchange Server

The following commands run in the Exchange Management Shell on a server with the current build. First, enable OAuth for the MRS Proxy and set the authorized entry. It consists of four values separated by a pipe: Tenant ID, Object ID of the MRS service principal, Audience (the full Application ID URI), and Role value. Audience and Role are case-sensitive.

New-SettingOverride -Name "OAuth MRS Settings" -Component "Mrs" -Section MRSProxyServiceOAuth -Parameters ("Enabled=true","AuthorizedEntries=$TenantID|$ObjectID|$Audience|$Role") -Reason "Enabling MRS Proxy OAuth"

Separate multiple entries with commas, each audience may only appear once.

Then check if there is already an audience validation, and use the Application ID of your new app for it.

You must include existing values, otherwise they will be lost:

Get-SettingOverride -Component OAuth -Name AudGuidValidation

New-SettingOverride -Name AudGuidValidation -Parameters @("Enabled=true", "AdditionalApplicationIds=[vorhandene Werte],[Application (client) ID]") -Component OAuth -Section "AppIdBasedAudienceValidation" -Reason "Allowing MRS API App"

Finally, enable OAuth on the frontend services:

New-SettingOverride -Name "Enable CAFE MRS OAuth" -Component Cafe -Section "OAuthAuthorizationInCAT" -Reason "Enable CAFE MRS OAuth" -Parameters "Enabled=true"

With Exchange Server SE, Microsoft additionally requires cookie-based session affinity at the load balancer, described as Scenario C 'Single namespace with session affinity, Layer 7' in the Exchange Server load balancing article. According to the documentation, this is not required for Exchange 2019 CU15.

For the first migrations, it's worth keeping a log:

New-SettingOverride -Name "MRS OAuthLogging Settings" -Component "Mrs" -Section MRSProxyAuthLogging -Parameters ("Enabled=true") -Reason "Enabling MRS Proxy OAuth Logging"

The logs are located under C:\Program Files\Microsoft\Exchange Server\V15\Logging\MrsProxyAuthorization. The first check level on the CAFE services logs to ...\V15\Logging\HttpProxy\Ews. If you later use Set-SettingOverride to set additional log options, the command overwrites all previous override parameters. Therefore, always specify the complete set.

4: Create endpoint in Exchange Online

In Exchange Online PowerShell, you set the endpoint using the new -UseOAuth switch. -RemoteServer must match the hostname from the Application ID URI:

Connect-ExchangeOnline
$remoteServer = "mail.contoso.com"
New-MigrationEndpoint -UseOAuth -Name "OAuthEndpoint" -RemoteServer $remoteServer -ExchangeRemoteMove
Test-MigrationServerAvailability -Endpoint "OAuthEndpoint"

The test retrieves an OAuth token and shows you whether the chain from Entra ID to CAFE and MRS Proxy is working. After that, you use the endpoint like any other, in migration batches or directly in move requests:

New-MigrationBatch -Name MyBatch -SourceEndpoint "OAuthEndpoint"

New-MoveRequest -Identity "user@contoso.com" -TargetDeliveryDomain contoso.com -SourceEndpoint "OAuthEndpoint" -RemoteHostName $remoteServer -Remote -ArchiveDomain contoso.com

Classification

The effort is almost entirely in steps 1 and 3. In return, the username and password previously stored in the endpoint are no longer required. If you are currently planning onboarding or still migrating mailboxes back, you can set up the OAuth endpoint in parallel with the existing Basic endpoint and verify it with Test-MigrationServerAvailability before switching batches. None of the server steps will work without Exchange SE in the October release or Exchange 2019 CU15 with the October ESU.

SourceURL
Exchange Team Blog: Now available: OAuth authentication for on-premises Exchange mailbox migrations to Microsoft 365 (11/09/2026)https://techcommunity.microsoft.com/blog/exchange/now-available-oauth-authentication-for-on-premises-exchange-mailbox-migrations-t/4571777
Microsoft Learn: Migrationsendpunkte mit OAuth-Authentifizierung erstellenhttps://learn.microsoft.com/en-us/exchange/hybrid-deployment/oauth-migration-endpoint
Microsoft Learn: New-MigrationEndpointhttps://learn.microsoft.com/en-us/powershell/module/exchangepowershell/new-migrationendpoint
Microsoft Learn: Lastverteilung in Exchange Serverhttps://learn.microsoft.com/en-us/exchange/architecture/client-access/load-balancing
Share:
No comments yet

Be the first to start the discussion with a helpful comment.

Leave a comment

Comments are reviewed briefly before they are published — factual, respectful and to the point is just right here.

Your email address will not be published.