[Design Discussion] Criteria-based token revocation for group, role and scope changes

[indeewari]

Related Feature Issue

#4127

Status: implemented. This document has been updated to match what shipped in
#5406. Where the implementation diverged from the original proposal, the text
now describes the shipped behaviour and says so; the alternatives and the reasoning behind each
decision are kept as they were.

Problem Summary

An access token is a snapshot: it is minted with the scopes the principal held at that moment and
stays valid until it expires. Removing a user from a group, unassigning a role or trimming a role's
permissions changes what the next token carries and changes nothing about tokens already issued. We
already close this gap for application deletion and client secret regeneration through ADMINISTRATION
flows; this design extends the same machinery to authorization changes.

High-Level Approach

Group, role and scope changes all reduce to one question: which scopes did this principal just
lose, and at what time? A token carries sub, aud and scope, never role or group IDs, so the
criterion has to be expressed in those terms whatever the operator actually clicked.

• Add one criterion dimension, entity.scope, plus a coarser scope dimension for scope deletion.
• Onboard six ADMINISTRATION flows that revoke before they act, reusing CriteriaRevocationExecutor,
  the deny-list table, the SQL and both enforcement points unchanged.
• Record revocations as boundary rather than terminal, so a reverted grant heals itself.
• Leave every native management endpoint untouched: revocation has exactly one home, the flow.

A scope name alone does not identify a scope

The obvious encoding, <entity>|license, is wrong. A permission string is unique only within its
resource server. derivePermission builds a root resource's permission from its handle alone, with
no resource server prefix. The schema already says so: ROLE_PERMISSION is keyed on
(ROLE_ID, DEPLOYMENT_ID, RESOURCE_SERVER_ID, PERMISSION), with the resource server in the key
precisely because the permission alone identifies nothing.

This is not theoretical. In our own US-geography test deployment 7 of 18 scope names are defined in two resource servers each, and after adding actions, 40 of 60 action scopes collide: license and license:suspend exist on both the California and Ohio DMV APIs, permits:approve on both Springfield servers, elections:certify on both counties.

Two roles named State Identity Administrator exist, one per state OU, each granting license on
its own DMV API. A criterion keyed on the scope name alone could not tell them apart, and neither
could one keyed on the role name.

The dimensions

CRITERION_TYPE  = 'entity.scope'
CRITERION_VALUE = sha256("<entity id>|<aud>|<scope>")

plus a coarser one for when a scope stops existing at all:

CRITERION_TYPE  = 'scope'
CRITERION_VALUE = sha256("<aud>|<scope>")

ResolveAudienceBinding binds token issuance to exactly one resource server, the access token's
aud is set to that server's identifier, and DownscopeToResourceServer filters the scopes to it.
RESOURCE_SERVER.IDENTIFIER is unique per deployment. So (aud, scope) is globally unique and both
halves are trusted claims.

Why hashed. CRITERION_VALUE is VARCHAR(255), while an identifier is VARCHAR(2048) and a permission is VARCHAR(1000). The triple does not fit and cannot be widened without exceeding the PostgreSQL btree key limit on a column that backs the hot lookup. A SHA-256 digest is 64 characters and loses nothing, since every match here is an equality test.

Each part is length-prefixed before hashing, rather than simply joined on |. A resource server identifier carries no character allowlist, so a plain join lets ("a|b", "c") and ("a", "b|c") render identically and one revocation would match a scope it was never written for. Length-prefixing makes the rendering unambiguous whatever the parts contain.

No plaintext column ships. An earlier draft of this design added a nullable, unindexed CRITERION_DETAIL column carrying the plaintext triple for operator readability. It was dropped before merge: nothing in the application ever read it back (not the enforcement query, not the Resource Server snapshot, not any handler), so its only consumer was a human querying the table directly, at the cost of storing a second copy of data the digest already identifies. It may be proposed separately if an admin-facing view needs it.

Where the scope ID does belong: the write path. It is the natural, unambiguous input to the
administration flow. The preparatory executor projects it once into (aud, permission), on the admin
path where a catalogue lookup is free. IDs upstream, token-space in the row.

Flow handle	Triggered by	Scopes revoked	Reason
default-role-assignment-removal-flow	Unassigning a role from a user, group or agent	The role's scopes	role_assignment_removed
default-role-permission-removal-flow	Editing a role to carry fewer scopes	The dropped scopes	role_permission_removed
default-role-deletion-flow	Deleting a role	All of the role's scopes	role_deleted
default-group-membership-removal-flow	Removing an entity from a group	The scopes the group's roles carried	group_membership_removed
default-group-deletion-flow	Deleting a group	Same, for every transitive member	group_membership_removed
default-scope-deletion-flow	Deleting a scope or its API resource	That scope, deployment wide	scope_deleted

Consent withdrawal and reducing an application's allowed scopes are natural follow-ons; both need a
third criterion shape, <entity>|<client>|<scope>, so they are out of scope for the first pass.

All six skip the SessionRevocationExecutor. Losing a scope is not losing your identity: the SSO
session is still legitimately the user's, and they should get a fresh, correctly scoped token without
signing in again.

What the preparatory executor computes

The node revokes every scope carried by the path being cut, without simulating the post-change
state (see Alternative 3). Boundary mode makes the resulting over-revocation self-healing.

Fan-out is the real constraint. A role assigned to a group of 10,000 users with 5 scopes is
50,000 rows. This needs a configurable cap on how many entities one revocation may expand to, and a
clear refusal above it rather than a half-written plan.

Architecture Overview

Only the starred boxes are new. The write seam, the table, the Authorization Server funnel and the
Resource Server cache already carry token_family, subject and app.key.

flowchart TB
    subgraph Admin["Administration (write path)"]
        C[Console / Management API] --> F["ADMINISTRATION flow ⭑"]
        F --> P["Preparatory executor ⭑<br/>resolves the lost scopes<br/>publishes a trusted plan"]
        P --> R[CriteriaRevocationExecutor<br/>unchanged]
        R --> A["Action executor ⭑<br/>performs the change"]
        A --> S["Re-stamp node ⭑<br/>moves the cutoff forward"]
    end

    R -->|RevokeByCriteria| DB[("REVOCATION_CRITERIA<br/>type + value + reason<br/>+ revoked_at + expiry")]
    S -->|RevokeByCriteria| DB

    subgraph Enforce["Enforcement (read path)"]
        AS[Authorization Server<br/>token validator]
        RS[Resource Server<br/>revocationcache]
    end

    DB -->|one indexed lookup per request| AS
    DB -->|periodic snapshot| RS
    AS --> V[allow or reject]
    RS --> V

Loading

A sample flow

flowchart LR
    S([START]) --> PV[PermissionValidator<br/>requiredScopes: system]
    PV --> PRE["PreRoleAssignmentRemovalExecutor<br/>mode: revoke_before_action"]
    PRE -->|"plan: criteria, mode,<br/>cutoff, reason, ttl"| REV[CriteriaRevocationExecutor]
    REV --> ACT[RoleAssignmentRemovalExecutor]
    ACT --> RS2[CriteriaRevocationExecutor<br/>re-stamp]
    RS2 --> E([COMPLETE])

Loading

The plan travels in SharedRuntimeData, written only by the preparatory node. Consumers refuse an
empty plan that does not explicitly declare there was nothing to revoke, the same contract
PreDeleteExecutor and PreApplicationDeleteExecutor already hold.

New executors: one preparatory type parameterized per action (the preApplicationActionExecutor
pattern, one struct behind several registered names), and one action executor per management
operation. CriteriaRevocationExecutor, the plan encoding, the store, the SQL and both enforcement
points are reused as they stand.

What lands in the database

Removing State Identity Administrator from l.tran at 10:15, where the California-scoped role
carries license and vehicle-registration:

TYPE	VALUE	DETAIL	REASON	REVOKED_AT	EXPIRY
entity.scope	9f86d081...	01a01978-b3a5...|https://api.dmv.ca.gov|license	role_assignment_removed	10:15	11:15
entity.scope	2c624232...	01a01978-b3a5...|https://api.dmv.ca.gov|vehicle-registration	role_assignment_removed	10:15	11:15

b.miller, who holds the Ohio-scoped role granting license on https://api.dmv.oh.gov, hashes
differently and is untouched. That is the whole point of qualifying by aud.

Writes are idempotent. The unique index on (DEPLOYMENT_ID, CRITERION_TYPE, CRITERION_VALUE)
means re-revoking the same pair updates the reason and time bounds rather than inserting a duplicate.
One row per criterion regardless of administrative churn.

Sizing the expiry

EXPIRY_TIME must outlive every artifact the row could match, then the existing cleanup job sweeps
it. The question is what sets that window.

An application criterion can be sized exactly, because it is scoped to one client:
resolveArtifactLifetime reads that client's own token config and takes the longest of its
user-access, client-access and refresh validities, plus the authorization code window. A role, group
or scope criterion has no such client. It matches a token from any application that could mint that
scope for the entity, so there is nothing single to read.

Decision: size these rows from oauth.refresh_token.validity_period, the deployment-wide refresh
token validity.

This needs no new code. resolveCriterionLifetime already returns
max(plan.TTL, tokenFamilyLifetime), and tokenFamilyLifetime is wired from exactly that config
value. So the preparatory node publishes no TTLSeconds and the row lands at
now + oauth.refresh_token.validity_period, 86400 seconds by default.

Two things to record alongside it:

• A client may configure a refresh or access validity longer than the deployment default, and nothing
  clamps it: ResolveTokenConfig overrides rather than caps, and no validation rejects an over-long
  value. That client's tokens can outlive the row. Accepted for now, since the alternatives are a
  deployment-wide maximum computed across every client or a real enforced ceiling, and neither exists
  today.
• The application path also adds authorization_code.validity_period, because a code issued just
  before a revocation can be redeemed just after and mint a token whose life starts later than
  REVOKED_AT. Worth deciding whether these rows should match that.

Sizing only has to cover artifacts outstanding at revocation time, not the rotation chains they
could have spawned. Revoking a refresh token kills its chain, and a rotated refresh token inherits
the original's absolute expiry rather than getting a fresh one, so a chain cannot outrun the window.

Time is part of the criterion

Group, role and scope assignments can be reverted, so a revocation cannot be a permanent verdict on a
value. role_assignment_removed, role_permission_removed and group_membership_removed all join
the existing boundary set alongside application_secret_regenerated. A boundary row denies only
artifacts established at or before REVOKED_AT. role_deleted and scope_deleted should be
boundary too, since a scope may be regranted through another role or a name reused. That differs from
how role_deleted is currently classified and should be confirmed.

A revert cycle then works without special handling:

	Event	Row	Effect
T1	role unassigned	REVOKED_AT = T1	tokens with iat <= T1 die
T2	role reassigned	unchanged	nothing written
T3	new token issued	unchanged	iat = T3 > T1, passes
T4	role unassigned again	REVOKED_AT = T4	the T3 token dies

Two rules fall out of this and must be stated explicitly, because both are easy to get wrong:

Never delete the row on revert. Tokens issued before T1 are still live until they expire, so
deleting the criterion when the grant is restored would resurrect them. The row's lifetime belongs to
the tokens, not to the grant.

The cutoff moves forward, never back. The upsert takes excluded.REVOKED_AT when the existing
reason is a boundary one, so re-revocation advances the cutoff. A terminal reason is never downgraded
to a boundary one.

The window between revoke and act, and how to close it

The cutoff is stamped in the preparatory node, before the action. That ordering is deliberate and
should stay. But it leaves a window:

T0.9  criteria node writes REVOKED_AT = T0.9
T1.1  the entity still holds the role. A token minted now carries the scope,
      and iat = T1.1 > T0.9, so it passes the boundary row.
T1.5  action node commits the change

The window cannot be closed with a transaction: the grant lives in configdb and the deny list in
runtime_persistent. The fix is to re-stamp after the action, adding a second
CriteriaRevocationExecutor node that rewrites the same criteria with cutoff = now. The upsert
moves REVOKED_AT forward, sweeping up anything minted in the window, while the first write
preserves the fail-safe property if the action fails. Two writes, one row, no schema change.

A smaller note: iat is second-granularity while REVOKED_AT is sub-second, and the comparison is
<=, so a token minted in the same second as a revocation is treated as revoked. That errs toward
over-revocation, which is the safe direction.

How the search runs at enforcement

Both enforcement points build a revocation identity from the token's trusted claims. Today an access
token contributes three criteria: token family, subject, and the OAuth client. This adds one
entity.scope and one scope criterion per scope in the token, each hashed with the audience. A
real token from our test deployment:

aud = https://api.dmv.ca.gov, sub = 01a01978-b3a5-..., scope = openid license

token_family : 01a05274-f1af-75e4-9f82-94e7b6b0e47c
subject      : 01a01978-b3a5-...
app.key      : ca-dmv-online
entity.scope : sha256("01a01978-b3a5-...|https://api.dmv.ca.gov|license")
scope        : sha256("https://api.dmv.ca.gov|license")

Authorization Server. Criteria are ORed into one indexed statement, as the existing query already
does. No extra round trip, only extra OR terms:

SELECT 1 FROM "REVOCATION_CRITERIA"
WHERE DEPLOYMENT_ID = $1
  AND EXPIRY_TIME > $2
  AND (REASON NOT IN (<boundary reasons>) OR $3 <= REVOKED_AT)   -- $3 is the token's iat
  AND ( (CRITERION_TYPE = $4 AND CRITERION_VALUE = $5) OR ... )
LIMIT 1

Each term is a probe on the unique index, so cost grows with the number of scopes in the token, not
with the size of the deny list. A six-scope token goes from three terms to fifteen. If that proves
material, the mitigation is a cheap per-deployment "any scope revocation exists" check that skips the
scope terms entirely.

Resource Server. The revocationcache snapshots the table periodically and answers from memory,
so these become two more map lookups. matchesEntry already implements the same boundary rule as the
SQL. The snapshot ignores criterion types it does not recognize, so an older Resource Server keeps
working against a newer writer.

Refresh tokens are covered. They carry scope, the user in access_token_sub and the audience
in access_token_aud. The identity builder already applies the subject fallback; the audience needs
the same treatment.

Scopeless and OIDC-only tokens are not bound to a resource server at all, so their audience falls
back to the client id and these criteria never match them. That is the correct outcome.

Known gap: a mapped sub. The examples above assume sub is the entity's resource ID, which is
the default. An application may map sub to a schema attribute through subjectAttribute, in which
case its tokens carry that attribute (an email, say) while the write path keys the row on the entity
ID, and the two never match. This is inherited rather than introduced here: the existing subject
dimension behind user deletion and session revocation has the same property. Closing it means emitting
an opaque, stable subject identifier on client-facing tokens and keying on that; sub_id already
exists on the internal flow assertion but is deliberately not emitted to clients today. Tracked
separately, since it changes token contents and affects the existing dimension too.

Security Considerations

• Revoke before you act. Every flow writes the deny-list rows before performing the change. If
  revocation succeeds and the action then fails we have over-revoked, costing a token refresh. The
  reverse ordering would under-revoke, which is a security hole.
• The revoke-to-act window. The revocation write and the change are not transactional, so a
  token minted between them escapes the boundary cutoff. Closed by re-stamping after the action.
• Fail closed, not open. The criterion is a self-contained equality test against claims the token
  already carries. Keying on catalogue IDs instead would mean resolving names to IDs at validation
  time, and a stale mapping would resolve to "no match" and silently admit a revoked token.
• Over-revoke rather than under-revoke. The preparatory node revokes every scope on the path being
  cut without simulating the post-change state, and the iat comparison is <= against a sub-second
  cutoff, so a token minted in the same second as a revocation is denied. Both err in the safe
  direction.
• Never delete a row when a grant is restored. Tokens issued before the revocation stay live
  until they expire; removing the criterion would resurrect them.
• Mutable audience. UpdateResourceServer can change IDENTIFIER, and nothing rejects tokens
  carrying the old aud: locally issued tokens are verified with an empty expected audience, and a
  third-party server validates against a statically configured string. A criterion written after such
  a change silently misses them. See the questions below.
• Fan-out. A role on a large group expands to many rows; an unbounded expansion is a
  denial-of-service surface against our own database and needs a cap with a clean refusal.
• Declarative resources refuse before revoking. A declarative role, a read-only group or a
  declarative resource server owns its definition from a file, so the change would be refused by the
  service anyway. The preparatory node therefore refuses first, rather than writing deny-list rows for
  a change that was never going to happen and leaving the principal's tokens dead for nothing.
• Third-party resource servers. revocationcache is fed by dbSource, which reads
  runtime_persistent directly, so it only serves processes sharing our database. A genuine third-party
  resource server has only /oauth2/introspect today. See the questions below.

Impacted Areas

• internal/flow/executor: new preparatory, action and re-stamp executors; CriteriaRevocationExecutor
  and PermissionValidator reused unchanged.
• internal/revocation: new CriterionType values and revocation reasons; boundary classification.
• internal/oauth/oauth2/revocation: criteria store and the deny-list SQL predicate.
• internal/oauth/oauth2/tokenservice: the Authorization Server revocation identity gains the scope
  dimensions and reads aud (and access_token_aud for refresh tokens).
• internal/system/revocationcache and internal/system/security: the Resource Server cache and
  the identity the middleware surfaces.
• internal/role, internal/resource: admin providers exposing the validation and scope-resolution the
  preparatory nodes need. The group operations live in internal/role rather than internal/group,
  because a group's scopes are the scopes of the roles it holds, so resolving them needs the role
  service regardless.
• Database: no schema change to REVOCATION_CRITERIA. The rows reuse the existing columns.
• internal/oauth/oauth2/revocation: a batched write path alongside the single-row one, so a plan
  carrying up to the fan-out cap costs a few statements rather than a round trip per row.
• Bootstrap resources and flow server-config: six new shipped flows and their handles.
• Console: delete, unassign and edit actions resolve a configured flow handle and execute the flow,
  falling back to the native endpoint when none is configured.

Alternatives Considered

Alternative 1: key criteria on the scope UUID instead of <entity>|<aud>|<scope>

• Pros: globally unique, immutable, no audience needed, fits VARCHAR(255) as plaintext with no hashing.
• Cons: a token never carries it, so both enforcement points would have to resolve
  (aud, scope-string) -> ID per request. The Resource Server cache would need the config-database
  catalogue replicated into it, and a stale mapping fails open instead of closed.
• Decision: rejected for the row. The scope ID is used as the flow's input and projected once into
  (aud, permission) on the admin path, and recorded in CRITERION_DETAIL.

Alternative 2: revoke by subject alone, with a boundary cutoff

• Pros: reuses an existing dimension with zero new enforcement work; one row per user rather than one
  per (user, scope).
• Cons: kills every token the user holds, across every application and resource server, for a change
  that removed one scope.
• Decision: rejected as the default. Worth keeping as a fallback if the fan-out cap is exceeded.

Alternative 3: compute the exact scope delta by simulating the post-change state

• Pros: revokes only genuinely lost scopes; no unnecessary refreshes.
• Cons: needs the effective-permission resolver run against a hypothetical state, and a resolver
  disagreement under-revokes, which is the unsafe failure.
• Decision: rejected. Over-revoke on the path being cut instead; boundary mode makes it self-healing.

Alternative 4: publish revocations per token via Token Status List

• Pros: an established draft standard, and works offline for third-party resource servers.
• Cons: a criterion is a predicate over tokens that do not exist yet, not a flag on one that does.
  Expressing it would mean enumerating every matching outstanding token, which needs a full token
  registry, precisely the state stateless JWTs exist to avoid.
• Decision: rejected as the mechanism for criteria. The third-party question stays open.

Questions for Community Input

1. Fan-out cap. What is the ceiling on entities per revocation, and what happens above it: refuse,
   or fall back to a coarse per-subject revocation? Resolved as shipped: the ceiling is
   oauth.revocation.criteria.max_criteria, 10,000 by default, and a change exceeding it is refused
   before anything is written. Falling back to the coarser scope dimension above the cap remains a
   reasonable future option, since today the largest changes are the ones that end up on the native
   endpoint, which revokes nothing.
2. role_deleted and scope_deleted classification. Boundary, as argued above, or terminal?
   Resolved as shipped: both are boundary, as argued above.
3. Mutable audience. UpdateResourceServer can change IDENTIFIER. Outstanding tokens keep the
   old aud, and nothing rejects them: locally issued tokens are verified with an empty expected
   audience, and a third-party server validates against a statically configured string. So a criterion
   written after the change silently misses them. Options: make the identifier change an
   administration flow that revokes on the old audience first, or refuse the change while non-expired
   criteria reference that server. Separately, whether skipping audience validation for locally issued
   tokens is intended at all is worth confirming against RFC 9068 section 4.
4. Third-party resource servers. The revocationcache is fed by dbSource, which reads
   runtime_persistent directly, so it only serves processes sharing our database. A genuine
   third-party resource server has only /oauth2/introspect today; there is no Shared Signals, CAEP,
   webhook or Token Status List anywhere in the codebase. The hard part is specific to this design: a
   criterion is a predicate over tokens that do not exist yet, not a flag on one that does. Per-token
   mechanisms such as Token Status List cannot express it without enumerating every matching
   outstanding token, which needs a full token registry, the very state stateless JWTs avoid. So the
   answer cannot simply be "adopt Token Status List later". Unresolved, and out of scope here. One
   thing in our favour: syncSource is already an interface with dbSource as one implementation.
5. Delegated tokens. A token with an act claim has an actor distinct from the subject. Do we
   revoke on the actor's lost scopes as well?

Suggested order of delivery

1. The entity.scope and scope dimensions at both enforcement points, the CRITERION_DETAIL
   column, and the new reasons.
2. default-role-assignment-removal-flow, with its preparatory, action and re-stamp nodes, to
   validate the shape end to end.
3. default-group-membership-removal-flow and default-group-deletion-flow.
4. default-role-permission-removal-flow and default-role-deletion-flow.
5. default-scope-deletion-flow.
6. Console wiring for each, following the application delete and regenerate pattern: resolve the
   configured flow handle, execute the flow, fall back to the native endpoint when none is configured.

[rajithacharith]

We need to have a proper stance on token revocation on declarative resource update.
Example: What will happen on the removal of declarative role?