Every environment can add custom claims to the session tokens Authdog issues, so your application reads roles, groups, or profile attributes straight from the token instead of making an extra lookup. Mappings are defined per environment and applied at sign-in, magic link verification, MFA elevation, and token refresh.
Custom claims are strictly additive: they never replace the standard claim set, and they never block a sign-in.
Configure mappings
In the Authdog console:
- Select the project and environment.
- Open Authentication > JWT Claims.
- Edit the claims document in the JSON editor.
- Save. The editor validates the document, reports errors inline, and refuses to save an invalid one.
The document maps a claim name to a source. Two forms are accepted:
{
"roles": "roles",
"groups": "groups",
"tenant": { "source": "static", "value": "acme" },
"dept": { "source": "metadata", "key": "department" },
"legacy_id": { "source": "externalId", "enabled": false }
}The shorthand string form names the source; use the object form when you need value, key, or enabled. Setting "enabled": false keeps a mapping in the document without emitting the claim — handy for staging a claim, or for switching one off without losing its definition.
Claim names may contain letters, digits, and _ . : / -, up to 128 characters.
Sources
| Source | Emits |
|---|---|
roles |
Array of role slugs |
groups |
Array of group slugs |
email |
Primary email address |
displayName |
Display name |
givenName |
Given (first) name |
familyName |
Family (last) name |
username |
Username |
externalId |
Stable external user id |
metadata |
Value at key in the user's metadata |
static |
The literal in value |
roles covers roles assigned directly, roles inherited through group membership, and roles held via an active time-bound elevated access grant. Slugs are deduplicated and sorted, so the claim stays byte-stable between tokens for an unchanged user.
metadata requires a key. static requires a value.
Emission rules
- A source that yields nothing is omitted rather than written as
null. Check for claim presence, not for a null value. rolesandgroupsare always emitted when mapped, as[]when the user has none. A configured array claim is safe to read without a presence check.- Mappings are applied in a stable order by claim name.
Reserved claims
These claims are load-bearing for token verification and authorization, and a mapping that targets one is dropped rather than applied:
iss, sub, aud, exp, iat, nbf, jti, scp, env, egat, sid, externalid
Namespace your own claims — for example https://acme.com/dept or acme_dept — so a future standard claim cannot collide with one of yours.
Discovery
Configured claim names are advertised in claims_supported on the environment's OpenID discovery document, so a relying party can see which claims to expect.
Failure behavior
Claim resolution is best-effort. A broken mapping or a transient database error never blocks authentication: the token is issued with the standard claim set only, and the failure is logged. Never build a security control on the assumption that a custom claim is present — treat a missing claim as "no grant", and keep server-side checks the source of truth for sensitive operations.
Size
Claims travel with the token on every request, so large arrays and long metadata values inflate headers and can trip proxy header limits. Map only the few attributes your application routes on; fetch the rest through the API.