mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 05:52:51 +00:00
d8ea041c56
## Todos for release - [x] Configure Env in docs project on vercel - [x] Configure Root Path in the docs project on vercel - [ ] Remove old CSP https://github.com/zitadel/website/pull/1592 ## What we did This pull request migrates the project documentation from the old `docs/` directory to the new `apps/docs/` directory, introduces a new documentation system built with Next.js and Fumadocs, and updates all relevant references, configuration files, and documentation to reflect this change. It also adds new configuration and ignore files for the new documentation app, updates CI and linting to exclude the new docs from certain checks, and revises the contributing guidelines accordingly. **Documentation System Migration and New Docs App** * Migrated all documentation from `docs/` to `apps/docs/`, and updated all references in `README.md`, `CONTRIBUTING.md`, and other files to point to the new location. [[1]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L585-L640) [[2]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L660-R607) [[3]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L740-R687) [[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L2-R3) [[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-R30) * Added a new Next.js/Fumadocs-based documentation app under `apps/docs/`, including core app files, layouts, routing, search API, and a comprehensive `README.md` with development and contribution instructions. [[1]](diffhunk://#diff-5a1b07344a2c1b4d3f37b23ff1388b62cd9f57dea3c1cd23d8a0412b7602b132R1-R74) [[2]](diffhunk://#diff-462b9ad1eabbb7d1c29bb9c36e4931eb180fd7190900e6d2babf8f4d66ad1c28R1-R39) [[3]](diffhunk://#diff-e16ae25660ded787b10ac35dea96d5ecaacf895dae0afc8a9bd4382dc79a8c87R1-R7) [apps/docs/app/[[...slug]]/layout.tsxR1-R81](diffhunk://#diff-59e08acde4e805b7aeccef1dcf98f1d71dfc550777e6b9402085cee0e9fa4e0aR1-R81), [apps/docs/app/[[...slug]]/page.tsxR1-R79](diffhunk://#diff-e5df3f80d0fa01e12d63d81f29c57a9d14e846c78fd3beabb2ef768e38fd9580R1-R79), [[4]](diffhunk://#diff-389b34918e040cacaa87cd7201ffa462cc2b0b716736f537e3d3c660ac69353bR1-R7) [[5]](diffhunk://#diff-d3b03416d1c457b19f1c27b26f2db741412df841b875c26ccadc36e4522247f4R1-R29) [[6]](diffhunk://#diff-c8fb8339570a5305809be7c618e14705fd86390dc278e6ce8ba224a7bc8b0c3cR1-R25) **Configuration and Tooling Updates** * Updated `.github/workflows/codeql.yml`, `.golangci.yaml`, and `.github/dependabot.yml` to properly handle the new docs app: excluded `apps/docs` from certain checks, added npm dependency updates for the docs app, and excluded generated content. [[1]](diffhunk://#diff-12783128521e452af0cfac94b99b8d250413c516ec71fe6d97dbea666ff7ba27L8-R14) [[2]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R5-R6) [[3]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R126-R129) [[4]](diffhunk://#diff-dd4fbda47e51f1e35defb9275a9cd9c212ecde0b870cba89ddaaae65c5f3cd28R89-R106) * Updated `.devcontainer/devcontainer.json` to use the latest Go 1.25.3 version for consistency. **Licensing and Miscellaneous** * Added `apps/docs/` to the list of licensed directories in `LICENSING.md`. These changes ensure the documentation is now maintained in a modern, scalable system and all project tooling is updated to support the new structure. --------- Co-authored-by: Federico Coppede <[email protected]>
119 lines
20 KiB
Plaintext
119 lines
20 KiB
Plaintext
---
|
|
title: Claims in ZITADEL
|
|
sidebar_label: Claims
|
|
---
|
|
|
|
ZITADEL asserts claims on different places according to the corresponding specifications or project and clients 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
|
|
|
|
```javascript reference
|
|
https://github.com/zitadel/actions/blob/de69b56f6d0463817953b59a52ffd6afc6a366fb/examples/add_claim.js#L9-L11
|
|
```
|
|
|
|
### Metadata as custom claim
|
|
|
|
```javascript reference
|
|
https://github.com/zitadel/actions/blob/main/examples/add_metadata.js#L9-L15
|
|
```
|
|
|
|
### Format roles claims
|
|
|
|
```javascript reference
|
|
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 primary domain of the organization 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 client 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's primary domain. |
|