Fix OAuth Token Expired During Migration

Your migration ran cleanly for the first four hours, then the log started spitting OAuth2 token expired and every connection began failing. The mailbox progress counter froze. You signed in to the target tenant in a browser fine, so the credentials are not the problem — what failed is the refresh token your migration tool was using to silently extend its session. The fix is to know whether the refresh failed because of time, an admin action, or a conditional access policy, and then reauthenticate cleanly so the job resumes from its last checkpoint.

Why OAuth tokens expire mid-migration#

OAuth uses two tokens: a short-lived access token (about one hour) and a long-lived refresh token that the migration tool uses to mint new access tokens silently. A long migration doesn't need re-consent every hour because the refresh token does the work in the background. Three things invalidate the refresh token mid-job. The OAuth 2 glossary entry covers the underlying flow if you want background.

The refresh token outlived its window#

Microsoft refresh tokens default to a 90-day inactive lifetime — they're valid as long as the tool keeps using them within 90 days. Long enough for any single migration, in theory. In practice, the refresh token gets pinned to its initial sign-in moment, and Entra ID can require a fresh consent earlier if the tenant has a token lifetime policy in place. For migrations expected to run more than 24 hours, check the policy first. Google's refresh tokens technically don't expire but can be invalidated by the same conditions Microsoft uses.

Admin revoked consent#

A nervous admin sees a service principal called "Mailbox Migration Tool" in Enterprise Applications and clicks Revoke. This invalidates every refresh token issued under that consent. Symptom: the migration was working fine, the admin did nothing visible to your batch, but at a specific minute every connection started failing with invalid_grant. Track it down by checking the audit log in Entra ID for consent removal events on the migration app.

Conditional access policy kicked in#

If the tenant has a conditional access policy that requires MFA for sensitive applications, and your migration service principal isn't on the exclusion list, the policy can revoke the refresh token the moment the migration's IP changes or the tool's user-agent doesn't match the original sign-in context. This is the most common cause of mid-migration token expiry in enterprise tenants. The modern auth required fix covers the related symptom set if the issue is the auth method rather than the policy.

If the source is a Microsoft 365 tenant and you're staging the migration toward another cloud, the Office 365 migration guide and the authentication failed fix cover the broader auth surface area.

Fixing the expired token — step by step#

1. Confirm the exact OAuth error

   Open the migration tool's log and search for token, oauth, and invalid_grant. The exact string identifies the cause. invalid_grant: AADSTS50173 is conditional access. invalid_grant: AADSTS70008 is a refresh-token-too-old or revocation. OAuth2 token expired from Google with no further code is usually a Workspace policy change. Note the timestamp — you'll need it for the audit log step.

2. Check Entra ID audit log for revocations

   In the Entra admin centre, open Monitoring > Audit Logs and filter on the migration tool's display name in the target column for the 30 minutes before the error timestamp. Look for Consent to application events with a remove action, or Update conditional access policy events. If you find either, that's the cause.

3. Reauthenticate the migration tool

   In the migration tool, open the auth screen for the affected tenant and sign in again as a global admin (or an admin with the relevant migration role). This mints a fresh access token and refresh token. Mailbox Taxi stores both encrypted at rest, so this step is the same regardless of how you originally authenticated.

4. Confirm admin consent has not been revoked

   Still in Entra ID admin centre, open Enterprise Applications, find the migration tool's app registration, and click Permissions. Confirm all required permissions still show Granted for <tenant> in green. If any are missing, click Grant admin consent and confirm.

5. Exclude the migration app from conditional access

   Open the conditional access policy that flagged the migration. Add the migration tool's service principal to the policy's exclusion list for the migration window. Document the exclusion and add a follow-up task to remove it after cutover. For Google Workspace tenants, the equivalent is the Context-Aware Access policy under Security > Access and data control.

6. Resume the migration from the checkpoint

   Click Resume in the migration tool. Confirm the job picks up at the last committed checkpoint — the per-mailbox progress should resume from the same percentage shown before the error. If the tool re-copies items from zero, stop and check that checkpoint persistence is enabled.

Preventing token expiry on the next migration#

Plan around the refresh token. For any migration expected to run longer than 24 hours, do three things at project kickoff: confirm the tenant token lifetime policy with the admin, add the migration tool's service principal to the exclusion list of every conditional access policy for the migration window, and document an emergency reauthentication procedure with a named person available on-call. Most token-expiry incidents during a real migration happen because the on-call person can't be reached.

For phased migrations spread over weeks, schedule a touch-base reauthentication at the end of each week even if it's not strictly required. It costs five minutes and removes a class of failure that's painful to debug at 2am.

FAQ#

For the broader catalogue of auth failures you might also be hitting, the email migration troubleshooting hub is the index.