3.5 Token Validation (Assertion Flow)

Scope

Defines the short-lived, audience-restricted player assertion flow used to authenticate third-party apps (e.g., Cloud Save) without exposing write-capable game keys or write-scoped JWTs.

Summary

Gamers Lab issues two JWTs to the game client in a step-by-step process:

1. A normal game JWT for GL writes.
2. A short-lived, audience-bound assertion token for third-party identity verification.

The third-party app introspects the assertion with Gamers Lab using its own read API key that has allow_auth enabled. No API key is ever embedded in the assertion.

Purpose

This second auth method allows game clients to authenticate into third-party applications without sharing a write-authorized JWT or the X-Game-Key. Instead, the game client fetches a second JWT that is tightly scoped to a specific third-party application by name and used for authorization purposes only.

The third-party application must register at Gamers Lab first and request an X-API-Key (read-only key), and the game owner must enable third-party authorization. This allows game clients to safely sign players in to third-party applications without compromising sensitive information, while allowing third-party applications to verify that a player is a registered member of a specific game.

Actors and Keys

• Game client: holds the player JWT used for game data writes.
• Gamers Lab API: issues and validates JWTs.
• Third-party app (e.g. Cloud Save): holds a tenant API key with allow_auth=true.
• Tenant API key: stored in bus_tenant_api_keys with allow_auth flag.

Tokens

Game JWT (player scope):

• Used for normal game API writes.
• Issued during player login.

Assertion JWT (verify scope):

• Short TTL: 120 seconds.
• aud must equal the tenant API key name.
• Scope is verify and auth type is player.
• Contains tenant_id, player_id, player_role, auth_provider, and optional email.
• Does not contain any API key or secret.

Endpoints

• POST /api/player-auth/jwt/exchange
  • Requires Authorization: Bearer <player_jwt>.
  • Accepts audience (string name of the third-party API key).
  • Issues the short-lived assertion token.
• POST /api/player-auth/jwt/validate
  • Requires X-API-Key with allow_auth=true.
  • Accepts the assertion token and validates it online.

Flow

1. Player logs in and receives the normal game JWT.
2. Game client calls /api/player-auth/jwt/exchange with the player JWT and the audience string (API key name).
3. Gamers Lab issues the assertion JWT with aud=audience, scope=verify, TTL 120s.
4. Game client sends the assertion JWT to the third-party app.
5. Third-party app calls /api/player-auth/jwt/validate with its X-API-Key and the assertion JWT.
6. Gamers Lab validates the assertion online and returns the player identity claims for that tenant.
7. Third-party app mints its own session JWT for future calls.

Validation Rules

Exchange (/exchange):

• Player JWT must be valid and have auth_type=player and scope=player.
• tenant_id and player_id must be present.
• The current player profile must still resolve to an active account.
• The player must not currently be banned from the tenant.
• audience must be provided; this is the API key name.

Validate (/validate):

• API key must be valid and have allow_auth=true.
• Assertion JWT must validate in a single pass for signature, issuer, expiry, and aud.
• Assertion JWT must have auth_type=player and scope=verify.
• Assertion tenant_id must match API key tenant.
• Assertion aud must match the API key name used in the X-API-Key request.

Security Notes

• The assertion is short-lived (120 seconds) and cannot be used for GL writes.
• The assertion is bound to a specific third-party API key name via aud.
• /exchange re-checks current active-profile state and tenant bans before minting an assertion.
• /validate enforces the assertion audience during JWT validation itself; it does not do a second unvalidated audience parse.
• The API key X-API-Key itself is never sent to the game client.
• The game client should never expose any keys to third parties.
• Introspection is online-only; third parties must call /validate (no local JWKS verification).

Code References

• Exchange and validation: GamersLabRestAPI/PlayerAuth/Controllers/PlayerTokenValidationController.cs
• JWT generation/validation: GamersLabRestAPI/Shared/Service/JwtService.cs
• API key allow-auth claim: GamersLabRestAPI/Saas/Business/Constants/ClaimTypes.cs
• API key middleware allowlist: GamersLabRestAPI/Saas/ApiKeys/Middleware/ApiKeyUseCaseMiddleware.cs

---