A production callback can fail after a domain migration when the redirect URI sent by the application no longer matches the URI registered with the identity provider. The login may begin normally, but the provider rejects the return trip, putting every customer who needs a fresh session at risk.
At 8:07 on Monday morning, the useful question is narrow: what changed between authorization and callback? A new domain, scheme, port, path, or trailing slash can be enough. The homepage may load. DNS may resolve. Existing sessions may remain active. None of those checks proves that a new OAuth login can complete.
The mismatch hides behind a healthy-looking migration
Domain migrations are often tested from the outside in. Teams confirm that the new host resolves, TLS works, pages render, and old URLs redirect. Authentication follows a different route.
An OAuth flow usually starts inside the application, moves to an identity provider, then returns to a registered callback address. The application supplies a `redirect_uri` during that exchange. The provider compares it with an approved value.
That comparison is deliberately strict. If the application sends `https://new.example.com/auth/callback` while the provider still allows only `https://old.example.com/auth/callback`, the provider should refuse the request. Differences that look minor to a person may also matter: `http` versus `https`, a changed subdomain, an added port, a missing path segment, or a trailing slash.
The result can be misleading. Customers with valid sessions keep working, so dashboards and health checks look normal. Logged-out customers, new users, people on fresh devices, and anyone whose session expires hit the broken path first.
The migration appears healthy until authentication creates new traffic through the callback.
Redirect behavior can conceal the actual fault
A common debugging mistake is to focus on where the browser ended up. That shows the visible symptom, not necessarily the value the provider evaluated.
A general redirect from the old domain to the new one may help ordinary page traffic. It does not guarantee that an OAuth provider will accept the old or new callback. Providers validate the declared redirect URI before returning authorization data because permissive matching would create an opportunity to send codes or tokens somewhere unintended.
Inspect the authorization request itself. Capture the exact `redirect_uri` value, decode it, and compare it character for character with the provider configuration. Then check the application setting that generated it. Possible sources include an environment variable, an authentication library base URL, a reverse proxy header, or a deployment-specific callback setting.
Logs should separate the stages:
- Did the application create the authorization request?
- Did the provider reject the redirect URI?
- Did the browser reach the callback endpoint?
- Did the application exchange the returned code?
- Did it create a session and send the customer to the intended page?
That sequence prevents a callback error, token exchange error, and session-cookie problem from collapsing into one vague report that “login is down.”
Multiple redirect URIs reduce migration risk
GitHub’s August changelog includes support for multiple redirect URIs and token refresh for OAuth apps. Multiple approved callbacks can make a staged domain migration safer when the provider supports them.
The practical pattern is simple. Register the new production callback before directing customer traffic to the new domain. Keep the old callback available during the migration window if both addresses remain valid and controlled. Test fresh authentication against the new address, then change the application’s generated redirect URI. Remove the old value after traffic and logs show it is no longer needed.
This is a temporary compatibility window, not permission to approve broad patterns. Exact callback addresses limit where authorization responses can go. Wildcards and loosely matched domains weaken that boundary.
Token refresh deserves separate testing. A successful login proves the authorization callback worked at that moment. It does not prove that existing credentials will refresh correctly after configuration changes. Test both a new authorization and a refresh path before declaring the migration complete.
This resembles the operational gap described in The Ten Seconds After You Press Go: deployment success and customer success are different observations.
Test the route customers actually take
The strongest preflight check starts with no session. Use a clean browser profile, begin on the production domain, choose each supported identity provider, complete authentication, and verify the final application session. Repeat the check through any old-domain entry point customers may still use.
Automated monitoring should follow the same route as far as safely possible. A homepage check cannot detect an OAuth callback mismatch. At minimum, monitor authorization initiation and callback reachability, then alert on provider rejection rates and login failures by domain.
Keep a rollback ready. That might mean restoring the previous application base URL, switching traffic back, or reactivating the prior registered callback. The correct option depends on which configuration changed, but it should be decided before the migration.
The final migration task is small and easy to overlook: open a clean browser, enter through the same bookmark a customer would use, and complete a fresh login. A green homepage is only the front door. The callback proves the key still works.
Sources
GitHub’s August changelog, as described in the supplied research context.
Comments
No comments yet.