OAuth callback state loss: trace where correlation data disappears

The symptoms

• •Identity provider returns the user to the redirect_uri, but the relying party responds with HTTP 400 or 403 and a generic error such as invalid_state or state_mismatch instead of completing sign-in.
• •Server logs show a state value present on the outbound /authorize request but no matching record on the inbound /callback request, often accompanied by a Set-Cookie absent on the response that served the original redirect.
• •OAuth flow works on the same browser session but fails when the callback is opened in a private window, mobile WebView, or after the browser blocks third-party cookies, indicating a cookie-not-stored condition.

Likely causes

• •The relying party attempted to persist the OAuth state in a session cookie, but the Set-Cookie header was stripped, downgraded, or rejected before it reached the browser, so no correlation record exists when the callback arrives.
• •SameSite cookie attributes or a top-level navigation policy caused the state cookie to be treated as third-party and dropped, while the application logic assumed it would persist across the identity-provider redirect.
• •State was stored in a server-side session store keyed by an identifier the browser did not echo back at callback time, such as a session ID that was rotated, expired, or scoped to a different cookie domain.
• •The relying party's CSRF or anti-replay middleware regenerated the session identifier after the outbound redirect, invalidating the in-memory map entry that bound the original state to the user.
• •Cross-site or subdomain mismatch between the cookie domain of the relying party and the redirect_uri host caused the browser to attach no cookie on the callback request.

First ten minutes

1. 01Reproduce the failure with a single browser profile and capture the outbound /authorize request and the inbound /callback request, including request and response headers, so the state value can be compared end to end.
2. 02Inspect the Set-Cookie header on the response that created or refreshed the OAuth state, using the MDN Set-Cookie reference to confirm which attributes were applied and whether any were silently stripped by an upstream proxy.
3. 03Inspect the Cookie header sent by the browser on the /callback request and confirm whether the cookie used to look up state is present at all, or is present with a different name, path, or domain than the one that stored the state.
4. 04Check the session store for an entry keyed by the state value observed on the outbound request, and note whether the lookup key is the state itself, the session ID, or a derived fingerprint.
5. 05Decide the boundary at which correlation data is lost: cookie layer, session store, identity-provider redirect, or callback validation middleware, before changing any code.

Evidence to collect

• •The literal state value present on the outbound /authorize request URL and the literal state value present on the inbound /callback request URL, recorded from network captures rather than logs.
• •The full Set-Cookie response header for any cookie that holds the state, including name, value, Path, Domain, Expires or Max-Age, Secure, HttpOnly, and SameSite attributes as actually sent on the wire.
• •The Cookie request header that the browser sends on the /callback request, so the presence or absence of the state-bearing cookie can be compared against expectations.
• •A timestamp or monotonic counter linking the outbound redirect and the inbound callback, so session-store TTL and possible rotation can be evaluated.

Where to look

• •The relying party's HTTP boundary, specifically the response headers of the route that initiates /authorize and the request headers of the route that handles /callback.
• •The session store or in-memory map used to bind the generated state to the originating user, looked up by either the state value or by the session ID at callback time.
• •The browser cookie jar for the relying party's domain, including any partitioned or third-party cookie classification applied by the browser policy in effect during the flow.
• •The reverse proxy or load balancer in front of the relying party, because header rewriting, cookie rewriting, or path normalization at this boundary is a frequent cause of silent state loss.

Diagnostic steps

1. 01Compare state on outbound vs inbound requests: if they differ, the failure is at the identity-provider or redirect layer rather than the relying party's storage; if they match but lookup fails, the failure is in storage.
2. 02Audit the Set-Cookie attributes for SameSite, Secure, Domain, and Path against the cookie attributes the browser actually requires for the /callback request, using the MDN Set-Cookie specification to verify which attributes are honoured.
3. 03Verify whether the state cookie is set with SameSite=None and Secure when the identity provider's authorization endpoint is on a different site than the relying party, and whether the browser treats the callback as a cross-site navigation.
4. 04Check whether the relying party rotates the session identifier between the outbound redirect and the inbound callback, which would invalidate any state stored under the original session ID and point to CSRF middleware interaction.
5. 05Inspect the session store TTL of the state entry relative to the elapsed time between outbound redirect and inbound callback, so storage expiration can be ruled in or out before code changes.
6. 06Confirm that the redirect_uri host exactly matches the cookie domain, including subdomain and scheme, since a host mismatch can attach no cookie on the callback even when the cookie is otherwise valid.

Common mistakes

• •Assuming the state is lost at the identity provider when the actual loss is at the cookie layer, which wastes investigation effort on the wrong system.
• •Storing state only in an HttpOnly cookie that is not echoed back to the server in a way that the callback handler can read, then treating the missing value as a bug in the identity provider.
• •Relying on in-memory state that does not survive a worker restart, multi-instance deployment, or request routing change, so the first callback after any topology change fails validation.
• •Changing SameSite, Secure, or Domain attributes without re-testing the cross-site navigation pattern, which can mask one cookie-blocking cause while introducing another.
• •Trusting application logs over wire-level captures, because logs often redact or normalize the very headers that carry the state correlation.

Safe fixes

• •Persist the OAuth state in a backend store keyed by the state value itself with a TTL longer than the slowest expected user round trip, and look up by state on the callback rather than by session ID alone.
• •When storing state in a cookie, sign it with a keyed HMAC and verify the signature on the callback handler, so the callback can validate without depending on a server-side session that may be rotated.
• •Configure the state cookie with attributes appropriate for the identity provider's site relationship, including Secure and SameSite=None where the authorization endpoint is cross-site, and confirm via wire capture that these attributes are not stripped by a proxy.
• •Disable or scope any session-rotation middleware so that the session identifier observed when the state was generated is the same identifier observed on the callback request, only if such middleware is confirmed to be the cause.
• •Align the redirect_uri host and cookie domain exactly, including subdomain and scheme, and document this alignment so future host changes do not reintroduce the failure.

Prove the fix

1. 01A successful OAuth round trip records the same state value on the outbound /authorize request and the inbound /callback request, with the Set-Cookie for the state-bearing cookie present on the response that initiated the flow.
2. 02The session store contains an entry keyed by the state value at the moment the callback handler runs, and the entry has not expired before validation completes.
3. 03A regression check that forces a same-site navigation path and a cross-site navigation path both complete sign-in, and that a tampered state value is rejected with the same error class as before the change.
4. 04A check that the Set-Cookie attributes observed on the wire for the state-bearing cookie match the attributes the application intends to set, so proxy stripping is detected rather than assumed.

Prevention and next steps

• •Treat OAuth state as a wire artifact and capture both the outbound and inbound requests in any reproduction, since logs alone are usually insufficient to localize the loss.
• •Define and document the cookie attributes and the redirect_uri host alignment in a single source of truth, and review them whenever the deployment topology or identity-provider domain changes.
• •Back the state lookup with a store that survives worker restarts and request routing changes, and set its TTL with margin for slow users and identity-provider latency.
• •Add an automated check that exercises a full OAuth round trip in a representative browser profile and asserts that the state-bearing cookie is set and returned.

Safe commands and checks

grep -n "Set-Cookie" <proxy_access_log_path> | grep -i "oauth_state"
grep -n "invalid_state\|state_mismatch" <app_log_path> | tail -n 50