OAuth Test Callbacks Need an Identity Ledger

OAuth tests often look successful for the wrong reason. A browser reaches the callback, a code is exchanged, and the test sees a 200 response. But which test user was authenticated? Was the code issued for this run? Did the inbox message belong to the same identity, or did a stale message make the assertion pass?

Those questions matter when a team uses a temp email generator or other disposable test mailbox. The mailbox is only one part of the identity. The authorization request, browser session, callback, token exchange, and verification message must be tied together. I call that small set of relationships an identity ledger.

Why the callback needs an identity ledger

An OAuth callback is a trust boundary. It receives values from a browser redirect and turns them into an authenticated application session. A useful test therefore checks more than whether the route is reachable.

For each run, the test should be able to answer:

1. Which test user started the authorization request?
2. Which state value and redirect URI were expected?
3. Which authorization code was consumed?
4. Which mailbox and message belonged to the run?
5. Which application user was finally created or updated?

Without those links, parallel tests can pass while crossing identities. A delayed callback can even attach to a newer browser session if the fixture keeps “the current user” in a shared variable. That is not a theoretical concern; it makes failures hard to reproduce and can hide a real account-mixup bug.

The ledger does not need to store message bodies or access tokens. It needs stable, non-secret correlation data and a clear lifecycle.

The threat model: identity confusion and replay

There are two failure classes worth separating.

Identity confusion happens when one run consumes another run's evidence. Typical causes are a shared inbox, a weak message search, or a test that selects the first matching email. A phrase such as “welcome email received” is not enough when several tests run at once.

Replay happens when an old callback, code, or verification message is accepted again. OAuth authorization codes should be short lived and single use, but the application test still needs to prove that its own request context is enforced. The state value is not decoration: it binds the callback to the initiating browser flow.

A good test deliberately tries the negative paths: use a state from another run, reuse a consumed code, alter the redirect target, and present a message with the right subject but the wrong correlation ID. The check are more valuable than another happy-path screenshot.

What to record for each test authorization

Create a ledger record when the authorization request starts. A minimal record can contain:

run_id                 opaque test-run identifier
user_id                synthetic application-user identifier
state_hash             hash of the OAuth state value
redirect_uri           exact registered callback URI
mailbox_id             provider-side test mailbox reference
message_claim          expected message correlation value
code_status            issued, consumed, rejected, or expired
created_at / expires_at bounded timestamps

Do not put the raw state, authorization code, access token, or mailbox credentials into ordinary logs. The hash is enough for correlation in most test reports. If your test provider offers message metadata, use a provider message ID or a unique run marker instead of scraping an entire inbox.

The callback handler can then resolve the record by a server-side session or a validated state value. It should mark the code as consumed in the same transaction that creates the application session. If the operation is retried, the result should be an explicit “already consumed” outcome, not a second login.

For observability, log the run ID, user ID, and outcome. This is where inbox correlation IDs in auth logs are useful: the email assertion and the OAuth assertion can be compared without exposing the message contents.

A small implementation pattern

The following pseudocode shows the important ordering. It leaves provider and database details to the application:

start_authorization():
    run = ledger.create(user_id, redirect_uri, expires_in=5m)
    state = sign({run_id: run.id, nonce: random_bytes()})
    ledger.store_state_hash(run.id, hash(state))
    redirect_to_provider(state, run.redirect_uri)

handle_callback(code, state):
    claims = verify_state(state)
    run = ledger.find_active(claims.run_id)
    require(hash(state) == run.state_hash)
    require(request.redirect_uri == run.redirect_uri)
    token = exchange_code_once(code)
    ledger.consume(run.id, token.subject)
    return create_session(run.user_id)

The consume operation must be atomic and idempotent for the expected retry behavior. It should also reject a token subject that is not the synthetic user recorded for the run. That extra comparison is a bit more clear than relying on the browser alone.

Privacy and cleanup boundaries

Test identity data still deserves a budget. Keep mailbox contents for the shortest useful period, redact addresses in reports, and delete ledger records after the retention window. A privacy budget for disposable email in CI is a practical way to make those limits visible to the team.

Use labels that explain purpose, such as oauth-e2e-<run_id>, instead of real names. Avoid vague fixtures named temp org mail or dummy e mail in production-facing examples; they make it easier for someone to accidentally reuse test data in a real flow. The ledger should contain references, not a permanent archive of personal-looking messages.

A practical verification checklist

• Generate a unique run ID and state value for every authorization.
• Validate the exact redirect URI, issuer, audience, and state.
• Select messages by run-specific metadata, not only subject or sender.
• Record code consumption and reject a second exchange.
• Assert that the token subject matches the planned synthetic user.
• Run two identities in parallel and prove their records never cross.
• Test an expired state, wrong state, wrong redirect, and stale message.
• Keep secrets and message bodies out of normal logs.
• Expire mailbox and ledger data after the test window.

Common questions

Is the state parameter enough for the ledger?

No. State helps bind the callback to the initiating flow, but the ledger also needs the intended user, redirect URI, lifecycle, and expected evidence. State alone does not prove that the email assertion belongs to the same test run.

Should a test use one mailbox for every run?

Only when the provider gives strong message-level isolation and your selector is run-specific. Separate mailboxes are simpler to reason about, but they do not replace correlation and cleanup.

Do I need to log the email address?

Usually not. A mailbox ID or keyed digest is enough for joining test events. This reduces the chance that debugging output becomes a quiet source of user data.

The payoff is modest but important: OAuth failures become explainable. When every callback, token exchange, and email assertion has one bounded identity ledger, a passing test means the intended user completed the intended flow—not merely that some browser reached the callback.