Vord

Enhancement Proposal

Proposal: Token and claims customization

Every identity platform lets integrators shape token claims; without it, relying parties can't get the claims they need. This specs declarative claim mapping on the issuer (ADR-0014) over the directory (ADR-0011) and the token format (ADR-0003) — no new architecture. The code-based transformation hooks (Auth0 "Actions") are explicitly deferred, because running custom logic in the token pipeline needs a sandboxed-execution ADR (ADR-0029).

Motivation

A fixed claim set forces every integrator to fetch identity data out-of-band. Claim mapping — directory attributes and roles into ID/access/UserInfo claims, varied by client, audience, and scope — is table-stakes and removes that friction.

Design

  • Declarative claim mapping per realm/client (ADR-0012, ADR-0014): map principal and directory attributes (ADR-0011) and group/role memberships (ADR-0006) into ID-token, access-token, and UserInfo claims; add static claims; define per-audience claim sets; gate a claim on a granted scope (least-disclosure).
  • Mappings respect the spec-first token format and its versioning (ADR-0003) and never overwrite the reserved security claims (amr/acr, ADR-0015/0020; iss/aud/exp).
  • Mappings are validated and versioned configuration, applied by the issuer — no per-request code execution.

Alternatives considered

  • Fixed claims only — rejected (inflexible; forces out-of-band lookups).
  • Code hooks as the only mechanism — deferred: arbitrary code in the token pipeline requires a sandboxing decision (ADR-0029). Declarative mapping covers the common case safely, without that decision.

Graduation criteria

A client/realm can map attributes and roles into claims, gate claims by scope, vary by audience, and add static claims; mappings are validated, versioned, and cannot clobber reserved security claims.

Backward compatibility

A feature on the issuer + directory; no architecture change. Code-based transformation hooks are settled separately in ADR-0029.

Open questions

  • The mapping expression surface (templated paths vs a restricted, non-Turing-complete expression syntax) that stays declarative rather than becoming code-execution.