OAuth Test Flows Need a Browser-Binding Check

OAuth tests can pass while proving the wrong thing. A browser starts a login, an identity provider redirects back, and a test sees a successful session. But if two workers share a browser context, or an old callback is accepted, the green result may belong to another flow.

The security question is not only “did authentication complete?” It is “did this browser, this authorization request, and this account complete the same flow?” I treat that as a browser-binding check. It is a small addition to a test fixture, but it makes session mix-ups and replay-like bugs much easier to see.

The browser-binding problem

An OAuth browser test usually has at least four identities:

• the test worker and its run ID
• the browser context that holds cookies
• the client registration and redirect URI
• the user account that receives the authorization result

The email fixture adds another boundary. A throwaway email address can help create an isolated test account, but receiving a message does not prove that the current browser initiated the request. If a helper simply opens the newest message, a previous worker can accidentally supply the evidence.

This is a common failure pattern:

1. Worker A starts an authorization request.
2. Worker B reuses a shared inbox or browser context.
3. A callback from B is observed by A.
4. The test checks only that a session exists and passes.

The product may still have a real defect: weak state validation, an overly broad redirect handler, or a session cookie that crosses test boundaries. The test did not catch it because its assertion was too wide.

What state and PKCE actually prove

The OAuth state value is a correlation value for the authorization request. A callback should match the value stored by the same browser session, and the value should be unpredictable. It is not a universal proof that the user intended every action after login.

PKCE adds a different check. The client creates a verifier, sends a derived challenge to the authorization server, and later presents the verifier at the token endpoint. A stolen authorization code should not be enough without that verifier. These controls work together, but neither one removes the need to isolate browser state in tests.

For a test fixture, keep the ownership rules explicit:

type OAuthRun = {
  runId: string;
  state: string;
  codeVerifier: string;
  browserContextId: string;
  inboxId: string;
  startedAt: string;
};

The callback handler can now check that the request belongs to the current run, that the browser owns the stored state, and that the token exchange uses the matching verifier. Do not log the verifier, authorization code, or full email address. A short run ID and redacted message ID is enough for most diagnosis.

Build a test fixture with explicit ownership

Start each test with a fresh browser context. Generate a run ID and store it outside page content, such as in the test worker's fixture state. Create an isolated account using a throwaway email address only for the test environment, then place a non-secret correlation marker where the application can safely associate it with the run.

The sequence should look like this:

new worker -> new browser context -> new account -> new OAuth request
    |             |                    |              |
  run ID       cookies             inbox lease       state + PKCE

When the callback arrives, assert all of these conditions rather than only checking the final URL:

• the redirect URI is the expected environment and exact path
• the state value matches the current context
• the code exchange uses the current PKCE verifier
• the account identity matches the account created by this run
• the session cookie exists only in this browser context

The last check is easy to skip, and it catches surprises that URL assertions miss. It also make parallel failures easier to reproduce.

Exercise the failure paths

A security-aware test suite should deliberately send the wrong evidence. These cases are more valuable than repeating the happy path many times:

• replace state with a value from another worker
• use a valid authorization code with the wrong PKCE verifier
• replay a callback after the run has expired
• send the callback to a staging host from a production fixture
• read an email received before the current run started
• open the callback in a different browser context

Each case should fail for a named reason. “Login failed” is not enough; state_mismatch, pkce_verifier_rejected, and stale_message tell the maintainer what boundary worked. The test should not retry a rejected security condition until it becomes green. That can hide a bug and make the report less clear.

If a manual note includes terms such as tempail or temp org mail, keep them out of account ownership assertions. They may explain a search or fixture history, but they are not identity evidence.

Keep CI evidence useful

OAuth failures are difficult to investigate when CI saves only a screenshot of the final page. Save a redacted receipt with the run ID, browser context ID, redirect host, state result, PKCE result, message ID, and final decision. Do not save access tokens, refresh tokens, authorization codes, or complete inbox contents.

For a compact pattern, pair the receipt with a reviewable CI receipt for API checks. The principle is the same: a result should explain what was checked, not merely claim that a command exited successfully. During deployment investigations, a deploy receipt that explains what happened is a useful reminder that provenance matters across system boundaries.

A receipt could contain:

{
  "run_id": "oauth-7f31",
  "browser_context": "ctx-204",
  "redirect_host": "staging.example.test",
  "state": "matched",
  "pkce": "matched",
  "email_message": "msg-redacted-81",
  "decision": "accepted"
}

This format is boring on purpose. It gives a teammate enough information to compare parallel runs without turning sensitive protocol values into permanent CI artifacts.

A practical security checklist

Before relying on an OAuth browser test, verify:

• every worker gets a fresh browser context and run ID
• state is generated, stored, and checked per context
• PKCE is enabled where the client flow supports it
• redirect URIs are exact and environment-aware
• the email fixture is isolated and filtered by run start time
• account identity is checked after token exchange
• rejected callbacks have stable, specific reasons
• artifacts redact tokens, codes, and mailbox contents
• expired fixtures are cleaned up, even when the test fails

The checklist is small enough to review during a pull request. More importantly, it turns an OAuth test from a page-navigation script into a set of claims about ownership.

Common questions

Is checking state enough?

No. State helps correlate a callback with an authorization request, while PKCE protects the code exchange. You still need isolated browser state, exact redirect checks, and an assertion about the account that was authenticated.

Should every test use a real personal inbox?

No. Personal inboxes make isolation, cleanup, and privacy harder. Use controlled test fixtures in a non-production environment, with short lifetimes and redacted evidence.

What is the best first improvement?

Give every worker a fresh browser context and a visible run ID, then record why each callback was accepted or rejected. That change usually exposes hidden sharing before the suite needs a larger redesign.

Browser binding is not an extra layer of ceremony. It is the missing assertion that connects the authorization request, the email fixture, the callback, and the resulting session to one test run.