Skip to main content

Token Claims & Context

Summary​

Keymate tokens contain standard identity and protocol claims plus application-specific projections. The accepted generic organization-context contract adds a minimal, versioned org_context reference derived from the requesting authenticated client session. It identifies the canonical selected context without embedding a complete effective-role or permission inventory.

Planned capability

The generic org_context mapper and client-session runtime are planned in KEOPS #307. Until that runtime is released and enabled, deployments must use the claim contract documented by their installed provider rather than assuming this target claim is present.

Why It Exists​

A minimal context reference lets services identify the selected organizational context without turning an issued token into a stale copy of every provider-owned role and permission.

Where It Fits in Keymate​

Session Management owns selected-context state, KEOPS validates and orchestrates it, token mappers serialize the versioned reference, and authorization services evaluate current facts.

Boundaries​

The claim records issuance-time context. It does not prove current membership, embed a complete effective-role inventory, or guarantee immediate invalidation of an older self-contained token.

How It Works​

Claim Sources and Ownership​

Claim categorySourceLifecycle characteristic
Standard identity/protocol claimsKeycloak user, client, realm, and protocol stateFixed for the issued token
org_contextCanonical selection on the requesting authenticated client sessionFixed for the issued token; client-session selection can later change
Optional custom attributesEligible definition + Security rule + active client scope/grant + KEOPS mapperFixed for the issued token
Effective roles and permissionsRole providers and authorization evaluationCan change after token issuance

The selected context is an input to authorization; it is not proof that every permission associated with that context remains current.

Session Management owns the authoritative selected-context state, its protected authenticated- client-session reference, and the expiry, revoke, and explicit-replacement lifecycle. KEOPS validates and orchestrates that state. A token-exchange flow may request selection or replacement and carry the returned opaque reference in its private signed claim, but it does not write the reserved session state directly. An administrative simulation or inspection value is never promoted into this runtime authority.

Attribute Claim Projection​

tokenVisible=true makes an attribute eligible; it does not emit the claim automatically. Emission also requires a matching Security bundle/rule and token surface, the native Keycloak client scope/grant, KEOPS orchestration and mapper support, and a safe fact for the verified selected context. SENSITIVE projection is prohibited and CONFIDENTIAL projection requires explicit approval. Missing or conflicting inputs omit the claim by default.

The immutable AKS reference image has passed exact-image runtime acceptance. Product Security #257 is historical manager-only evidence for that tested digest, not candidate-specific target authority; CONFIDENTIAL projection remains disabled and deferred to Security #290. The isolated-local T901 matrix passed but is not a shared-environment or same-digest image observation. The capability remains BLOCKED with assembly detail ASSEMBLED. The KEOPS #894 fail-closed consumer is released, but its operational result remains UNAVAILABLE without an actual candidate-qualified attestation under the delivered GitOps #429 contract. Admin Console, Console #4279 consumption, and Product Documentation completion remain open. An authorized matching deployment observation is required only for ACTIVE, not signed VERIFIED. GİB is a separate deferred release lane. See Attribute Capability Status. Do not infer ACTIVE from a packaged image, a successful business request, or runtimeState=DEPLOYED.

Minimal org_context Contract​

The generic runtime owns the exact schema and increments its version when a breaking interpretation changes. Its design rules are:

  • include a claim version;
  • include only canonical identifiers required to name the selected eligible context;
  • derive the value from the requesting authenticated client session;
  • omit rejected context metadata;
  • omit a potentially stale complete role, permission, or policy inventory; and
  • fail closed when a consumer does not support the claim version or required identifiers.

Conceptually:

{
  "org_context": {
    "version": "<contract-version>",
    "membership_id": "<canonical-membership-id>",
    "tenant_id": "<canonical-tenant-id>",
    "organization_id": "<canonical-organization-id>",
    "organization_unit_id": "<canonical-unit-id-if-applicable>",
    "position_id": "<canonical-position-id-if-applicable>"
  }
}

This example illustrates the boundary, not a released field-level schema. Optional hierarchy identifiers depend on the selected context type; consumers must follow the versioned runtime contract delivered with KEOPS #307.

Why Roles Are Not the Context Claim​

Roles can be direct, template-sourced, inherited, time-bounded, or changed by membership lifecycle operations. Copying the complete effective set into org_context would make the context claim a stale duplicate of provider-owned authorization facts and enlarge every token.

Services should:

  • validate the token according to the deployment's token profile;
  • read the selected context reference;
  • enforce tenant, organization, audience, and client boundaries; and
  • resolve or evaluate current authorization facts where freshness is required.

Some token profiles can still project standard Keycloak role claims for compatibility. Those claims represent issuance-time data and do not change the minimal org_context contract into a current authorization inventory.

An effective-role result resolved for this context is a narrowing authorization fact. It is not, by itself, a final access decision and does not replace the other mandatory policy, topology, security, readiness, or revocation controls.

Client-Session Scope​

The same root SSO session can contain multiple authenticated client sessions. Each client session can select a different organization context. A token mapper reads only the requesting client session, so a context change in application X does not change application Y's claim.

Diagram​

Issuance-Time Data and Revocation​

An access token is not rewritten when:

  • the client session later selects another context;
  • a membership is disabled or removed;
  • a membership-bound role assignment is deleted; or
  • an organization-template entitlement changes.

The client must replace its token set after a successful context switch. Whether an older access token is rejected before expiry depends on an explicitly implemented and enforced profile, such as supported introspection or session/current-state validation. Local JWT validation alone observes signature, issuer, audience, and expiry, not later domain changes.

warning

Do not infer immediate old-token invalidation from durable membership or role cleanup. Treat issued-token enforcement and provider-owned authorization-fact cleanup as separate controls.

Example Scenario​

Scenario​

Jane switches the selected organization context for one authenticated client session.

Input​

  1. A token identifies Jane and carries organization A's versioned context reference.
  2. The service validates standard token properties.
  3. The authorization boundary uses A as contextual input and evaluates the current required permission.
  4. If membership A has since become ineligible, a freshness-enforcing profile rejects the request; a purely offline JWT profile cannot discover that change until token expiry.
  5. A switch to B produces a fresh token for the requesting client without changing sibling clients.

Expected Outcome​

The requesting client receives a fresh token with context B, sibling clients retain their own context, and services still evaluate current authorization facts according to the deployed profile.

Common Misunderstandings​

  • "org_context contains every effective role." It intentionally carries only a versioned canonical context reference.
  • "All clients in one SSO session share the claim." The value is scoped to each requesting authenticated client session.
  • "Deleting durable roles edits existing JWTs." Issued self-contained tokens are immutable.
  • "Every deployment performs introspection on every request." Enforcement is profile-specific and must be documented by the deployment.
  • "Missing optional hierarchy fields are empty strings." Optionality is defined by the versioned schema; consumers must not invent values.

Design Notes / Best Practices​

  • Keep org_context minimal, versioned, and scoped to the requesting authenticated client session.
  • Resolve current roles and permissions at the authorization boundary when freshness matters.
  • Fail closed when the claim version or required canonical identifiers are unsupported.
  • Switch organization context for one client without changing sibling client sessions.
  • Evaluate a current membership after token issuance.
  • Support offline JWT validation with an explicitly documented freshness limitation.

Token Exchange Model

How browser and confidential-client profiles obtain a fresh token set.

Session Governance

Root and authenticated client-session boundaries.

Org-Aware Tokens & Sessions

Eligibility, selection, and lifecycle separation.

Policy Evaluation Model

How current authorization facts are evaluated.

Attribute Capability Verification

Interpret runtime and product evidence without promotion.