JWT authorization claims (RFC 9068, SCIM)

What it isCopy Anchor Link

RFC 9068, the JWT profile for OAuth 2.0 access tokens, says in section 2.2.3.1 that an authorization server which embeds authorization attributes beyond delegated scopes (memberships in roles and groups, entitlements for the targeted resource) SHOULD use the roles, groups and entitlements attributes of the SCIM User schema (RFC 7643 section 4.1.2) as claim names, and registers all three in the IANA JWT claims registry. RFC 7643 defines the three as multi-valued complex attributes: each value is an object whose value sub-attribute carries the identifier, optionally with display (a human label), type, primary and $ref. RFC 7643 section 8.2 shows the groups form. No vocabulary is given for roles or entitlements.

In practice many issuers emit plain string arrays ("roles": ["admin"], "groups": ["9f2c..."]), so a reader must accept both encodings.

Two neighbours:

• SCIM 2.0 Group (RFC 7643 section 4.2): a Group resource has a displayName and members[].value. There is no tenant attribute anywhere in SCIM; tenancy is per endpoint or per bearer token. Nested groups are provider-specific (Microsoft Entra does not expand them in members.value filters). The IPSIE AL1 profile constrains SCIM for enterprise interoperability (watch list).
• draft-gazitt-oauth-authzen-claims (individual draft, 2026): binds the three RFC 9068 claims to AuthZEN Resource Search so an authorization server can obtain them from a policy decision point rather than a directory. A claim binding associates a claim with an AuthZEN resource type and action; a search over that type and action enumerates the claim's values.

Why it matters for PermDockCopy Anchor Link

PermDock reads role and group material from tokens on every request through permdock/jwt and the provider mappers (authentication), and the tenancy model needs a place for team memberships and entitlement roles on the wire. Inventing claim names would make PermDock one more vendor mapping. Following RFC 9068 means:

• Issuers that already follow the RFC (Entra app roles under roles, Okta and Entra groups) work with the default mapping and no claims configuration.
• Group ids arrive as identifiers, and the SCIM value versus display distinction gives the rule for which one to trust.
• The AuthZEN claims draft makes permdock/authzen's /search/resource endpoint a legitimate source of roles and groups for an authorization server, which closes the loop: PermDock decides which roles a subject holds, and the token an agent later presents can carry them.

How PermDock uses itCopy Anchor Link

Default claim mapping in permdock/jwtCopy Anchor Link

import { subjectFromJwt } from "permdock/jwt";

const subject = await subjectFromJwt(token, {
  jwks: "https://issuer.example/.well-known/jwks.json",
  issuer: "https://issuer.example",
  audience: "api://permdock-example",
  claims: {
    id: "sub",
    roles: "roles", // default; RFC 9068
    groups: "groups", // default; RFC 9068 -> team memberships
    entitlements: "entitlements", // default; RFC 9068 -> principal.plans
    tenant: "org_id", // no standard exists; vendor specific, see below
  },
});

Reading SCIM complex values: { "value": "9f2c", "display": "Design", "type": "direct" } contributes 9f2c; display and type are not read. An Entra _claim_names / _claim_sources overflow (above roughly 200 groups) is not resolved. For large or nested directories, use app roles or a directory lookup in context (authentication single sign-on).

Tenant claimsCopy Anchor Link

There is no standard tenant claim. The claims.tenant path is configuration, and the resolver applies the threat model rule: the value is compared against onboarded tenants (or the subject's memberships) and an absent or unknown value yields a subject with no active tenant, never a default.

PermDock as a claim sourceCopy Anchor Link

permdock/authzen serves /access/v1/search/resource. Under the AuthZEN claims draft an authorization server binds roles to a resource type and action (for example type role, action hold) and asks the PDP which resources the subject may act on; the answer is the claim value list. PermDock answers from permdock.heldRoles({ tenant }) and permdock.memberships() for the authenticated subject. PermDock follows the draft only through this existing endpoint and adds nothing draft-specific until a working group adopts it; the draft is on the watch list.

Mapping tableCopy Anchor Link

SourcesCopy Anchor Link

• RFC 9068: JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens, section 2.2.3.1 and section 7.2.
• RFC 7643: SCIM Core Schema, sections 4.1.2, 4.2 and 8.2; RFC 7644: SCIM Protocol.
• IANA JSON Web Token Claims registry entries roles, groups, entitlements.
• draft-gazitt-oauth-authzen-claims-00.
• Microsoft Entra: configure group claims, Okta: add a groups claim.
• SaaS tenancy and roles for the vendor rows.