PATTERN Cited by 1 source

Dual-token session bridge

Intent

Exchange a validated external identity token (JWT from a managed identity provider) for an application-native session token in a single server-side operation, so the application can manage sessions independently of the identity provider after the initial bridge.

Structure

Client → Identity Provider: authenticate (SRP / OIDC / OAuth)
Client ← Identity Provider: JWT (sub, iss, exp, aud)

Client → Application Server: present JWT as credential
         [Server-side hook]
           1. Validate JWT cryptographically (5-step)
           2. Extract subject claim (e.g., `sub` UUID)
           3. Discard client-supplied identity — use only JWT claim
           4. Create or link user account by subject
           5. Issue application session token
Client ← Application Server: session token (independent lifecycle)

After the bridge, the JWT is never used again. All subsequent requests carry only the application session token.

Key properties

• Never trust client-supplied identity: the hook discards any identity value sent in the request body and overwrites with the cryptographically- verified claim from the JWT. This prevents impersonation via body manipulation.
• Independent lifecycle: the identity JWT and the session token can have different expiry times tuned to their respective concerns (identity = short for credential rotation; session = longer for gameplay continuity).
• Runtime decoupling: after the bridge, the application server never calls back to the identity provider. No network dependency on the IdP for ongoing session validation.

Canonical instance

The AWS Architecture Blog's Nakama + Amazon Cognito reference architecture (2026-06-29) implements this via Nakama's BeforeAuthenticateCustom Go hook:

• Client calls POST /v2/account/authenticate/custom with the Cognito JWT as the id field.
• The hook validates the JWT (format → RS256 → signature → expiry → issuer/client_id), extracts sub, sets in.Account.Id = sub, returns.
• Nakama creates or links the account and returns a session token.

(Source: sources/2026-06-29-aws-dual-token-authentication-for-nakama-game-servers)

When to use

• Application servers that manage their own sessions (game servers, real-time collaboration, chat) but want managed identity (MFA, social login, federation) without runtime coupling.
• Multi-platform clients (web, native, console) where the identity provider handles platform-specific auth flows and the application server is platform-agnostic.

Relationship to other patterns

• patterns/jwt-tenant-claim-extraction — same "never trust body, extract from JWT" principle applied to tenant isolation rather than identity bridging.
• patterns/pre-token-generation-hook — enriches the JWT at issuance time; the bridge pattern consumes the enriched JWT downstream.
• patterns/lambda-authorizer — validates JWT at the API Gateway layer; the bridge pattern validates inside the application server.

Seen in

• sources/2026-06-29-aws-dual-token-authentication-for-nakama-game-servers — Cognito → Nakama session bridge