[Design Discussion] Introduce a token family id (tfid) for grant-scoped revocation

[indeewari]

Related Feature Issue

Token Revocation, design discussion #3321. tfid is the prerequisite for the M3-b tranche of implicit revocation (grant-scoped behaviours), building on the merged deny-list work (#3727, #3803, #3839) and the in-review single-use rotation #3872 (M3-a).

---

Problem Summary

ThunderID issues stateless JWT access and refresh tokens, each with its own jti, and the revocation deny-list is keyed only by jti — one token at a time. Three revocation events in the authorization_code + refresh_token flows (the only flows that issue refresh tokens) must drop a whole login's tokens at once:

• Refresh reuse / replay — a stolen refresh token is replayed after the client already rotated it; the entire family from that login must die (including the attacker's freshly rotated tokens), not just the token presented.
• Explicit revocation / per-login sign-out — revoking a login's refresh token must also drop the access tokens issued from that same login.
• Authorization-code replay — a code redeemed twice signals compromise; the grant it produced should be killed.

The real requirement: revoke one authorization grant — the tokens from a single login+consent — precisely, without over-revoking the user's other logins or other apps. Today nothing links a token to its login (decoded tokens share only sub, client_id, scope, grant_type, iat), so matching on sub+client_id+scope over-revokes across independent grants.

This design adds tfid (token family id), a stable identifier for one grant's tokens, so revocation can target a whole family. (Backed by RFC 7009 §2.1 and RFC 9700 §4.14.2.)

"Token family" is shorthand, not a spec term; the concept is "the same authorization grant." Under non-forking rotation, family and grant are the same set of tokens (1:1).

---

Why not grant_id

In FAPI Grant Management, grant_id is a client-facing resource (GET/DELETE /grants/{id}, consent merge/replace). An internal, non-manageable grant_id would squat on that term and collide with real Grant Management later. tfid is internal, revocation-only, not exposed to clients. (family_id is avoided as it reads like a user attribute.)

---

High-Level Approach

tfid is an internal JWT claim identifying a token's family, plus a family dimension on the deny-list. No issued-token store — tokens stay stateless.

1. Mint one tfid (UUIDv7) during the login flow, at the step where the session participant is already recorded (see Logout) — so the SESSION_ID → tfid link is written with no extra DB call.
2. Propagate it: the flow assertion carries tfid → the authorization code stores it → the token builder stamps it onto the access and refresh tokens.
3. Copy it unchanged across refresh rotation — never regenerated, never forked.
4. Revoke by family: a write records the revoked tfid; AS + RS enforcement reject any token carrying it, alongside the existing jti check.
5. Stay forward-compatible with FAPI Grant Management — same semantics, internal identifier now, not the client-facing API.

Unblocks the M3-b toggles (#1, #2, #5, #6).

What tfid identifies

A per-authorization-event UUIDv7, not hash(client_id + subject). The same user at the same client can authorize multiple times, each independently revocable:

Login #1:  user U + client C  →  tfid F1
Login #2:  user U + client C  →  tfid F2   ← different id

RevokeFamily(F1) kills login #1 only. A hashed id would collapse both. The same tfid rides every token of the authorization and every rotation; a new one is minted only for a new grant.

Invariant: generate once, never fork

Rotation must be atomic (check-and-invalidate the presented refresh token under one lock) so it can't be redeemed twice into two live children. This keeps 1 grant : 1 family; a fork would split a grant across two families and let revocation miss a branch.

Revocation hierarchy — one claim, coarser scopes resolve to families

The SSO session is 1:N with grants — one session (grouped by FlowID) authorizes many apps:

SSO session (SESSION_ID)          ← 1
 └── authorization grant           ← N   (one per app in the session)
      └── token family (tfid)      ← 1:1 with the grant
           └── tokens (jti)          ← N   (via rotation)

The token carries only tfid. Coarser scopes need no extra claim: the AS resolves them to a set of families at revoke time from persisted relationships. Logout enumerates the session's families and revokes each tfid. The session id is deliberately not on the token — one session backs many apps, so a session-valued claim would over-revoke on a single app's replay and would expose a session identifier (C-High) to resource servers.

Axis	Revokes	Resolves to	Match key
Single token (RFC 7009)	one token	itself	jti
Family / grant (this design)	one family	itself	tfid
Session / logout	all families in a session	the session's tfids	tfid
Criteria-based (Phase 2)	attribute match	attribute + time	sub/client_id/role

Enforcement matches only jti and tfid (plus Phase-2 attributes); session revocation adds no new match dimension, it just writes more tfid rows. Exact-jti lives in REVOKED_TOKEN; everything else shares one criteria table.

---

Architecture Overview

• Claim ClaimTokenFamilyID (tfid) in internal/oauth/oauth2/constants.
• Minting + linkage — tfid is minted in the flow at the participant-write step, and the SESSION_ID → tfid mapping is stored on that same existing write (SSO_SESSION_PARTICIPANT is upserted on every login), so there is no extra login round-trip.
• Propagation — the flow assertion carries tfid → stored on the AUTHORIZATION_CODE record → the back-channel token exchange (no session context) stamps it onto AT/RT → RefreshTokenClaims carries it so rotation copies it (no regeneration).
• Code-replay revocation — the retained INACTIVE code record carries its tfid; replay is already detected (errAuthorizationCodeAlreadyConsumed, authz/service.go), so the handler reads the tfid and calls RevokeFamily(tfid), closing the existing revoke-on-replay TODO.
• Storage — tfid revocation is a row in the criteria-based revocation table (a generalized attribute+time deny-list also backing subject/client/consent revocation): CRITERION_TYPE='token_family', CRITERION_VALUE=<tfid>. A revoked family is terminal, so membership alone suffices (the generic iat < revoked_at predicate is always true here):

REVOCATION_CRITERIA (DEPLOYMENT_ID, ID, CRITERION_TYPE, CRITERION_VALUE, REASON, REVOKED_AT, EXPIRY_TIME)
  INDEX (DEPLOYMENT_ID, CRITERION_TYPE, CRITERION_VALUE)   -- match lookup
  INDEX (EXPIRY_TIME)                                       -- cleanup scan

EXPIRY_TIME = REVOKED_AT + max_refresh_token_lifetime; one prune covers all criterion types. Exact single-jti revocation stays in REVOKED_TOKEN.

• Enforcement — AS revocation service and RS revocationcache consult the revoked-tfid set; the security middleware surfaces tfid alongside jti.

flowchart LR
    subgraph AS["Authorization Server"]
        GC["Login flow<br/>mint tfid F<br/>write participant SESSION_ID to F"] -->|"F via assertion then code"| TB["Token builder<br/>stamps tfid F"]
        TB --> AT["Access token<br/>jti and tfid F"]
        TB --> RT["Refresh token<br/>jti and tfid F"]
        RT -->|"refresh / rotation"| RH["Refresh handler<br/>copies F onto new AT and RT"]
        RH --> TB
        EV["Revoke event<br/>explicit / reuse<br/>code-replay / logout"] --> RG["Revoke-by-family<br/>write seam"]
    end
    RG -->|"criterion row token_family=F"| DB[("Runtime-persistent DB<br/>REVOCATION_CRITERIA and REVOKED_TOKEN")]
    DB -.->|"AS reads, RS cache syncs"| ENF["EnsureNotRevoked jti tfid"]
    AT -.present.-> ENF
    RT -.present.-> ENF
    ENF -->|"jti OR tfid revoked"| REJ["reject 401 / invalid_grant"]
    ENF -->|"neither revoked"| OK["allow"]

Loading

sequenceDiagram
    autonumber
    participant C as Client
    participant AS as Authorization Server
    participant DB as Runtime-persistent DB (deny-list)
    participant RS as Resource Server (cache + middleware)

    Note over AS: Login flow (front-channel)
    AS->>AS: mint tfid F, write participant SESSION_ID to F
    Note over AS: Authorization-code exchange (back-channel)
    C->>AS: code + client auth
    AS->>AS: read tfid F from the code record
    AS-->>C: AT1 tfid=F, RT1 tfid=F

    Note over AS: Refresh (rotation)
    C->>AS: refresh_token = RT1
    AS->>DB: revoke RT1.jti (M3-a single-use)
    AS-->>C: AT2 tfid=F, RT2 tfid=F

    Note over AS: RT1 replayed, reuse detected
    C--xAS: refresh_token = RT1 (stolen copy)
    AS->>AS: RT1.jti already revoked, reuse
    AS->>DB: RevokeFamily(F), one criterion row

    Note over RS,DB: Enforcement afterwards
    C->>RS: request with AT2 (tfid F)
    RS->>RS: EnsureNotRevoked(jti, F), F revoked
    RS-->>C: 401 invalid_token

Loading

---

Logout and session revocation

The SSO session is persisted (SSO_SESSION + per-app SSO_SESSION_PARTICIPANT, runtime_persistent), established during login before any token exists: session → participant → code → token. Because tfid is minted at the participant write, the SESSION_ID → tfid mapping (1:many, for in-session re-consent) is captured with no extra DB call, and no session id ever goes on the token. Session revocation is then resolve the session to its families, then revoke each:

Terminate(session S)                       // logout — always revokes
  txn:
    tfids ← SELECT tfid WHERE session = S
    INSERT REVOCATION_CRITERIA(token_family, tfid) for each     // revoke first
    DELETE participants / session / contexts
  commit

• Single-app logout → revoke that app's family; full logout → revoke every family in the session.
• Revoke before delete, in one transaction, so a crash can't orphan live tokens.
• Session expiry is decoupled by default: session deadlines govern silent SSO, not token lifetime — refresh tokens live to their own exp. Expiry deletes the session without revoking unless oauth.revocation.session.cascade is on (then the sweep runs the same revoke-then-delete).

This deliberately avoids both obvious alternatives and their costs: a separately written server-side mapping (an extra login DB call) and a sid claim on tokens (a C-High session identifier exposed to resource servers, and off-label — RFC 9068 defines no sid for access tokens; OIDC scopes sid to ID/Logout tokens). Minting at the participant write pays neither cost.

---

Where families exist

Only authorization_code (and its refresh continuations) issues a refresh token, so it is the only flow with a true family and the only flow with an SSO session. The rest are access-token-only, so logout/session revocation doesn't apply; they revoke by jti or by attribute:

• token_exchange (RFC 8693) — derived from a subject token; configurable: inherit the subject's tfid or stay independent.
• client_credentials — no user/session/refresh; revoke by jti or client_id. Default: no tfid.
• ciba — no refresh; single access (+ID) token. Optional shared tfid.

---

Security Considerations

• No session id on the token — the token carries only the opaque tfid; the session id stays server-side (C-High per WSO2 data classification), so tokens leak no session grouping to resource servers and one app's revocation never touches another's.
• Opaque, unguessable — UUIDv7, not derived from user/client; no cross-grant information, can't be forged into another family.
• Never-fork — atomic rotation + immutable tfid keep 1 grant : 1 family, so revocation can't miss a branch.
• Fail-closed + scope-preserving — deny-list unavailable ⇒ reject; tfid propagation must not widen a rotated token's scope (RFC 6749 §6).
• Backward compatible — pre-rollout tokens carry no tfid; family revocation is a bounded, expiry-limited no-op for them.

---

Impacted Areas

flow/session (mint tfid + store SESSION_ID → tfid on the participant write; revoke-on-logout, optional revoke-on-expiry) · flow assertion (carry tfid) · authz/{service,auth_code_store,model} (store tfid on the code; revoke-on-replay) · tokenservice builder + RefreshTokenClaims · granthandlers/{refresh_token,authorization_code,token_exchange}.go · revocation (write + AS enforcement) · revocationcache + security middleware · dbscripts/runtime_persistent (new REVOCATION_CRITERIA; tfid on AUTHORIZATION_CODE and the participant mapping) · config (oauth.* M3-b toggles + oauth.token_exchange.family + oauth.revocation.session.cascade) · docs.

---

Alternatives Considered

1. Reuse sub+client_id+scope — over-revokes concurrent grants, can't walk a rotation chain. Rejected.
2. Stateful issued-token store — abandons stateless JWTs, write-per-issuance cost. Rejected.
3. Parent-jti lineage chain — helps only the RT chain, O(n) walk. Rejected.
4. sid (session id) on tokens for O(1) logout — exposes a C-High session identifier to resource servers / shared infrastructure (cross-app correlation), and is off-label for access tokens (RFC 9068 / OIDC scope sid to ID and Logout tokens). Rejected in favour of minting tfid at the participant write — no session id on the token and no extra login write.
5. Full FAPI Grant Management now — far larger surface, client-facing grant_id. Adopt the internal identifier now, revisit FAPI separately.

---

Questions for Community Input

1. Naming — internal claim tfid (not grant_id, reserved by FAPI; not family_id). Agree?
2. Storage — tfid as CRITERION_TYPE=token_family in the shared criteria table; keep exact-jti in REVOKED_TOKEN or fold it in? Final table name?
3. Lifetime bound — EXPIRY_TIME = longest-lived token (≈ refresh validity), or a fixed max-family-lifetime?
4. Grant boundaries — token_exchange inherit vs independent? Do client_credentials/ciba carry a tfid at all?
5. Rollout — accept pre-tfid tokens un-revocable by family until expiry, or backfill?
6. Session linkage — confirm minting tfid at the participant write (mapping piggybacks an existing login write; no session id on the token) over a separate mapping write or a sid claim; and oauth.revocation.session.cascade default off?
7. Cascade defaults — RT→ATs (Add initial server implementation #1) on, AT→RT (Fix integration tests with embedded sqlite and refactoring #2) off, code-replay revoke (Minor refactoring #5) on, reuse→family (Add more integration tests for client credentials grant #6) on.

[senthalan]

Regarding the storage, can we generalise the storage layer for that we can store any revoked key and value. So we don't need to introduce new tables and new sql queries or Redis queries.

[Thumimku]

Token Family Revocation Configuration

Currently, three separate configurations have been introduced for token family revocation:

Configuration	Default	Description
oauth.revocation.token_family.on_refresh_replay	true	If an already-rotated refresh token is presented again, revoke every token associated with that login. This helps mitigate stolen refresh-token replay. This configuration is effective only when renew_on_grant is enabled.
oauth.revocation.token_family.on_explicit_revoke	true	When a client explicitly revokes a token through RFC 7009, also revoke the remaining tokens associated with that login, allowing related access and refresh tokens to be invalidated together.
oauth.revocation.token_family.on_code_replay	true	If an authorization code is redeemed more than once, revoke all tokens issued as a result of its first successful redemption. Since authorization codes are single-use, a replay can indicate that the code has been compromised.

Documentation status: All three configurations are currently missing from the documentation.

Proposal: Consolidate into a Single Configuration

Beyond the specification-level MUST/SHOULD requirements for the individual scenarios, these three configurations appear to represent the same higher-level security policy: whether token-family revocation should be applied when a compromise/revocation condition is detected.

From a developer's perspective, if token-family revocation is desired, there may be little practical value in enabling or disabling these behaviors independently. A single configuration could therefore be sufficient:

oauth.revocation.token_family.enabled

When enabled, token-family revocation would apply to all supported trigger conditions:

1. Refresh-token replay
2. Explicit token revocation through RFC 7009
3. Authorization-code replay

This would simplify the configuration surface and provide a clearer security model: token-family revocation is either enabled for the authorization/login session or disabled.

@thiva-k @senthalan @indeewari @darshanasbg @omindu WDYT?

[indeewari]

Thanks @Thumimku, worth questioning the config surface.

The documentation was added recently

https://thunderid.dev/docs/next/guides/protocols/oauth-oidc/token-revocation/#what-revokes-a-family
Code replay and refresh replay are us reacting to a possible attack. Explicit revoke is the client asking for something on purpose. A deployment can reasonably want a strong reaction to attacks, but not want a client revoking one access token to drop the whole login. One flag takes that choice away.

A middle ground. If the goal is a smaller surface, we could merge the two attack-detection triggers and leave client intent alone:

oauth.revocation.token_family.on_replay_detected   # code replay + refresh replay
oauth.revocation.token_family.on_explicit_revoke   # unchanged

WDYT ?

Thanks and Regards