[Design Discussion] Token revocation in Thunder ID

[indeewari]

Related Feature Issue

• Add token revocation support #795

Problem Summary

Thunder ID was initially designed without a token revocation mechanism — a deliberate choice, as self-contained JWTs with short expiry are the approach recommended by OAuth 2.0 best practices for stateless systems. For many deployments, short-lived access tokens are sufficient.

However, short expiry alone does not cover all revocation requirements. Once a token is issued, there is no mechanism to invalidate it before its exp claim is reached, even if the user is deleted, loses a role, the client is deregistered, or a security compromise is detected. The design below introduces a server-side blocklist to close this window, in phases that each deliver independently useful revocation capability.

High-Level Approach

Because Thunder ID's tokens are stateless JWTs, revocation is implemented as a server-side blocklist: when a token is revoked, a lightweight record is written and every subsequent validation at Thunder ID gates on that list. Resource servers can verify token validity by calling POST /oauth2/introspect, but making that call on every incoming request adds latency that most resource servers prefer to avoid when validating JWTs locally. Therefore introduces a push notification mechanism: on every write to the blocklist or criteria store, Thunder ID notifies resource servers so they can update a local revocation cache and check it locally — no per-request call needed.

At an abstract level, token revocation in an authorization server can be categorized into two flows. The first is single-token revocation, which includes direct revocation via an API call or auth code replay — in these cases, the JTI of the revoked token can be explicitly identified. The second is bulk token revocation, which applies in scenarios such as client secret regeneration or changes to user permissions, where multiple tokens are invalidated at once rather than individually. Here we identify a token revocation criteria rather than a JTI.

flowchart TB
    A["Token Revocation"]
    B["Single token revocation"]
    JTI[("Token deny list by JTI")]
    C["Bulk token revocation"]
    Criteria[("Token deny criteria")]

    A --> B
    B --> JTI
    A --> C
    C --> Criteria

Loading

Based on the above, our first milestone is to focus on the single-token revocation path.

flowchart TB
    subgraph ThunderID["ThunderID"]
        subgraph ThunderAS["ThunderID Authorization Server"]
            direction TB
            SingleRevoke["Single token revocation"]
            RevocationService["Revocation Service"]
            RevocationStore[("Enforcement DB\n(Token deny list by JTI)")]
            Notifier["Notifier"]
            subgraph TokenValidatorAS["Token Validator"]
                direction LR
                ATValidator["Access token validator"]
                RTValidator["Refresh token validator"]
                ACValidator["Auth code validator"]
            end
            subgraph InternalAS["OAuth Services"]
                direction TB
                TokenExchange["Token exchange"]
                Introspection["Introspect"]
                RevokeToken["Revoke token"]
                RefreshToken["Refresh token"]
                IssueToken["Issue token\n(Auth Code replay)"]
            end
            RevokeToken -->|"Revoke token"| SingleRevoke
            RefreshToken -->|"Revoke token"| SingleRevoke
            RefreshToken --> TokenValidatorAS
            IssueToken -->|"Revoke token if replay detected"| SingleRevoke
            SingleRevoke --> RevocationService
            RevocationService -->|"Add to the deny list"| RevocationStore
            RevocationService -->|"Publish to internal notification layer"| Notifier
            TokenExchange -->|"Validate token before exchange"| TokenValidatorAS
            Introspection -->|"Validate token to get token status"| TokenValidatorAS
            TokenValidatorAS -->|"Check deny list hit"| RevocationStore
        end
        subgraph ThunderRS["ThunderID Resource Server"]
            direction TB
            NotificationHandler["Notification Handler"]
            RevocationCacheService["Revocation Cache Service"]
            RevocationCache[("Revocation Cache")]
            TokenValidatorRS["Token Validator"]
            subgraph InternalRS["Resource Access Authorization"]
                direction TB
                AdminAPIs["Admin APIs"]
                MCPServerAccess["MCP Server Access"]
                UserInfo["User Info"]
            end
            AdminAPIs --> TokenValidatorRS
            MCPServerAccess --> TokenValidatorRS
            UserInfo --> TokenValidatorRS
            TokenValidatorRS --> RevocationCacheService
            NotificationHandler --> RevocationCacheService
            RevocationCacheService --> RevocationCache
        end
    end

    subgraph ExternalRS["External Resource Server"]
        direction TB
        Webhook["Notification Endpoint"]
        Cache[("Local Cache")]
        TokenCheck["Token Validator"]
        Authz["Resource Access Authorization"]
        Webhook --> Cache
        Authz --> TokenCheck
        TokenCheck --> Cache
    end

    subgraph Legend["Legend"]
        direction LR
        CoreLegend["Core architectural modification"]
        FeatureLegend["Feature-level modification"]
    end

    ExternalWebhookManager["External Webhook Manager"]
    Notifier --> ExternalWebhookManager
    ExternalWebhookManager --> NotificationHandler
    ExternalWebhookManager --> Webhook

    classDef dotted stroke-dasharray: 4 4,fill:none
    classDef coreStyle fill:#FFE8CC,stroke:#FF9900,color:#000000
    classDef featureStyle fill:#DBEAFE,stroke:#3B82F6,color:#000000

    class ThunderID dotted
    class RevocationStore,NotificationHandler coreStyle
    class RevokeToken,SingleRevoke,RevocationService,RevocationCache,RevocationCacheService,TokenValidatorAS,Notifier,ExternalWebhookManager,TokenValidatorRS featureStyle
    class CoreLegend coreStyle
    class FeatureLegend featureStyle

Loading

Core Architectural Modifications

1. Introducing database.enforcement — a new data classification

Token revocation data does not fit ThunderID's existing database classifications. Runtime DB is for short-lived transactional state; criteria-based revocation records (by sub or client_id) have no natural expiry and must survive a Runtime DB flush. Config DB holds system configuration, not runtime enforcement decisions. User DB holds identity, not authorization state.

Revocation data is event-driven at runtime but must persist beyond any single session — a combination no existing classification addresses. This introduces database.enforcement: the authoritative store for authorization enforcement state, including token revocation records and consent history. It establishes a foundation for future enforcement-oriented data such as audit logs.

2. Notification listening mechanism for ThunderID Resource Server

ThunderID's own Resource Server have no facility to receive or respond to revocation events. A notification listening mechanism is introduced, allowing revocation events from the Authorization Server to be delivered in-process via the internal event bus, populating a local Revocation Cache that token validators consult at request time — without a network round-trip to the introspection endpoint.

Feature-Level Modifications

ThunderID Authorization Server

1. /oauth2/revoke endpoint
   Implements RFC 7009, enabling clients and administrators to explicitly revoke a specific token by presentation. The token's JTI is written to the Revocation Store and a TOKEN_REVOKED event is published to trigger downstream notification.

HTTP contract:

Condition	Status	Error
Success (including invalid/expired/unknown token)	200	—
Missing token parameter	400	invalid_request
Unsupported token type	400	unsupported_token_type
Token belongs to a different client	400	invalid_grant
Client authentication failure	401	invalid_client
Server error	500	server_error

2. Revocation Data
   New table REVOKED_TOKEN in database.enforcement stores one row per revoked token JTI. Only single-token revocation flows write to this table.

Column	Description
ID	UUID, Primary key
DEPLOYMENT_ID	Multi-tenancy key present on every table
JTI	jti JWT claim — the deny list lookup key
TOKEN_TYPE	Access token or refresh token
REVOKED_AT	Timestamp of the revocation event (audit)
EXPIRY_TIME	Token's original expiry; record can be dropped once this passes

3. Admin governance for implicit revocation
   Introduces server-level configuration to govern implicit revocation behaviour on the single-token path — including refresh token rotation enforcement and revocation of tokens issued from a replayed authorization code.

4. Token validation against revocation data
   Extends the shared token validation path (introspection, refresh grant, token exchange) to consult the persisted revocation data on every validation. Tokens whose JTI or issuing principal appears in the store are rejected regardless of cryptographic validity.

5. Outbound notification to external Resource Servers
   When a token is revoked, the Revocation Notifier resolves target Resource Servers from the token's aud claim and dispatches a signed webhook payload via the External Webhook Manager, with configurable retry and backoff.

ThunderID Resource Server

1. Revocation Cache
   Introduces a local Revocation Cache, populated by inbound revocation notifications.

2. Token validation against revocation cache
   Extends token validation on all first-party Resource Server surfaces to consult the Revocation Cache on each request. A cache hit results in immediate rejection. A cache miss bounds worst-case exposure to the token's natural lifetime.

Architecture Overview

Revocation dimensions

A token is considered revoked if any one of these dimensions returns a hit at the
blocklist / criteria:

Dimension	Store key	Check	When written	Store
JTI	jti	Exact match	POST /oauth2/revoke; old RT on rotation	Runtime
Client	client_id	Exact match	DELETE /oauth2/dcr/register/{client_id}	Config
Forced subject	sub	revoked_at >= token.iat	User deletion, suspension, password reset	Config
Scoped subject	sub:client_id	revoked_at >= token.iat	Role removed; permission withdrawn for user-app	Config
Subject	sub	revoked_at >= token.iat	OIDC logout (end_session_endpoint) — Phase 3	Config

Flows covered

Flows that triggers token revocation

Flow	Spec	What triggers revocation	Revocation scope	Example	Priority
Direct token revocation	RFC 7009	Client calls POST /oauth2/revoke	Single token (JTI blocklisted)	A mobile app detects its device is lost/stolen and immediately revokes the refresh token stored on it, before the finder/thief can use it	1
Refresh token rotation	RFC 6749	New refresh token issued at token endpoint	Consumed refresh token (JTI blocklisted)	A long-lived SPA refresh token leaks via an XSS bug; rotation means the leaked token is single-use, so the attacker's window closes the next time the legitimate client refreshes	TBD
Refresh token replay	RFC 6749 §10.4	Rotated RT presented again at token endpoint	invalid_grant returned; grant-level deferred	An attacker holding an already-rotated stolen refresh token tries to redeem it; the replay attempt itself becomes a compromise signal that can optionally trigger full grant revocation	TBD
Auth code replay	OAuth 2.0 Security BCP §4.2.4	Code presented a second time at token endpoint	invalid_grant returned; grant-level deferred	A malicious logging proxy captures an authorization code in transit and replays it after the legitimate client already redeemed it	TBD
Client/application deletion	-	Delete application is called via console or API	All tokens for the deleted client	An admin offboards a third-party partner integration by deleting its application registration; its outstanding tokens must stop working immediately, not linger until natural expiry	TBD
Client deregistration	RFC 7592 §2.3	DELETE /oauth2/dcr/register/{client_id}	All tokens for the deregistered client	A CLI tool that self-registered via DCR calls its own configuration endpoint to deregister itself on uninstall, with no admin involved	TBD
User lifecycle	—	User deleted, suspended, or password reset	All tokens for the user, no exceptions	A user reports their account compromised and resets their password; any token an attacker already holds must be killed immediately rather than riding out its TTL	TBD
Permission change	—	Role removed or scope withdrawn for a user-application pair	Tokens for that user-application pair only	An admin revokes a user's billing-admin role mid-day; without this, the user's live access token keeps the old scope until it naturally expires	TBD
OIDC logout (Phase 3)	OIDC RP-Initiated Logout 1.0; OIDC Back-Channel Logout 1.0	User initiates logout via end_session_endpoint	Session-bound tokens for the user; offline_access tokens exempt	A user clicks "sign out everywhere" in an SSO hub; ThunderID must end the session and back-channel-notify every relying party so they drop their local sessions too	TBD
Consent revocation	-	User revokes consent for scopes already granted in a live access token	Tokens carrying the revoked scopes of that user-application pair	A user opens their privacy settings and revokes a third-party app's access to their calendar; the app's live token should lose calendar:read rather than keep it until expiry	TBD

Flows that requires to evaluate the validity of the token once token revocation is introduced

Flow	ThunderID's role here	Why
Token introspection (/oauth2/introspect)	Authorization Server	RFC 7662 defines introspection as an AS capability — ThunderID is answering a query about a token, not consuming the token to access its own protected resource.
Refresh token grant	Authorization Server	Token lifecycle management — issuing new tokens — is core AS responsibility.
Token exchange grant	Authorization Server	Same — minting a new token from an existing one is an AS function.
Protected admin/management API access (Console/REST: users, roles, applications, resource servers, etc.)	Resource Server	ThunderID's own management API is a protected resource being accessed with a bearer token, exactly like any third-party API. The AS and RS happen to be the same process, but the role in this interaction is RS.
UserInfo endpoint (/oauth2/userinfo)	Resource Server	OIDC Core §5.3 explicitly defines UserInfo as "an OAuth 2.0 Protected Resource" — it's co-located with the AS, but it's consuming the token, not issuing/inspecting it on behalf of someone else.
MCP server access (/mcp/**)	Resource Server	Same pattern — first-party protected resource validating a bearer token to authorize access.

[Future] Introducing a grant store

A new table will be introduced to manage grants, enabling users to list and
revoke their active sessions per device to handle offline_access cases.

GRANT_ID	SUB	CLIENT_ID	SCOPES	STATE	CREATED_AT	LAST_USED_AT	DEVICE
g-abc1	alice	app-mobile	openid offline_access	ACTIVE	2026-05-01 10:00:00	2026-05-01 10:00:00	iPhone 15
g-abc2	alice	app-mobile	openid offline_access	ACTIVE	2026-05-15 14:00:00	2026-05-15 14:00:00	Samsung Galaxy
g-abc3	alice	app-web	openid profile	ACTIVE	2026-06-12 08:00:00	2026-06-12 08:00:00	Chrome / macOS

Security Considerations

Token ownership enforcement. The revocation service verifies the token was issued to the requesting client. A mismatch returns invalid_grant, preventing a client from revoking another client's tokens.

Expired tokens remain revocable. Signature-only verification is used —blocking on expiry creates a race condition at token expiry and breaks revocation under clock skew.

User deletion leaves no window. Forced subject revocation applies regardless of client or offline_access scope. A deleted or suspended user's tokens are invalid on the next validation call.

Runtime database erasure is bounded. Loss of the token blocklist is bounded by token lifetime. Criteria records survive because they live in the config database.

Push notification delivery is best-effort with bounded miss window. If a resource server misses a push notification (due to downtime or network partition), it continues to accept revoked tokens until the next successful startup sync. The miss window is bounded by the access token's remaining lifetime — after exp, the token is rejected by standard expiry validation regardless.

Impacted Areas

• Authentication
• User management

Alternatives Considered

Single table in the runtime database. A runtime database wipe would silently restore access for deleted users and deregistered clients. Two tables split by durability requirement — runtime for JTI entries, config for criteria — was chosen.

Expiry on criteria records derived from server max token validity. Unsafe when token validity is per-application; criteria records are managed explicitly instead.

Single table per revocation type. A type-discriminator in one criteria table covers all lookup patterns with fewer migrations and cleanup jobs.

User deletion as standard subject revocation. This would leave offline_access tokens valid after account deletion. A distinct forced revocation type with no exemption was chosen.

Questions for Community Input

1. Resource server token validation in practice — In your deployments, how do resource servers typically handle JWT token validation — purely local (signature and expiry only), via introspection on each request, or via a cached model? Understanding common patterns would help us prioritize the integration approach.
2. Revocation requirements driven by compliance — Are there compliance frameworks (FAPI, healthcare, government) or enterprise security policies in your use cases that mandate immediate token revocation? If so, which token types — access tokens, refresh tokens, or both — are in scope?

[rajithacharith]

Hi @indeewari
Let's consider ThunderID Resource server as a separate resource server without making any special treatments as we support deploying ThunderID Resource server secured with a separate ThunderID Authorization server

[indeewari]

Hi @rajithacharith ,

Thank you for the feedback — I've updated the discussion to reflect the decoupled deployment requirement.

Thanks and Regards

[thiva-k]

Hi @indeewari,
Regarding flows to consider in token revocation we should also consider CIBA issued tokens too, since CIBA has an async authentication flow, the criteria based revocation check should be done before issuing the token(similar to token exchange and refresh token grants)

And may also need to check when DPoP bound tokens are needed to be revoked via the revocation endpoint, whether the revocation request needs to be sent with the DPoP proof.

[indeewari]

Hi @thiva-k ,

Thank you for the feedback. We will incorporate these flows as well. Per the current design, all token verification at the ThunderId authorization server is routed through a central point — these flows fall within that scope and must be validated accordingly. Test cases for these flows are mandatory and will be included in the test paths.

Noted:
CIBA
DPoP

Thank you.

[thiva-k]

We also have a JTI_RECORD table in the runtime db currently to prevent replay in DPoP and private key jwt authentication. We may need to evaluate whether we can use the same revocation table to store this data too.

[indeewari]

Hi @thiva-k ,

The recommendation for a new database stems from the current data classification constraints. While the runtime database can store transactional data, it does not guarantee persistence — and any data loss in token revocation would constitute a critical security incident, unlike DPoP. Therefore, a transactional, persistent data store is required.

Thanks

[piraveena]

@indeewari , I have below question here?

1. Does this effort incorportate access token revocation too via APIs?
2. When a refresh token is revoked, are we revoking the corresponding access tokens too?

[indeewari]

Hi @piraveena ,

1. Yes, an OAuth2 /revoke endpoint will be introduced as part of this effort.
2. There is no mandatory specification requirement for this case — we can default to the most secure approach while providing configuration options for flexibility.

Thank You