OAuth Provider Discovery and Identity Resolution (Without Breaking Account Recovery)

#oauth #security #authentication

Short answer: choose an OAuth provider only after you can map every (issuer, subject) pair to one local principal, rotate refresh tokens atomically, revoke a stolen token family, and recover the account without trusting a mutable email address. Discovery makes connection setup easier; it does not solve identity resolution.

For a fintech application, the recovery path is the real design test. A clean authorization redirect means little if a stolen session survives a password reset, or if two providers can silently collapse separate people into one balance-bearing account. Keep provider configuration, external identity, local principal, session, and token family as separate records. Then a provider can change without rewriting the meaning of an account.

How should an OAuth provider strategy balance discovery simplicity and identity resolution complexity?

Use OpenID Connect discovery to obtain provider metadata, then treat the returned issuer as a security boundary rather than a friendly label. The client retrieves the provider configuration, validates the metadata, performs the authorization flow, verifies the ID token, and resolves the exact iss plus sub pair to an internal principal. That composite key matters because the same sub value can exist at two issuers, while email can change, be recycled, or arrive with different verification semantics.

Discovery removes hand-copied endpoint configuration. Good. It still leaves the difficult policy questions in your application: Can an existing user attach a second external identity? What proof is required? What happens when a provider account disappears? Which sessions survive recovery? A safe default is conservative: never auto-link accounts solely because their email strings match. Require an already authenticated session or a separate, strong recovery ceremony before adding a new (issuer, subject) mapping. OWASP likewise recommends reauthentication after risk events such as account recovery and suspicious activity.

This separation also controls blast radius. Provider metadata belongs in a cache with an explicit refresh policy; verified identity claims become input to resolution; resolution returns only a local principal ID; session issuance happens afterward. Don't let profile synchronization update ownership or recovery factors as a side effect of login. The convenient shortcut is exactly where discovery simplicity can leak into identity complexity.

How can refresh-token rotation contain a stolen session?

Model refresh-token rotation as a one-time state transition. Store only a digest of each refresh token, give related tokens a family ID, and consume the presented token in the same transaction that creates its successor. If an already consumed token appears again, assume the family may have been copied and revoke the whole family. The OAuth security best current practice describes rotation and sender-constrained refresh tokens as ways for public clients to detect replay.

Replay wins otherwise.

The example below is deliberately provider-neutral. The storage adapter must implement a serializable transaction or an equivalent compare-and-swap guarantee; without that guarantee, two concurrent refreshes could both look valid. invalid_grant is the useful outward result for an unusable refresh token, while detailed reason codes stay in restricted audit data.

type TokenRow = {
  id: string;
  familyId: string;
  digest: string;
  status: "active" | "consumed" | "revoked";
  expiresAt: Date;
};

type RotationResult =
  | { ok: true; refreshToken: string; accessToken: string }
  | { ok: false; error: "invalid_grant" };

interface TokenStore {
  transaction<T>(work: (tx: TokenStore) => Promise<T>): Promise<T>;
  findByDigestForUpdate(digest: string): Promise<TokenRow | null>;
  consumeAndInsert(currentId: string, next: TokenRow): Promise<boolean>;
  revokeFamily(familyId: string, reason: string): Promise<void>;
}

declare function sha256(value: string): string;
declare function randomToken(): string;
declare function randomId(): string;
declare function issueAccessToken(principalId: string): string;
declare function principalForFamily(familyId: string): Promise<string>;

async function rotateRefreshToken(
  store: TokenStore,
  presentedToken: string,
  now: Date,
): Promise<RotationResult> {
  return store.transaction(async (tx) => {
    const current = await tx.findByDigestForUpdate(sha256(presentedToken));

    if (!current || current.expiresAt <= now || current.status === "revoked") {
      return { ok: false, error: "invalid_grant" };
    }

    if (current.status === "consumed") {
      await tx.revokeFamily(current.familyId, "refresh_token_reuse");
      return { ok: false, error: "invalid_grant" };
    }

    const rawNext = randomToken();
    const next: TokenRow = {
      id: randomId(),
      familyId: current.familyId,
      digest: sha256(rawNext),
      status: "active",
      expiresAt: current.expiresAt,
    };

    const advanced = await tx.consumeAndInsert(current.id, next);
    if (!advanced) {
      await tx.revokeFamily(current.familyId, "concurrent_refresh");
      return { ok: false, error: "invalid_grant" };
    }

    const principalId = await principalForFamily(current.familyId);
    return {
      ok: true,
      refreshToken: rawNext,
      accessToken: issueAccessToken(principalId),
    };
  });
}

There is a sharp edge here — mobile clients retry after a lost response. Imagine request A consuming token 17 and committing token 18, while its response disappears on a subway handoff; the client retries token 17 as request B, which now looks exactly like an attacker replay. Strict reuse detection turns B into a family revocation. A narrowly bounded grace design can return the already-created successor for one retry, but it must bind that response to the same client context, expire quickly, and prevent token 18 from advancing twice. That expands state and replay analysis. I'm not sure one policy fits every client; packet-loss tests and the value of the protected action should decide. For money movement, favor containment and make reauthentication painless rather than quietly widening the replay window.

Identity resolution is an account-recovery policy

An external identity table should have a unique constraint on (issuer, subject) and point to a stable local principal. Keep email, display name, and provider-specific claims as attributes, not keys. This sounds fussy until the first recovery request arrives: support needs to distinguish “the provider changed my email” from “attach this different provider identity to my account,” and those actions need different proof.

Use explicit states for linking. An authenticated user may start a link attempt, complete the new provider flow, then confirm a fresh authentication factor before the mapping becomes active. An unauthenticated visitor who presents an email match should enter recovery, not linking. For a fintech account, recovery should revoke existing token families, require fresh authentication, and record which factor authorized the change. A stolen browser session must not be sufficient to replace its own recovery factor.

Keep it boring.

The catch is that strict separation adds support work when a customer loses the original provider and every registered recovery factor. A manual recovery path may be necessary, but it should be a distinct, audited business process with delayed high-risk actions; it should not be implemented as an email-based identity merge. If the business cannot operate that process, stick with a narrower set of providers whose account-recovery guarantees the risk team can evaluate. More login buttons would create liabilities, not resilience.

A practical resolution table is small:

Input state	Decision	Session effect
Known issuer and subject	Sign in the mapped principal	Issue a new local session
Unknown subject, authenticated linker	Require fresh proof, then attach	Revoke or rotate the linking session
Unknown subject, matching email only	Do not merge	Start account recovery
Refresh-token reuse	Reject the refresh	Revoke the entire token family
Confirmed stolen session	Reauthenticate the customer	Revoke all affected families

This is also where audit design earns its keep. Record principal ID, external-identity ID, token-family ID, policy decision, time, and a privacy-preserving request correlation ID. Avoid placing raw tokens or full identity claims in logs. A 401 count is useful, but invalid_grant split by expired, revoked, reused, and concurrent categories is what tells an operator whether rotation policy or an attack is driving recovery volume. Those internal categories must never make the public response more revealing.

Provider products differ at the control boundary

Three common products illustrate the decision without producing a ranking. Auth0 documents automatic reuse detection for refresh-token rotation; its managed control plane reduces the application code needed for that feature, while tenant configuration and account-linking policy remain part of the design. Amazon Cognito documents refresh-token rotation for user-pool app clients and exposes rotation settings through that service's configuration model, which suits teams already operating inside AWS but couples the identity control plane to that environment. Keycloak publishes OpenID Connect endpoints and can be operated by the team itself, which gives direct control over deployment and data handling but also makes upgrades, availability, key management, and security response the operator's job.

None of those boundaries answers whether two external identities represent the same legal customer. They also don't decide whether recovery revokes one device, one token family, or every session. Evaluate a provider by running the same acceptance tests against each candidate: exact issuer validation, unknown-key refresh, duplicate-link rejection, one-time refresh consumption, replay detection, global session revocation, and recovery without the original provider. Product demos tend to stop at the callback. The expensive behavior starts afterward.

Cost belongs in this evaluation, but not as a headline comparison. Count monthly active users, machine identities, audit retention, support burden, and the engineering hours required to test recovery and revocation. Published plan limits can change, and self-hosting shifts spend rather than removing it. Your mileage may vary with compliance scope and existing operations staff.

Operate recovery and revocation as one system

Ship the flow behind observable policy decisions. Before deployment, test two refreshes racing on the same token, replay of a consumed token, revocation followed by refresh, a provider signing-key change, an issuer mismatch, a changed email claim, and recovery while an attacker still holds a session. Verify the database constraints under concurrency rather than mocking them away. Then rehearse key rotation and token-family revocation in a staging environment with production-like session lifetimes.

In production, alert on sudden changes in refresh reuse, account-link attempts, recovery starts, and recovery completions. Set retention deliberately: enough to investigate an account takeover, but no longer than policy and regulation require. Review privileged recovery actions separately from routine login telemetry. A dashboard cannot prove identity; it can expose a broken decision rule before support turns that rule into habit.

The final selection rule is plain: prefer the provider strategy whose discovery metadata you can validate, whose tokens you can bind to a local identity model, and whose recovery boundary you can test under theft. If a candidate makes callback setup easy but leaves linking, revocation, or recovery semantics implicit, it is not suitable for a balance-bearing fintech account.

DEV Community