Skip to content

CONCEPT Cited by 1 source

Token enrichment

What it is

Token enrichment is the practice of adding authorization-relevant attributes (roles, group memberships, tenant identifiers, custom claims) to an authentication token (typically a JWT access token) at token-issuance time, so downstream authorizers can evaluate policies purely from token claims — no second round-trip to an identity or attribute store on the hot path.

Why it matters

ABAC / fine-grained authorization evaluates rules like principal.role == "PAYMENT_INITIATOR" — the runtime must know the user's role. Three places to source it:

  • Per-request lookup. Authorizer calls user store → adds one database hop per API call. Dominates latency.
  • Token enrichment. Attributes fetched once at login, signed into the token. Authorizer reads claims directly. Submillisecond.
  • Session-cached lookup. Attributes fetched on first request, cached server-side. Intermediate — adds a distributed cache as dependency.

Enrichment chooses the second: push the cost to authentication (already expensive, already happens once per session), make authorization cheap (many requests per session).

Mechanism

The canonical implementation in AWS is Cognito's pre-token-generation Lambda trigger — a function Cognito invokes between authentication success and token signing, given the user's base identity, returning a set of attributes to add to the access token and/or ID token.

(Source: sources/2026-02-05-aws-convera-verified-permissions-fine-grained-authorization)

Generalizes across IdPs:

  • Auth0 — Actions / Rules inject custom claims.
  • Keycloak — Token Mappers / Script Mappers.
  • Okta — Inline Hooks / Token Inline Hook.

Common shape: "at issue time, call a function with identity, return attributes to sign into the token."

The ID-token vs access-token distinction

Enrichment targets the access token (OAuth authorization grant), not the ID token (OIDC identity assertion):

  • ID token: "who the user is." Audience = the client app. Contains identity claims. Don't bloat with authorization-specific attributes the client shouldn't see.
  • Access token: "what the user can do." Audience = the resource server / authorizer. Contains authorization-relevant attributes. The right place for enriched claims.

Convera's internal flow explicitly customizes the access token with attributes stored in DynamoDB while letting the ID token carry only identity. AVP's IsAuthorizedWithToken API evaluates the access token.

Attributes vs authorization

Enrichment adds attributes; authorization is still a separate step that evaluates policies over those attributes. Specifically:

  • Enriched claim: "role": "PAYMENT_INITIATOR".
  • Policy: permit when principal.role == "PAYMENT_INITIATOR" && ....

The token doesn't grant anything. It attests attribute values that the policy engine trusts because the token is signed.

Freshness tradeoff

Enriched attributes are pinned for the token lifetime (typically minutes to hours). Attribute changes mid-session (role demoted, tenant added) do not take effect until token refresh. Mitigations:

  • Short token lifetimes. Expensive — more auth traffic, more enrichment calls.
  • Revocation list / denylist. Out-of-band mechanism checked in the authorizer; defeats the "no-database-lookup" advantage.
  • Per-request attribute fetch for mutable attributes only. Hybrid: stable attributes enriched at token issue, volatile ones (current daily-limit usage) looked up per request.

Convera's post does not discuss this tradeoff.

Seen in

Last updated · 200 distilled / 1,178 read