mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 05:52:51 +00:00
f4f43f5248
# Which Problems Are Solved Pages in `apps/docs` that embed source from GitHub via the Docusaurus convention ```` ```js reference https://github.com/zitadel/actions/blob/main/examples/org_metadata_claim.js ``` ```` stopped working after the migration from Docusaurus to fumadocs. The old `docusaurus-theme-github-codeblock` plugin used to fetch the file and render it; fumadocs has no support for that meta, so the page rendered the raw URL as plain code-block text. Visible at `/docs/apis/actions/code-examples` and 16 other pages. # How the Problems Are Solved - Converted every ```` ```<lang> reference\n<URL>\n``` ```` block (46 total across 17 `.mdx` files) to the native fumadocs JSX form: `<GithubCodeBlock url="<URL>" />`. The existing `<details>`/`<summary>` collapsibles around blocks are kept — they're an authoring choice, not part of the rendering bug. - Updated `apps/docs/components/github-code-block.tsx` to render via `DynamicCodeBlock` from `fumadocs-ui/components/dynamic-codeblock` (proper shiki highlighting) instead of raw `CodeBlock` + `Pre` (which produced unhighlighted output). Also fixed language detection so a URL hash like `#L10-L20` no longer pollutes the language token. - Registered `GithubCodeBlock` globally in `apps/docs/mdx-components.tsx`, matching how every other shared component (`APIPage`, `Callout`, `Tab/Tabs`, `Step/Steps`, `Admonition`, `TerminologyUpdate`) is exposed. MDX files no longer need a local `import`. # Additional Changes - Normalized the two MDX files that were already using the JSX form (`examples/secure-api/python-django.mdx`, `examples/secure-api/java-spring.mdx`): removed their now-redundant local `import { GithubCodeBlock }` and rewrote 9 long-form `<GithubCodeBlock url="..."></GithubCodeBlock>` tags to self-closing for consistency. # Additional Context Verified locally with `pnpm --filter @zitadel/docs dev`: - `/docs/apis/actions/code-examples` — 20 shiki-highlighted code blocks rendered inside the `<details>` collapsibles (was 0). - `/docs/apis/openidoauth/claims` — line-range hashes (`#L9-L11`) honored. - `/docs/examples/login/flutter` — mixed languages (xml/dart/html) detected and highlighted. - `/docs/guides/integrate/external-audit-log` — edge case of fenced reference indented inside a numbered list also converted and rendered. Greps: - `^[ \t]*\`\`\`[a-zA-Z0-9]+ reference` in `apps/docs/content/**/*.mdx` → 0 matches. - `<GithubCodeBlock url="` in `apps/docs/content/**/*.mdx` → 55 matches. - `from '@/components/github-code-block'` in `apps/docs/content/**/*.mdx` → 0 matches. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
114 lines
20 KiB
Plaintext
114 lines
20 KiB
Plaintext
---
|
|
title: Claims in ZITADEL
|
|
description: "Standard OIDC and custom claims issued by ZITADEL in ID tokens, access tokens, and via the Userinfo endpoint."
|
|
sidebar_label: Claims
|
|
---
|
|
|
|
ZITADEL asserts claims on different places according to the corresponding specifications or project and applications settings.
|
|
Please check below the matrix for an overview where which scope is asserted.
|
|
|
|
| Claims | Userinfo | Introspection | ID Token | Access Token |
|
|
|:--------------------------------------------------|:---------------|-----------------------------------------|-------------------------------------------------|------------------------------------------------------|
|
|
| acr | No | No | Yes | No |
|
|
| act | No | After Token Exchange with `actor_token` | After Token Exchange with `actor_token` | When JWT and after Token Exchange with `actor_token` |
|
|
| address | When requested | When requested | When requested and response_type `id_token` | No |
|
|
| amr | No | No | Yes | No |
|
|
| aud | No | Yes | Yes | When JWT |
|
|
| auth_time | No | No | Yes | No |
|
|
| azp (client_id when Introspect) | No | Yes | Yes | When JWT |
|
|
| email | When requested | When requested | When requested and response_type `id_token` | No |
|
|
| email_verified | When requested | When requested | When requested and response_type `id_token` | No |
|
|
| exp | No | Yes | Yes | When JWT |
|
|
| family_name | When requested | When requested | When requested and response_type `id_token` | No |
|
|
| gender | When requested | When requested | When requested and response_type `id_token` | No |
|
|
| given_name | When requested | When requested | When requested and response_type `id_token` | No |
|
|
| iat | No | Yes | Yes | When JWT |
|
|
| iss | No | Yes | Yes | When JWT |
|
|
| jti | No | Yes | No | When JWT |
|
|
| locale | When requested | When requested | When requested and response_type `id_token` | No |
|
|
| name | When requested | When requested | When requested and response_type `id_token` | No |
|
|
| nbf | No | Yes | No | When JWT |
|
|
| nonce | No | No | When provided in the authorization request [^1] | No |
|
|
| phone | When requested | When requested | When requested and response_type `id_token` | No |
|
|
| phone_verified | When requested | When requested | When requested and response_type `id_token` | No |
|
|
| preferred_username (username when Introspect) | When requested | When requested | Yes | No |
|
|
| sid | No | No | Yes | No |
|
|
| sub | Yes | Yes | Yes | When JWT |
|
|
| urn:zitadel:iam:org:domain:primary:\{domainname} | When requested | When requested | When requested | When JWT and requested |
|
|
| urn:zitadel:iam:org:project:roles | When requested | When requested | When requested or configured | When JWT and requested or configured |
|
|
| urn:zitadel:iam:user:metadata | When requested | When requested | When requested | When JWT and requested |
|
|
| urn:zitadel:iam:user:resourceowner:id | When requested | When requested | When requested | When JWT and requested |
|
|
| urn:zitadel:iam:user:resourceowner:name | When requested | When requested | When requested | When JWT and requested |
|
|
| urn:zitadel:iam:user:resourceowner:primary_domain | When requested | When requested | When requested | When JWT and requested |
|
|
|
|
[^1]: The nonce can also be used to distinguish between an id_token and a logout_token as latter must never include a nonce.
|
|
|
|
## Standard Claims
|
|
|
|
| Claims | Example | Description |
|
|
|:-------------------|:---------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| acr | TBA | TBA |
|
|
| act | `{"iss": "${CUSTOM_DOMAIN}","sub": "259241944654282754"}` | JSON object describing the actor from the `actor_token` after [token exchange](/guides/integrate/token-exchange#actor-token) |
|
|
| address | `Lerchenfeldstrasse 3, 9014 St. Gallen` | TBA |
|
|
| amr | `pwd mfa` | Authentication Method References as defined in [RFC8176](https://tools.ietf.org/html/rfc8176) <br/> `password` value is deprecated, please check `pwd` |
|
|
| aud | `69234237810729019` | The audience of the token, by default all client id's and the project id are included |
|
|
| auth_time | `1311280969` | Unix time of the authentication |
|
|
| azp | `69234237810729234` | Client id of the client who requested the token |
|
|
| email | `[email protected]` | Email Address of the subject |
|
|
| email_verified | `true` | Boolean if the email was verified by ZITADEL |
|
|
| events | `{ "http://schemas.openid.net/event/backchannel-logout": {} }` | Security Events such as Back-Channel Logout |
|
|
| exp | `1311281970` | Time the token expires (as unix time) |
|
|
| family_name | `Runner` | Last name of the subject |
|
|
| family_name | `Runner` | Last name of the subject |
|
|
| gender | `other` | Gender of the subject |
|
|
| given_name | `Road` | First name of the subject |
|
|
| given_name | `Road` | First name of the subject |
|
|
| iat | `1311280970` | Time of the token was issued at (as unix time) |
|
|
| iss | `${CUSTOM_DOMAIN}` | Issuing domain of a token |
|
|
| jti | `69234237813329048` | Unique id of the token |
|
|
| locale | `en` | Language from the subject |
|
|
| name | `Road Runner` | The subjects full name |
|
|
| nbf | `1311280970` | Time the token must not be used before (as unix time) |
|
|
| nonce | `blQtVEJHNTF0WHhFQmhqZ0RqeHJsdzdkd2d...` | The nonce provided by the client |
|
|
| phone | `+41 79 XXX XX XX` | Phone number provided by the user |
|
|
| phone_verified | `true` | Boolean if the phone was verified by ZITADEL |
|
|
| preferred_username | `[email protected]` | ZITADEL's login name of the user. Consist of `username@primarydomain` |
|
|
| sid | `291693710356251044` | String identifier for a session. This represents a session of a user agent for a logged-in end-User. Different sid values are used to identify distinct sessions at an OP. |
|
|
| sub | `77776025198584418` | Subject ID of the user |
|
|
|
|
## Custom Claims
|
|
|
|
Custom claims are being inserted into user tokens in addition to the standard claims.
|
|
Your app can use custom claims to handle more complex scenarios, such as restricting access based on these claims.
|
|
|
|
You can add custom claims using the [complement token flow](/apis/actions/complement-token) of the [actions feature](/guides/manage/console/actions-overview).
|
|
|
|
Multiple examples of Actions that result in custom claims can be found in our [Marketplace for ZITADEL Actions](https://github.com/zitadel/actions).
|
|
|
|
### Static values as custom claim
|
|
|
|
<GithubCodeBlock url="https://github.com/zitadel/actions/blob/de69b56f6d0463817953b59a52ffd6afc6a366fb/examples/add_claim.js#L9-L11" />
|
|
|
|
### Metadata as custom claim
|
|
|
|
<GithubCodeBlock url="https://github.com/zitadel/actions/blob/main/examples/add_metadata.js#L9-L15" />
|
|
|
|
### Format roles claims
|
|
|
|
<GithubCodeBlock url="https://github.com/zitadel/actions/blob/main/examples/custom_roles.js#L20-L33" />
|
|
|
|
## Reserved Claims
|
|
|
|
ZITADEL reserves some claims to assert certain data. Please check out the [reserved scopes](./scopes#reserved-scopes).
|
|
|
|
| Claims | Example | Description |
|
|
|:--------------------------------------------------|:---------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| urn:zitadel:iam:action:\{actionname}:log | `{"urn:zitadel:iam:action:appendCustomClaims:log": ["test log", "another test log"]}` | This claim is set during Actions as a log, e.g. if two custom claims with the same keys are set. |
|
|
| urn:zitadel:iam:org:domain:primary:\{domainname} | `{"urn:zitadel:iam:org:domain:primary": "acme.ch"}` | This claim represents the Organization Domain the user belongs to. |
|
|
| urn:zitadel:iam:org:project:roles | `{"urn:zitadel:iam:org:project:roles": [ {"user": {"id1": "acme.zitade.ch", "id2": "caos.ch"} } ] }` | When roles are asserted, ZITADEL does this by providing the `id` and `primaryDomain` below the role. This gives you the option to check in which organization a user has the role on the current project (where your application belongs to). |
|
|
| urn:zitadel:iam:org:project:\{projectid}:roles | `{"urn:zitadel:iam:org:project:id3:roles": [ {"user": {"id1": "acme.zitade.ch", "id2": "caos.ch"} } ] }` | When roles are asserted, ZITADEL does this by providing the `id` and `primaryDomain` below the role. This gives you the option to check in which organization a user has the role on a specific project. |
|
|
| urn:zitadel:iam:user:metadata | `{"urn:zitadel:iam:user:metadata": [ {"key": "VmFsdWU=" } ] }` | The metadata claim will include all metadata of a user. The values are base64 encoded. |
|
|
| urn:zitadel:iam:user:resourceowner:id | `{"urn:zitadel:iam:user:resourceowner:id": "orgid"}` | This claim represents the user's organization ID. |
|
|
| urn:zitadel:iam:user:resourceowner:name | `{"urn:zitadel:iam:user:resourceowner:name": "ACME"}` | This claim represents the user's organization's name. |
|
|
| urn:zitadel:iam:user:resourceowner:primary_domain | `{"urn:zitadel:iam:user:resourceowner:primary_domain": "acme.ch"}` | This claim represents the user's Organization Domain. |
|