JWT claims

You can add your own claims to the session tokens Authdog issues. Your app then reads roles, groups, or profile attributes straight from the token, without an extra lookup.

Mappings belong to one environment. Authdog applies them at sign-in, magic-link verification, MFA elevation, and token refresh.

Custom claims are additive. They never replace the standard claims, and a broken mapping never blocks sign-in.

Configure mappings

In the Authdog console:

1. Select the project and environment.
2. Open Authentication > JWT Claims.
3. Edit the claims document in the JSON editor.
4. 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 string form names the source. Use the object form when you need value, key, or enabled. Setting "enabled": false keeps the mapping in the document without putting the claim on the token. That's useful when you're staging a claim, or when you want to turn one off without deleting its definition.

Claim names may contain letters, digits, and _ . : / -, up to 128 characters.

Sources

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.
• roles and groups are 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 carry token verification and authorization. If a mapping targets one of them, Authdog drops that mapping instead of applying it:

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 can't collide with one of yours.

Discovery

Configured claim names show up 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 brief database error, never blocks authentication. Authdog still issues the token, with the standard claims only, and logs the failure.

Don't build a security control on the assumption that a custom claim is present. Treat a missing claim as "no grant," and keep the server-side check as the source of truth for anything sensitive.

Size

Claims travel with the token on every request. Large arrays and long metadata values grow the header, and they can trip proxy limits. Map only the few attributes your app actually routes on. Fetch the rest through the API.

Related