How to Configure OAuth for Exchange Server to Microsoft 365 Mailbox Migrations

The important operational detail: this is optional, not a forced migration away from Basic authentication. Existing endpoints and migrations already underway are unaffected. For administrators, this is an opportunity to improve migration authentication—not a reason to interrupt a working mailbox move.

Microsoft’s implementation guide also reveals why adoption requires more than adding an OAuth switch to a command. The configuration connects a Microsoft Entra application registration, a tenant-specific MRS service principal, on-premises authorization settings, and an Exchange Online migration endpoint. Each piece must agree about who is calling and which resource it may access.

Who can use OAuth mailbox migrations?​

The launch has explicit cloud and server boundaries. According to the Exchange Team announcement, supported environments are:

Microsoft says it will share news about other cloud environments over the following months, but provides no availability date for them. Administrators should not assume that commercial-cloud support extends to other Microsoft 365 clouds.

The Exchange 2019 requirement deserves particular attention: CU15 alone is not the stated baseline; the October 2026 ESU is part of it. Microsoft’s Learn guide similarly specifies current Exchange SE or Exchange 2019 CU15 with the latest ESU.

This is not Hybrid Modern Authentication​

Microsoft explicitly distinguishes this feature from Hybrid Modern Authentication, which authenticates user access. Migration OAuth instead uses an application-based authorization model with a defined MRS identity, separation from other Exchange hybrid workloads, and tenant-specific authorization through a service principal object ID.

That distinction matters when planning the change. Having modern authentication configured for users is not evidence that the new migration endpoint is ready. The documented MRS application and authorization settings still need to be established.

The security benefit is also specific: the migration can use OAuth rather than the Basic credentials of a privileged directory user. Our assessment is that this is a useful separation of responsibilities, but not a substitute for carefully reviewing application authorization. The configuration still grants migration access; it changes how that access is represented and validated.

Step 1: Prepare the application identity​

Microsoft’s prerequisites include administrator access to Microsoft Entra ID and configuration of the on-premises domain used for migration. The procedure also uses Microsoft Graph PowerShell, on-premises Exchange PowerShell, and Exchange Online PowerShell. Prepare those administrative environments before starting.

In the Microsoft Entra admin center:

1. Open App registrations, select New registration, and create a recognizable single-tenant registration.
2. Open the registration and set its Application ID URI.
3. Use a lowercase URI specific to the on-premises MRS Proxy endpoint.
4. Under API permissions, remove the Microsoft Graph permissions so direct permissions are empty.
5. Under App roles, create and enable a role whose allowed member type is Applications.

Microsoft permits reuse of an existing migration endpoint URI. Alternatively, it recommends optionally incorporating the application’s client ID into the hostname, with a domain registered in the Entra tenant:

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

A conventional endpoint-specific URI is also permitted:

[url unfurl="true"]https://mail.contoso.com/ews/mrsproxy.svc[/url]

The entire URI must be lowercase. Keep a record of the exact value: it becomes the audience authorized on-premises, and its hostname must later match the migration endpoint’s remote server.

For the app role, Microsoft illustrates a display name such as MRS Onprem Onboarding and a value such as MRS.Onprem.Onboarding. Record the actual role value, not merely its friendly label; authorization checks are case-sensitive.

Next, add the access-token optional claim idtyp through Token Configuration, then edit the manifest so optionalClaims.accessToken also contains:

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

There is a documentation trap here: one explanatory line in Microsoft’s guide says xml_aud_guid, but both JSON examples specify xms_aud_guid. The configuration shown in the examples uses the latter. Preserve the existing manifest structure and the idtyp entry when adding it.

Step 2: Register and authorize Microsoft’s MRS principal​

On a computer with Microsoft Graph PowerShell installed, connect and register the MRS service principal in the tenant used for migration:

Connect-MgGraph

$spn1P = New-MgServicePrincipal `
    -AppId "dbcda063-249e-42b8-84a1-5c1b9298c1f3"

$spn1P | Format-List DisplayName, AppDisplayName, AppId, Id

Microsoft identifies that application ID as its Mailbox Replication Service application. Validate that the returned identity is Mailbox Replication Service, and retain the returned Id: this is the tenant-specific service principal object ID, not the shared application ID.

Assign the application role created in the previous step. Replace the placeholder client ID and use your exact role value:

$appId = "<your on-premises API application client ID>"
$role = "MRS.Onprem.Onboarding"

$app = Get-MgApplication -Filter "AppId eq '$appId'"
$appRole = $app.AppRoles |
    Where-Object { $_.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 | Format-List AppRoleId, PrincipalDisplayName,
    PrincipalId, PrincipalType, ResourceDisplayName, ResourceId

The verification checkpoint is PrincipalDisplayName: it should identify Mailbox Replication Service. Do not carry sample object IDs from documentation into your deployment; retrieve your tenant’s actual values.

Step 3: Configure on-premises Exchange authorization​

The on-premises MRS Proxy configuration authorizes a combination of four values:

• TenantID: the migration tenant’s GUID.
• ObjectID: the tenant-specific MRS service principal ID.
• Audience: the full Application ID URI.
• Role: the app role’s exact value.

In on-premises Exchange PowerShell, populate the variables and create the documented override:

$TenantID = "<migration tenant GUID>"
$ObjectID = "<MRS service principal object ID>"
$Audience = "[url]https://mail.contoso.com/ews/mrsproxy.svc[/url]"
$Role = "MRS.Onprem.Onboarding"

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

The separators inside each authorization entry are pipes. Multiple entries may be comma-separated, but each audience must be unique. Both audience and role are case-sensitive.

Audience GUID validation is a separate setting. First inspect whether it already exists:

Get-SettingOverride -Component OAuth -Name AudGuidValidation

For a new configuration, Microsoft documents the OAuth component, AppIdBasedAudienceValidation section, Enabled=true, and AdditionalApplicationIds containing the on-premises API’s client ID. For example, where no previous override exists:

New-SettingOverride `
    -Name "AudGuidValidation" `
    -Component OAuth `
    -Section "AppIdBasedAudienceValidation" `
    -Parameters (
        "Enabled=true",
        "AdditionalApplicationIds=$appId"
    ) `
    -Reason "Allowing MRS API App"

If an override already exists, preserve its existing application IDs and parameters when modifying it rather than blindly attempting to create another. Microsoft warns that Set-SettingOverride overwrites previous settings. Its cmdlet reference confirms that it modifies existing overrides.

Finally, enable front-end OAuth authorization:

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

These overrides deserve change-control discipline. Microsoft’s PowerShell reference explains that overrides are stored in Active Directory, may be organization-wide or server-specific, and persist across cumulative updates. It also cautions against using them outside documented instructions or Microsoft support guidance.

Step 4: Check load balancing and enable diagnostics​

Microsoft documents a specific load-balancing requirement for Exchange Server Subscription Edition: use cookie-based session affinity. The guide explicitly limits this requirement to SE; it should not be casually presented as applying equally to Exchange 2019.

Enable OAuth logging during early migrations:

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

Microsoft describes two validation layers and their default log locations:

Additional logging properties include LogEventData, LogExceptionMessage, and LogExceptionCallStack. Event data can include app-only status, tenant ID, object ID, application ID, and audience.

For detailed troubleshooting, Microsoft supplies this configuration:

Set-SettingOverride `
    -Identity "MRS OAuthLogging Settings" `
    -Parameters (
        "Enabled=true",
        "LogEventData=true",
        "LogExceptionMessage=true",
        "LogExceptionCallStack=true"
    )

Inspect existing parameters before modifying an override and retain settings you still need. This is a replacement operation, not an invitation to assume unspecified values remain untouched.

Step 5: Create and test the migration endpoint​

Once Entra and on-premises configuration are complete, connect to Exchange Online PowerShell and create the endpoint:

Connect-ExchangeOnline

New-MigrationEndpoint `
    -UseOAuth `
    -Name "OAuthEndpoint" `
    -RemoteServer "mail.contoso.com" `
    -ExchangeRemoteMove

Test-MigrationServerAvailability -Endpoint "OAuthEndpoint"

Replace the example hostname with the host portion of your Application ID URI. If that URI contains the client ID in its hostname, the same hostname belongs in -RemoteServer. The endpoint name can be chosen for your environment, but the test must reference that same name.

Microsoft says the availability test obtains an OAuth token. Treat successful endpoint validation as the checkpoint before proceeding to a pilot mailbox move—not as proof that a mailbox migration has already completed. Our operational recommendation is to validate the endpoint first, then evaluate a small migration before expanding its use.

The endpoint can then be used with migration batches or remote moves. Microsoft’s move-request instructions require -RemoteHostName to match the application URI’s hostname and specify -ArchiveDomain to resolve the appropriate parameter set. Batch configuration otherwise treats the OAuth endpoint like other endpoint types. Mailbox selection, delivery-domain values, and direction-specific options still need to match the actual migration.

Where to look when validation fails​

Microsoft’s configuration requirements provide a focused troubleshooting checklist:

• Identity mismatch: confirm that on-premises authorization uses the MRS service principal’s object ID, not its shared application ID or the API registration’s object ID.
• Audience mismatch: compare the complete URI across Entra and Exchange, including case; compare its hostname with -RemoteServer.
• Role mismatch: verify the assigned role and its exact case-sensitive value.
• Incomplete token configuration: confirm that both idtyp and xms_aud_guid are present.
• Missing authorization layer: check both audience GUID validation and the CAFE OAuth setting.
• SE load balancing: verify cookie-based session affinity.
• Unexpected override changes: inspect existing parameters before replacing them.

This checklist is derived from Microsoft’s documented dependencies, not from a claim about which failures are most common. Use the front-end and MRS logs to distinguish where validation is failing rather than repeatedly recreating an endpoint.

A worthwhile change, without an emergency deadline​

The sensible adoption path is deliberate: confirm eligibility, document existing settings, configure the application relationship, validate the endpoint, and pilot a migration. Because Microsoft leaves existing endpoints and in-progress moves untouched, administrators can evaluate OAuth without treating the announcement as an emergency cutover order.

The improvement is meaningful but bounded. Exchange administrators gain a migration authentication option that avoids using a privileged on-premises user’s Basic credentials. In return, they must manage an explicit application authorization relationship across Entra and Exchange. That is a useful trade—provided the object IDs, audiences, roles, and server prerequisites receive as much attention as the welcome new -UseOAuth switch.