Certificates & Site Ops · Field note
OAuth Callback URL Mismatch Debugging
Redirect URI mismatch errors usually come from small string differences. Compare the callback value, environment, path, port, and encoding before changing provider or application settings.
Before you start
Inspect the current certificate, key, token, or endpoint output before changing deployment config; stale artifacts make fixes misleading.
OAuth callback failures often come down to a one-character difference in the redirect URI.
The provider compares the redirect URI sent in the authorization request with a registered value. In the common exact-match case, one changed character is enough to stop the flow.
Tip: Capture the authorization request your application actually sent. Comparing a value reconstructed from memory can hide the environment or encoding mistake.
The exact value is what matters
These values can look almost identical and still fail:
Registered: https://app.example.com/auth/callback
Sent: https://app.example.com/auth/callback/
Other common mismatches:
httpvshttpslocalhost:3000vslocalhost:3001/signin-oidcvs/auth/callback- encoded query params vs decoded ones
- staging callback registered in production
What to compare before you change code
- The exact redirect URI sent in the authorize request.
- The exact redirect URI registered with the provider.
- The environment, tenant, and client ID involved.
- Whether the provider requires an exact string match or allows limited wildcard behavior.
If you skip step two and rely on memory, you usually lose time.
A failure case that catches teams repeatedly
The application builds the authorize URL with an encoded redirect value:
redirect_uri=https%3A%2F%2Fapp.example.com%2Fauth%2Fcallback
When you extract this query parameter, form-decode it once. Then compare the resulting callback string exactly with the registered value. Do not trim it, change case, add or remove a slash, reorder its query, or decode it a second time.
A practical workflow
- Use the OAuth Redirect URI Checker to paste the registered value and either the sent callback or the complete authorization request. It extracts the parameter once and keeps exact equality authoritative.
- Review the first differing character and component evidence before changing application configuration.
- If login reaches the callback but token handling fails afterward, move to JWT and JWKS inspection instead of continuing to change the redirect URI.
Where discovery metadata helps
If you are also unsure about the issuer or authorization endpoint, paste that environment's metadata into the OIDC Discovery Inspector. A tenant or authorization-server mismatch can send an otherwise correct callback to the wrong environment.
Questions that matter in practice
Does a trailing slash matter?
Often yes. Many providers treat the redirect URI as an exact string, and a trailing slash changes the string.
Can I register one callback for every environment?
Some providers support multiple allowed redirect URIs, but you should still keep them explicit. Overly broad callback rules create confusion and can weaken security.
Why does this fail only in production?
Because production often differs by host, tenant, HTTPS enforcement, reverse proxy behavior, or an environment variable that was copied from staging.