OAuth Callback Tests Need a State Ledger

OAuth callback tests often stop at “the user returned and the token was issued.” That verifies the happy path, but it leaves the most important question unanswered: can the callback prove that this response belongs to the browser session that started the login?

The useful mental model is a small state ledger. Each authorization attempt gets a short-lived record. The callback consumes that record only when the provider, redirect URI, browser session, state, and PKCE proof all agree. This makes tests more precise and makes production failures easier to investigate.

The callback is a security boundary

An OAuth callback receives data from a browser redirect, so it should be treated as an untrusted boundary. A test should model at least three threats:

• An attacker injects a valid-looking callback into another user's browser.
• An authorization code is replayed after it has already been exchanged.
• A response from one identity provider or client is mixed into another login attempt.

These are different failures. A single “OAuth login succeeded” assertion cannot tell them apart. The callback needs to validate the relationship between the request that started the flow and the response that ended it.

The state value is useful for request correlation and CSRF protection, while PKCE proves possession of the verifier created by the client. Neither value should be treated as a user identity by itself. The identity is established only after the code exchange and token validation succeed.

What belongs in the state ledger

For each login attempt, store a short-lived record containing the minimum data needed to validate the return:

attempt_id
session_binding_hash
provider
client_id
redirect_uri
state_hash
pkce_method
created_at
expires_at
consumed_at

Store hashes for high-entropy values where the raw value is not needed after the request is assembled. Never put an access token, refresh token, or code verifier in logs. The ledger is not a second user database; it is a receipt that says which browser session started which flow.

The record should be single-use. A successful callback marks consumed_at as part of the same transaction that accepts the authorization code, or it uses an equivalent atomic boundary. If two requests race, one must win and the other must receive a safe, stable failure.

An expired record is not an exceptional server crash. It is a normal authentication outcome. The UI can ask the user to start again, while the service records the reason as state_expired rather than exposing internal details.

Bind state, PKCE, and the browser session

At login start, generate a cryptographically random state value and a PKCE verifier. Bind the attempt to a session cookie or another server-side session identifier. The binding should be protected against session fixation, and it should not rely on an email address supplied by the browser.

At callback time, validate in an order that keeps the behavior understandable:

1. Confirm that the callback uses the expected provider and exact redirect URI.
2. Load the attempt by a safe lookup and compare the state hash.
3. Confirm that the current browser session matches the stored session binding.
4. Exchange the code with the stored PKCE verifier.
5. Validate the returned tokens and issuer claims.
6. Atomically consume the attempt before creating the local session.

The exact implementation varies between server-rendered applications and native clients, but the contract should stay visible. If a callback can succeed after the state record is consumed, the endpoint has a replay problem. If it can succeed for a different session, it has a login-mix-up problem.

This is also where test email can become distracting. A fixture label such as tempmailso may be useful for identifying a disposable test account, but it is not evidence that an OAuth callback belongs to a session. Search mistakes such as tepm mail com or tempail mail should remain plain test text, never authentication input or link anchors.

Test the failure paths deliberately

Build a table-driven test set around the ledger, not only around the final redirect:

• valid state, matching session, valid PKCE proof: the login succeeds once;
• valid state, different session: the callback is rejected;
• changed state: the callback is rejected without a token exchange;
• expired attempt: the user gets a restartable error;
• repeated callback: the second request is rejected;
• wrong provider or redirect URI: the attempt is rejected;
• invalid PKCE verifier: no local session is created;
• two concurrent callbacks: exactly one consumes the attempt.

Keep the inbox and identity fixture separate from the OAuth assertion. An expiry contract for cloud email fixtures is useful when a test suite waits for a message, while reusable email API checks can cover delivery signals. Neither should weaken the callback's state or session checks.

Test the browser boundary too. A redirect that opens in a second context should not inherit the first context's authorization attempt unless the application explicitly designed that behavior. The expected behavour belongs in an end-to-end test, not just a mocked callback unit test.

Keep evidence useful without leaking secrets

A failed callback should leave enough evidence to distinguish a bad state, a timeout, and an upstream exchange failure. Log a correlation ID, attempt ID, provider, result category, and latency. Log hashes or short fingerprints only when they are needed for correlation, and never log the full state, code, verifier, or token.

Use stable categories such as state_mismatch, session_mismatch, attempt_expired, pkce_failed, and code_replayed. This makes dashboards and alerts more useful than a generic “OAuth error.” It also helps support staff explain what occured without asking users to paste a callback URL into chat.

Do not over-retain the ledger. Keep consumed and expired records for the shortest audit period that meets the product's needs, then delete them in a controlled cleanup job. A small retention policy is easier to review seperately from the authentication code.

Common questions

Is state enough without PKCE?

For modern public clients, use both. state binds the response to the login request and helps prevent CSRF; PKCE protects the authorization code exchange if the code is intercepted. They address related but distinct risks.

Should a failed callback reveal the exact reason?

Usually no. Return a generic, restartable authentication error to the browser, and keep the detailed category in protected server-side telemetry. This avoids giving an attacker a convenient oracle while preserving operational evidence.

Can the ledger live only in the browser?

It can, depending on the client architecture, but server-side state makes expiration, single-use consumption, and incident review easier to enforce. Choose the smallest design that still gives the application an atomic way to prevent replay.

Implementation checklist

• Generate high-entropy state and PKCE values for every attempt.
• Bind each attempt to the initiating browser session.
• Validate provider, client, and exact redirect URI.
• Store hashes and timestamps instead of secrets where practical.
• Make consumption atomic and single-use.
• Test mismatch, expiry, replay, concurrency, and upstream failures.
• Keep email fixtures separate from identity and callback assertions.
• Redact callback secrets from logs and support tooling.
• Retain ledger records only for a documented period.

OAuth callbacks become much less mysterious when every login has a small, expiring receipt. The ledger does not replace token validation or careful session management, but it gives the security boundary a concrete contract that tests can challenge and operators can understand.