andwati/zitadel
1
0
Fork 0
mirror of https://github.com/andwati/zitadel.git synced 2026-10-18 05:52:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: introduce versioned docs and migrate to fuma (#11166)

Browse Source 
## 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]>
This commit is contained in:
Florian Forster
2026-01-29 08:38:36 -08:00
committed by GitHub
co-authored by Federico Coppede
parent 7b6395c348
commit d8ea041c56
2826 changed files with 78739 additions and 23571 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.devcontainer/devcontainer.json
+1 -1
View File
@@ -33,7 +33,7 @@
},
"features": {
"ghcr.io/devcontainers/features/go:1": {
"version": "1.25"
"version": "1.25.3"
},
"ghcr.io/devcontainers/features/docker-outside-of-docker": {},
"ghcr.io/schlich/devcontainer-features/cypress:1": {
.github/dependabot.yml
+18
View File
@@ -86,3 +86,21 @@ updates:
commit-message:
prefix: chore
include: scope
- package-ecosystem: npm
directory: '/apps/docs'
open-pull-requests-limit: 10
schedule:
interval: weekly
time: "02:00"
groups:
prod:
dependency-type: production
dev:
dependency-type: development
commit-message:
prefix: chore
include: scope
labels:
- "npm"
- "dependencies"
- "documentation"
.github/workflows/codeql.yml
+2 -2
View File
@@ -5,13 +5,13 @@ on:
branches:
- 'main'
paths-ignore:
- 'docs/**'
- 'apps/docs/content/**'
pull_request:
# The branches below must be a subset of the branches above
branches:
- 'main'
paths-ignore:
- 'docs/**'
- 'apps/docs/content/**'
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
.gitignore
+8 -7
View File
@@ -57,19 +57,18 @@ console/.angular
pkg/**/**.connect.go
**.gen.go
openapi/**/*.json
# multi-version proto artifacts
/proto/latest/
/proto/v*/
/internal/api/assets/authz.go
/internal/api/assets/router.go
internal/api/ui/console/static
!internal/api/ui/console/static/gitkeep
docs/docs/apis/auth
docs/docs/apis/admin
docs/docs/apis/mgmt
docs/docs/apis/system
docs/docs/apis/proto
**/.sass-cache
apps/docs/content/apis/assets/assets.mdx
apps/docs/content/reference/api/
/internal/api/ui/login/static/resources/themes/zitadel/css/zitadel.css
/internal/api/ui/login/static/resources/themes/zitadel/css/zitadel.css.map
zitadel-*-*
/zitadel-*-*
!apps/**/zitadel-*-*
# local
@@ -106,3 +105,5 @@ CLAUDE.md
AGENTS.md
.mcp.json
.gemini/*
docs_old
.golangci.yaml
+6
View File
@@ -2,6 +2,8 @@ version: "2"
run:
concurrency: 4
go: "1.24"
skip-dirs:
- apps/docs
linters:
enable:
- asciicheck
@@ -121,6 +123,10 @@ issues:
max-issues-per-linter: 0
max-same-issues: 0
new-from-rev: origin/main
exclude-rules:
- path: apps/docs/.*
linters:
- typecheck
formatters:
enable:
- gci
.nxignore
+2
View File
@@ -2,3 +2,5 @@
!console/src/app/proto/generated
!internal/api/ui/console/static
!.artifacts/bin/*/*/zitadel.local
!apps/docs/content/apis/assets/assets.mdx
!apps/docs/content/reference/api/
CONTRIBUTING.md
+5 -58
View File
@@ -129,7 +129,7 @@ The code consists of the following parts:
| API definitions | Specifications of the API | [Protobuf](https://developers.google.com/protocol-buffers) | [./proto/zitadel](./proto/zitadel) | [Contribute to API](#contribute-to-api) |
| Management Console | Frontend the user interacts with after log in | [Angular](https://angular.io), [Typescript](https://www.typescriptlang.org) | [./console](./console) | [Contribute to Frontend](#contribute-to-frontend) |
| Login | Modern authentication UI built with Next.js | [Next.js](https://nextjs.org), [React](https://reactjs.org), [TypeScript](https://www.typescriptlang.org) | [./apps/login](./apps/login) | [Contribute to Frontend](#contribute-to-frontend) |
| Docs | Project documentation made with docusaurus | [Docusaurus](https://docusaurus.io/) | [./docs](./docs) | [Contribute to Frontend](#contribute-to-frontend) |
| Docs | Project documentation made with docusaurus | [Docusaurus](https://docusaurus.io/) | [./apps/docs](./apps/docs) | [Contribute to Frontend](#contribute-to-frontend) |
| translations | Internationalization files for default languages | YAML | [./console](./console) and [./internal](./internal) | [Contribute Translations](#contribute-translations) |
Please follow the guides to validate and test the code before you contribute.
@@ -582,62 +582,9 @@ pnpm nx run @zitadel/client:build # Build after changes
### Contribute to Docs
Project documentation is made with Docusaurus and is located under [./docs](./docs). The documentation uses **pnpm** and **Nx** for development and build processes.
Project documentation is located under [./apps/docs](./apps/docs).
Please refer to the [Docs README](./apps/docs/README.md) for detailed instructions on how to contribute to the documentation.
To start developing, make sure you followed the [quick start](#quick-start) steps.
#### Local Development
```bash
# Start development server (recommended)
pnpm nx run @zitadel/docs:dev
# Or start production server
pnpm nx run @zitadel/docs:prod
```
The Docs build process automatically:
1. Downloads required protoc plugins
2. Generates gRPC documentation from proto files
3. Generates API documentation from OpenAPI specs
4. Copies configuration files
5. Builds the Docusaurus site
#### Local testing
The documentation server will be available at http://localhost:3000 with live reload for fast development feedback.
#### Style guide
- **Code with variables**: Make sure that code snippets can be used by setting environment variables, instead of manually replacing a placeholder.
- **Embedded files**: When embedding mdx files, make sure the template ist prefixed by "\_" (lowdash). The content will be rendered inside the parent page, but is not accessible individually (eg, by search).
- **Don't repeat yourself**: When using the same content in multiple places, save and manage the content as separate file and make use of embedded files to import it into other docs pages.
- **Embedded code**: You can embed code snippets from a repository. See the [plugin](https://github.com/saucelabs/docusaurus-theme-github-codeblock#usage) for usage.
Following the [Google style guide](https://developers.google.com/style) is highly recommended. Its clear and concise guidelines ensure consistency and effective communication within the wider developer community.
The style guide covers a lot of material, so their [highlights](https://developers.google.com/style/highlights) page provides an overview of its most important points. Some of the points stated in the highlights that we care about most are given below:
- Be conversational and friendly without being frivolous.
- Use sentence case for document titles and section headings.
- Use active voice: make clear who's performing the action.
- Use descriptive link text.
#### Docs pull request
When making a pull request use `docs(<scope>): <short summary>` as title for the semantic release.
Scope can be left empty (omit the brackets) or refer to the top navigation sections.
#### Pass Quality Checks
Verify the Docs build correctly.
```bash
pnpm nx run @zitadel/docs:build
```
Fix the quality checks, add new checks that cover your changes and mark your pull request as ready for review when the pipeline checks pass.
## Contribute Translations
@@ -657,7 +604,7 @@ You also have to add some changes to the following files:
- [Register Local File](./console/src/app/app.module.ts) - Import and register the Angular locale, register `i18n-iso-countries` locale
- [Exclude from Angular prebundle](./console/angular.json) - Add `i18n-iso-countries/langs/<locale>.json` to `prebundle.exclude`
- [Add Supported Language](./console/src/app/utils/language.ts)
- [Customized Text Docs](./docs/docs/guides/manage/customize/texts.md)
- [Customized Text Docs](./apps/docs/docs/guides/manage/customize/texts.md)
- [Add language option](./internal/api/ui/login/static/templates/external_not_found_option.html)
### Login v2 (Next.js)
@@ -737,7 +684,7 @@ The category shows which part of Zitadel is affected.
- **category: backend**: The backend includes the APIs, event store, command and query side. This is developed in golang.
- **category: ci**: ci is all about continuous integration and pipelines.
- **category: design**: All about the ux/ui of Zitadel
- **category: docs**: Adjustments or new documentations, this can be found in the docs folder.
- **category: docs**: Adjustments or new documentations, this can be found in the apps/docs folder.
- **category: frontend**: The frontend concerns on the one hand the Zitadel Management Console (Angular) and on the other hand the Login (gohtml)
- **category: infra**: Infrastructure does include many different parts. E.g Terraform-provider, docker, metrics, etc.
- **category: translation**: Everything concerning translations or new languages
LICENSING.md
+1
View File
@@ -16,6 +16,7 @@ The following files and directories, including their subdirectories, are license
```
proto/
apps/docs/
```
README.md
+3 -3
View File
@@ -1,6 +1,6 @@
<p align="center">
<img src="./docs/static/logos/zitadel-logo-dark@2x.png#gh-light-mode-only" alt="Zitadel Logo" max-height="200px" width="auto" />
<img src="./docs/static/logos/zitadel-logo-light@2x.png#gh-dark-mode-only" alt="Zitadel Logo" max-height="200px" width="auto" />
<img src="./apps/docs/static/logos/zitadel-logo-dark@2x.png#gh-light-mode-only" alt="Zitadel Logo" max-height="200px" width="auto" />
<img src="./apps/docs/static/logos/zitadel-logo-light@2x.png#gh-dark-mode-only" alt="Zitadel Logo" max-height="200px" width="auto" />
</p>
<p align="center">
@@ -27,7 +27,7 @@
<p align="center">
<a href="https://openid.net/certification/#OPs" alt="OpenID Connect Certified">
<img src="./docs/static/logos/oidc-cert.png" /></a>
<img src="./apps/docs/static/logos/oidc-cert.png" /></a>
</p>
Are you searching for a user management tool that is quickly set up like Auth0 and open source like Keycloak?
apps/api/project.json
+66 -28
View File
@@ -20,7 +20,9 @@
"!{workspaceRoot}/**/integration_test/**/*"
],
"pack": [
{ "env": "VERSION" },
{
"env": "VERSION"
},
"runtime"
]
},
@@ -65,10 +67,16 @@
],
"command": "bash -c 'CGO_ENABLED=0 go build -o .artifacts/bin/$(go env GOOS)/$(go env GOARCH)/zitadel.local -ldflags=\"-s -w\"'",
"inputs": [
{ "runtime": "go env GOOS" },
{ "runtime": "go env GOARCH" },
{
"runtime": "go env GOOS"
},
{
"runtime": "go env GOARCH"
},
"runtime",
{"dependentTasksOutputFiles": "internal/api/ui/console/static/**/*"}
{
"dependentTasksOutputFiles": "internal/api/ui/console/static/**/*"
}
],
"outputs": [
"{workspaceRoot}/.artifacts/bin/*/*/zitadel.local"
@@ -82,13 +90,17 @@
"generate-statik"
]
},
"lint-install":{
"lint-install": {
"description": "Installs golangci-lint binary for linting. Using go install is not recommended in the official docs, because this can produce non-deterministic results.",
"cache": true,
"command": "curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b .artifacts/bin/$(go env GOOS)/$(go env GOARCH) v2.5.0",
"inputs": [
{ "runtime": "go env GOOS" },
{ "runtime": "go env GOARCH" }
{
"runtime": "go env GOOS"
},
{
"runtime": "go env GOARCH"
}
],
"outputs": [
"{workspaceRoot}/.artifacts/bin/*/*/golangci-lint"
@@ -137,8 +149,12 @@
"command": "go build -cover -race -tags integration -o .artifacts/bin/$(go env GOOS)/$(go env GOARCH)/zitadel.test main.go",
"cache": true,
"inputs": [
{ "runtime": "go env GOOS" },
{ "runtime": "go env GOARCH" },
{
"runtime": "go env GOOS"
},
{
"runtime": "go env GOARCH"
},
"sources",
"{workspaceRoot}/internal/integration/**",
"{workspaceRoot}/go*"
@@ -193,8 +209,12 @@
]
},
"inputs": [
{ "runtime": "go env GOOS" },
{ "runtime": "go env GOARCH" },
{
"runtime": "go env GOOS"
},
{
"runtime": "go env GOARCH"
},
"sources",
"{workspaceRoot}/internal/integration/**",
"{workspaceRoot}/go*"
@@ -215,7 +235,9 @@
"command": "find internal/api/ui/console/static -mindepth 1 ! -name 'gitkeep' -delete -print && cp -r -v console/dist/console/* internal/api/ui/console/static",
"cache": true,
"inputs": [
{"dependentTasksOutputFiles": "console/dist/console/**/*"}
{
"dependentTasksOutputFiles": "console/dist/console/**/*"
}
],
"outputs": [
"{workspaceRoot}/internal/api/ui/console/static"
@@ -231,7 +253,6 @@
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install go.uber.org/mock/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install golang.org/x/tools/cmd/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install github.com/rakyll/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install github.com/bufbuild/buf/cmd/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install google.golang.org/protobuf/cmd/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install google.golang.org/grpc/cmd/[email protected]",
@@ -240,15 +261,18 @@
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install github.com/envoyproxy/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install connectrpc.com/connect/cmd/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install google.golang.org/protobuf/cmd/[email protected]",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install ./internal/protoc/protoc-gen-authoption",
"GOBIN=${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH) go install ./internal/protoc/protoc-gen-zitadel"
]
},
"cache": true,
"inputs": [
{ "runtime": "go env GOOS" },
{ "runtime": "go env GOARCH" },
{
"runtime": "go env GOOS"
},
{
"runtime": "go env GOARCH"
},
"{workspaceRoot}/internal/protoc/protoc-gen-authoption/**/*",
"{workspaceRoot}/internal/protoc/protoc-gen-zitadel/**/*"
],
@@ -257,7 +281,6 @@
"{workspaceRoot}/.artifacts/bin/*/*/mockgen",
"{workspaceRoot}/.artifacts/bin/*/*/stringer",
"{workspaceRoot}/.artifacts/bin/*/*/statik",
"{workspaceRoot}/.artifacts/bin/*/*/buf",
"{workspaceRoot}/.artifacts/bin/*/*/protoc-gen-go",
"{workspaceRoot}/.artifacts/bin/*/*/protoc-gen-go-grpc",
@@ -265,7 +288,6 @@
"{workspaceRoot}/.artifacts/bin/*/*/protoc-gen-openapiv2",
"{workspaceRoot}/.artifacts/bin/*/*/protoc-gen-validate",
"{workspaceRoot}/.artifacts/bin/*/*/protoc-gen-connect-go",
"{workspaceRoot}/.artifacts/bin/*/*/protoc-gen-authoption",
"{workspaceRoot}/.artifacts/bin/*/*/protoc-gen-zitadel"
]
@@ -313,8 +335,12 @@
},
"cache": true,
"inputs": [
{ "runtime": "go env GOOS" },
{ "runtime": "go env GOARCH" },
{
"runtime": "go env GOOS"
},
{
"runtime": "go env GOARCH"
},
"{workspaceRoot}/internal/statik/generate.go",
"{workspaceRoot}/internal/notification/statik/generate.go",
"{workspaceRoot}/internal/api/ui/login/static/resources/generate.go",
@@ -332,7 +358,7 @@
"dependsOn": [
"generate-install"
],
"command": "mkdir -p docs/apis/assets && go run internal/api/assets/generator/asset_generator.go -directory=internal/api/assets/generator/ -assets=docs/apis/assets/assets.md",
"command": "mkdir -p apps/docs/content/apis/assets && go run internal/api/assets/generator/asset_generator.go -directory=internal/api/assets/generator/ -assets=apps/docs/content/apis/assets/assets.mdx",
"cache": true,
"inputs": [
"{workspaceRoot}/internal/api/assets/generator/asset_generator.go"
@@ -340,7 +366,7 @@
"outputs": [
"{workspaceRoot}/internal/api/assets/authz.go",
"{workspaceRoot}/internal/api/assets/router.go",
"{workspaceRoot}/docs/apis/assets/assets.md"
"{workspaceRoot}/apps/docs/content/apis/assets/assets.mdx"
]
},
"generate-go": {
@@ -372,7 +398,9 @@
"cache": true,
"inputs": [
"pack",
{ "env": "ZITADEL_VERSION" }
{
"env": "ZITADEL_VERSION"
}
],
"outputs": [
"{workspaceRoot}/.artifacts/pack/zitadel-darwin-amd64.tar.gz",
@@ -389,7 +417,9 @@
"cache": true,
"inputs": [
"pack",
{ "env": "ZITADEL_VERSION" }
{
"env": "ZITADEL_VERSION"
}
],
"outputs": [
"{workspaceRoot}/.artifacts/pack/zitadel-darwin-arm64.tar.gz",
@@ -406,7 +436,9 @@
"cache": true,
"inputs": [
"pack",
{ "env": "ZITADEL_VERSION" }
{
"env": "ZITADEL_VERSION"
}
],
"outputs": [
"{workspaceRoot}/.artifacts/pack/zitadel-linux-amd64.tar.gz",
@@ -423,7 +455,9 @@
"cache": true,
"inputs": [
"pack",
{ "env": "ZITADEL_VERSION" }
{
"env": "ZITADEL_VERSION"
}
],
"outputs": [
"{workspaceRoot}/.artifacts/pack/zitadel-linux-arm64.tar.gz",
@@ -440,7 +474,9 @@
"cache": true,
"inputs": [
"pack",
{ "env": "ZITADEL_VERSION" }
{
"env": "ZITADEL_VERSION"
}
],
"outputs": [
"{workspaceRoot}/.artifacts/pack/zitadel-windows-amd64.tar.gz",
@@ -457,7 +493,9 @@
"cache": true,
"inputs": [
"pack",
{ "env": "ZITADEL_VERSION" }
{
"env": "ZITADEL_VERSION"
}
],
"outputs": [
"{workspaceRoot}/.artifacts/pack/zitadel-windows-arm64.tar.gz",
apps/docs/.gitignore
+39
View File
@@ -0,0 +1,39 @@
# deps
/node_modules
# generated content
.source
scanned-urls.json
# test & build
/coverage
/.next/
/out/
/build
*.tsbuildinfo
# misc
.DS_Store
*.pem
/.pnp
.pnp.js
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# others
.env*.local
.vercel
next-env.d.ts
# generated api docs
/content/reference/api
/content/reference/api-v1
/openapi/
# multi-version artifacts
/content/versions.json
/content/v*/
/public/v*
/.temp/
/.source
apps/docs/README.md
+83
View File
@@ -0,0 +1,83 @@
# @zitadel/docs
Documentation for Zitadel, built with [Fumadocs](https://fumadocs.dev) and [Next.js](https://nextjs.org).
## Getting Started
Ensure you have followed the [root quick start](../../CONTRIBUTING.md#quick-start) to set up dependencies.
### Local Development
Start the development server:
```bash
pnpm nx run @zitadel/docs:dev
```
The site will be available at http://localhost:3000.
### Scripts
Key scripts for documentation workflows:
| Script | Description |
| :--- | :--- |
| `dev` | Starts the development server. |
| `build` | Builds the production application. |
| `fetch:remote-content` | Fetches remote tags and referenced content. |
| `generate` | Runs all generation steps (`fetch:remote-content`, `generate:proto-docs`, `generate:api-reference`, `generate:index-pages`). |
| `check:links` | Validates content integrity (broken links, missing frontmatter, schema errors). |
| `check-types` | Validates typescript types. |
| `test` | Runs all validation steps (`check-types`, `check:links`). |
| `lint` | checks for code style and syntax errors (ESLint). |
| `clean` | Cleans the build output and generated files. |
### Validation
* **Code Quality**: Run `pnpm lint` to check for syntax and style issues in JS/TS/MDX files.
* **Content Integrity**: Run `pnpm check:links` to validate content structure, including:
* Broken internal links
* Missing required frontmatter (e.g., `title`)
* Image references
## Contributing
### Build Process
The docs build process automatically handling the following steps via `generate`:
1. Downloads required protoc plugins.
2. Generates gRPC documentation from proto files.
3. Generates API documentation from OpenAPI specs.
4. Generates index files for directory structures.
### Style Guide
- **Variables**: Use environment variables in code snippets where possible.
- **Embedded Content**: Use `_filename.mdx` for content embedded in other pages (not indexed individually).
- **Code Embedding**: Use the `file` property in code blocks to embed code from the repo.
- **Voice**: Use active voice and sentence case for titles.
Refer to the [Google Developer Style Guide](https://developers.google.com/style) for general guidelines.
### Adding Content
All documentation content is located in the `content` directory. Note that the system strictly accepts **only `.mdx` files**.
To add a new page:
1. Create a `.mdx` file in the appropriate subdirectory of [`content`](./content).
2. Register the new page in the sidebar configuration at [`lib/sidebar-data.ts`](./lib/sidebar-data.ts) to make it accessible in the navigation.
### Pull Requests
Use `docs(<scope>): <short summary>` for PR titles.
Pass quality checks before submitting:
```bash
pnpm nx run @zitadel/docs:build
pnpm nx run @zitadel/docs:check:links
```
You can also run specific steps individually:
* `pnpm fetch:remote-content`
* `pnpm generate:api-reference`
apps/docs/app/(home)/layout.tsx
+7
View File
@@ -0,0 +1,7 @@
import { HomeLayout } from 'fumadocs-ui/layouts/home';
import { baseOptions } from '@/lib/layout.shared';
import { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
return <HomeLayout {...baseOptions()}>{children}</HomeLayout>;
}
apps/docs/app/[[...slug]]/layout.tsx
+81
View File
@@ -0,0 +1,81 @@
import { source, versionSource } from '@/lib/source';
import { ReactNode } from 'react';
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import { baseOptions } from '@/lib/layout.shared';
import { buildCustomTree } from '@/lib/custom-tree';
import rawVersions from '@/content/versions.json';
const versions = rawVersions as any[];
import { VersionSelector } from '@/components/version-selector';
export default async function Layout(props: { children: ReactNode; params: Promise<{ slug?: string[] }> }) {
const params = await props.params;
const slug = params.slug || [];
// Determine current version and tail path
// If first slug segment matches a version param (e.g. v4.10), that's the version.
// Otherwise it's latest.
const versionParam = slug[0] && versions.find(v => v.param === slug[0]) ? slug[0] : undefined;
const currentVersion = versionParam || 'latest';
const allPages = [...source.getPages(), ...versionSource.getPages()];
const labelsMap = new Map<string, string>();
allPages.forEach(p => {
if (p.data.sidebar_label) {
labelsMap.set(p.url, p.data.sidebar_label);
}
});
let tree = source.pageTree;
if (currentVersion !== 'latest') {
// Hoist the version folder to root to flatten sidebar
// versionSource.pageTree -> [ v4.10 folder, v4.9 folder ... ]
// We want the children of the specific version folder.
const children = (versionSource.pageTree as any).children || [];
const versionFolder = children.find((node: any) => {
if (node.type !== 'folder') return false;
// Check if the folder's index page belongs to this version
if (node.index?.url && node.index.url.includes(`/${currentVersion}`)) return true;
// Fallback: check first child if index missing
if (node.children?.[0]?.url?.includes(`/${currentVersion}`)) return true;
return false;
});
if (versionFolder) {
// Hoist children
const hoistedTree = {
name: versionFolder.name,
children: versionFolder.children,
} as any;
// Apply custom sidebar structure (from local sidebar-data.ts)
// We strip the prefix '/v4.10' so the lookup matches generic keys 'guides/...'
// The logs showed the URLs start with /[version] not /docs/[version]
const prefix = currentVersion === 'latest' ? '/docs' : `/${currentVersion}`;
tree = buildCustomTree(hoistedTree, {
stripPrefix: prefix,
labels: labelsMap
});
} else {
tree = buildCustomTree(versionSource.pageTree, { labels: labelsMap });
}
} else {
tree = buildCustomTree(source.pageTree, { labels: labelsMap });
}
return (
<DocsLayout
tree={tree}
{...baseOptions()}
sidebar={{
banner: (
<VersionSelector />
),
}}
>
{props.children}
</DocsLayout>
);
}
apps/docs/app/[[...slug]]/page.tsx
+79
View File
@@ -0,0 +1,79 @@
import { getPageImage, getPage, source } from '@/lib/source';
import {
DocsBody,
DocsDescription,
DocsPage,
DocsTitle,
} from 'fumadocs-ui/layouts/docs/page';
import { notFound } from 'next/navigation';
import { getMDXComponents } from '@/mdx-components';
import type { Metadata } from 'next';
import { createRelativeLink } from 'fumadocs-ui/mdx';
import { Callout } from 'fumadocs-ui/components/callout';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Feedback } from '@/components/feedback';
export default async function Page(props: any) {
const params = await props.params;
const { page, source: pageSource } = getPage(params.slug);
if (!page) notFound();
const MDX = page.data.body;
return (
<DocsPage toc={page.data.toc} full={page.data.full}>
<DocsTitle>{page.data.title}</DocsTitle>
<DocsDescription>{page.data.description}</DocsDescription>
<DocsBody>
<MDX
components={getMDXComponents({
Callout,
Tab,
Tabs,
// this allows you to link to other pages with relative file paths
a: createRelativeLink(pageSource, page),
})}
/>
</DocsBody>
<Feedback />
</DocsPage>
);
}
export const dynamicParams = true;
export const revalidate = 3600;
export async function generateStaticParams() {
return source.generateParams();
}
export async function generateMetadata(
props: any,
): Promise<Metadata> {
const params = await props.params;
const { page } = getPage(params.slug);
if (!page) notFound();
const baseUrl = 'https://zitadel.com/docs';
const url = params.slug ? `${baseUrl}/${params.slug.join('/')}` : baseUrl;
let canonicalUrl = url;
if (params.slug?.[0]?.startsWith('v')) {
const unversionedSlug = params.slug.slice(1);
const unversionedPage = source.getPage(unversionedSlug);
if (unversionedPage) {
canonicalUrl = `${baseUrl}${unversionedPage.url === '/' ? '' : unversionedPage.url}`;
}
}
return {
title: page.data.title,
description: page.data.description,
alternates: {
canonical: canonicalUrl,
},
openGraph: {
images: getPageImage(page).url,
},
};
}
apps/docs/app/api/search/route.ts
+7
View File
@@ -0,0 +1,7 @@
import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
export const { GET } = createFromSource(source, {
// https://docs.orama.com/docs/orama-js/supported-languages
language: 'english',
});
apps/docs/app/global.css
+408
View File
@@ -0,0 +1,408 @@
@import 'tailwindcss';
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
@import 'fumadocs-openapi/css/preset.css';
@theme {
/* 1. REGISTER STANDARD UTILITIES */
--color-background: hsl(var(--background));
--color-foreground: hsl(var(--foreground));
--color-card: hsl(var(--card));
--color-card-foreground: hsl(var(--card-foreground));
--color-popover: hsl(var(--popover));
--color-popover-foreground: hsl(var(--popover-foreground));
--color-primary: hsl(var(--primary));
--color-primary-foreground: hsl(var(--primary-foreground));
--color-secondary: hsl(var(--secondary));
--color-secondary-foreground: hsl(var(--secondary-foreground));
--color-muted: hsl(var(--muted));
--color-muted-foreground: hsl(var(--muted-foreground));
--color-accent: hsl(var(--accent));
--color-accent-foreground: hsl(var(--accent-foreground));
--color-destructive: hsl(var(--destructive));
--color-destructive-foreground: hsl(var(--destructive-foreground));
--color-border: hsl(var(--border));
--color-input: hsl(var(--input));
--color-ring: hsl(var(--ring));
/* 2. MAP FUMADOCS VARIABLES */
--color-fd-primary: var(--color-primary);
--color-fd-primary-foreground: var(--color-primary-foreground);
--color-fd-background: var(--color-background);
--color-fd-foreground: var(--color-foreground);
--color-fd-card: var(--color-card);
--color-fd-card-foreground: var(--color-card-foreground);
--color-fd-popover: var(--color-popover);
--color-fd-popover-foreground: var(--color-popover-foreground);
--color-fd-muted: var(--color-muted);
--color-fd-muted-foreground: var(--color-muted-foreground);
--color-fd-accent: var(--color-accent);
--color-fd-accent-foreground: var(--color-accent-foreground);
--color-fd-border: var(--color-border);
--color-fd-ring: var(--color-ring);
--color-zitadelpink: #ff2069;
--font-sans: var(--font-lato), "Lato", "ui-sans-serif", "system-ui";
}
/* --- LIGHT MODE VARIABLES --- */
:root {
--primary: 230 59% 58%;
--primary-foreground: 0 0% 100%;
--background: 0 0% 98%;
--foreground: 0 0% 10%;
--card: 0 0% 93%;
--card-foreground: 0 0% 10%;
--muted: 0 0% 96%;
--muted-foreground: 0 0% 45%;
--accent: 0 0% 92%;
--accent-foreground: 230 59% 58%;
--secondary: 240 4.8% 95.9%;
--secondary-foreground: 240 5.9% 10%;
--destructive: 0 84.2% 60.2%;
--destructive-foreground: 0 0% 98%;
--border: 0 0% 90%;
--input: 0 0% 90%;
--ring: 230 59% 58%;
--radius: 0.5rem;
--overlaycolor: #6c90b420;
}
/* --- DARK MODE VARIABLES --- */
:root[class~="dark"], [data-theme="dark"] {
--primary: 340 100% 56%;
--primary-foreground: 0 0% 100%;
--background: 235 45% 14%;
--foreground: 0 0% 98%;
--card: 220 40% 25%;
--card-foreground: 0 0% 98%;
--muted: 230 43% 15%;
--muted-foreground: 230 20% 70%;
--accent: 230 43% 20%;
--accent-foreground: 340 100% 65%;
--secondary: 240 3.7% 15.9%;
--secondary-foreground: 0 0% 98%;
--destructive: 0 62.8% 30.6%;
--destructive-foreground: 0 0% 98%;
--border: 230 43% 25%;
--input: 230 43% 25%;
--ring: 340 100% 56%;
--overlaycolor: #ffffff15;
/* FORCE OVERRIDE for Fumadocs Variables */
--color-fd-background: hsl(var(--background));
--color-fd-foreground: hsl(var(--foreground));
--color-fd-primary: hsl(var(--primary));
--color-fd-primary-foreground: hsl(var(--primary-foreground));
--color-fd-card: hsl(var(--card));
--color-fd-card-foreground: hsl(var(--card-foreground));
--color-fd-popover: hsl(var(--card));
--color-fd-popover-foreground: hsl(var(--foreground));
--color-fd-muted: hsl(var(--muted));
--color-fd-muted-foreground: hsl(var(--muted-foreground));
--color-fd-accent: hsl(var(--accent));
--color-fd-accent-foreground: hsl(var(--accent-foreground));
--color-fd-border: hsl(var(--border));
--color-fd-ring: hsl(var(--ring));
}
@layer components {
/* 1. VISIBILITY HELPERS */
.hideondark { display: block !important; }
.hideonlight { display: none !important; }
:root[class~="dark"] .hideondark, [data-theme="dark"] .hideondark {
display: none !important;
}
:root[class~="dark"] .hideonlight, [data-theme="dark"] .hideonlight {
display: block !important;
}
/* 2. MAIN CARD LAYOUT (Tile Wrapper) */
.tile-wrapper {
@apply flex flex-row flex-wrap gap-6 my-6;
}
.tile-wrapper > * {
@apply flex flex-col items-center text-center rounded-lg border relative;
background-color: hsl(var(--card)) !important;
border-color: hsl(var(--border));
justify-content: flex-start;
min-width: 160px;
min-height: 180px;
padding: 2rem;
padding-bottom: 3rem;
}
.tile-wrapper > * > :last-child {
margin-top: auto;
}
.tile-wrapper > * > h3,
.tile-wrapper > * > h4,
.tile-wrapper > * > strong {
@apply mt-0;
}
/* 3. ICON STYLING */
.custom-rounded {
@apply flex items-center justify-center p-2 rounded-full w-14 h-14 shrink-0 m-0;
}
.custom-rounded svg {
@apply fill-white h-7 w-7;
}
.custom-rounded i {
@apply text-white;
}
/* Gradients */
.custom-rounded-start { background: linear-gradient(40deg, #059669 30%, #047857); }
.custom-rounded-password { background: linear-gradient(40deg, #f59e0b 30%, #b45309); }
.custom-rounded-login, .custom-rounded-register { background: linear-gradient(40deg, #059669 30%, #047857); }
.custom-rounded-privatelabel, .custom-rounded-phone, .custom-rounded-email, .custom-rounded-storage, .custom-rounded-service { background: linear-gradient(40deg, #ff2069 30%, #cc1a54); }
.custom-rounded-split { background: linear-gradient(40deg, #ff2069, #cc1a54); }
.custom-rounded-texts, .custom-rounded-help, .custom-rounded-architecture { background: linear-gradient(40deg, #dc2626 30%, #db2777); }
.custom-rounded-system, .custom-rounded-apis, .custom-rounded-policy, .custom-rounded-instance { background: linear-gradient(40deg, #1f2937, #111827); }
/* 4. B2B / DIAGRAM LAYOUTS (Fixes the B2B Component) */
.flexrowbetween {
@apply flex flex-row items-center justify-around gap-4 my-8 w-full;
}
.arrowright {
@apply w-8 h-8 shrink-0 text-muted-foreground;
}
.b2borg, .b2bproject, .b2bapp, .b2buser {
@apply rounded-xl p-4 border text-left;
background: var(--overlaycolor);
border-color: hsl(var(--border));
}
.b2buser { @apply mt-4; }
.b2borg span, .b2bproject span, .b2bapp span, .b2buser span {
@apply ml-4 mb-2 block font-semibold;
}
/* Specific styling for the role text */
.b2bprojectrole {
@apply mt-2 ml-4 block text-sm opacity-80 font-normal;
}
/* 5. FOOTER / PAGINATION CARDS */
a.\@max-lg\:col-span-full {
@apply flex flex-col p-6 rounded-xl border transition-all no-underline;
background-color: hsl(var(--card)) !important;
border-color: hsl(var(--border)) !important;
}
a.\@max-lg\:col-span-full:hover {
@apply shadow-sm;
border-color: hsl(var(--primary)) !important;
background-color: hsl(var(--card)) !important;
}
a.\@max-lg\:col-span-full > div:first-child {
@apply flex items-center gap-3;
}
a.\@max-lg\:col-span-full svg {
@apply w-5 h-5 m-0;
}
a.\@max-lg\:col-span-full p {
margin-bottom: 0 !important;
margin-top: 0 !important;
}
a.\@max-lg\:col-span-full p.text-fd-muted-foreground {
@apply mt-2 text-sm opacity-80;
}
/* 6. VIDEO PLAYER WRAPPER */
/* Fixes aspect ratio for ReactPlayer embeds */
.player-wrapper {
@apply relative mb-8;
padding-top: 56.25%; /* 16:9 Aspect Ratio */
}
.react-player {
@apply absolute top-0 left-0;
}
/* 7. GET STARTED BUTTON */
.get-started {
@apply inline-flex items-center justify-center px-6 py-2 rounded-full font-bold border-2 transition-all;
border-color: #ff2069;
background-color: #ff2069;
color: white;
}
.get-started:hover {
@apply opacity-90;
color: white !important;
}
/* Target any div that uses the callout color variable */
div[style*="--callout-color"] {
@apply rounded-lg shadow-sm mb-4;
/* Force Docusaurus Layout: Left Border Only */
border: 1px solid rgba(0,0,0,0.05) !important;
border-left-width: 4px !important;
/* Hide the default Fumadocs vertical colored bar inside */
& > div[role="none"] {
display: none !important;
}
}
/* --- INFO (Blue) --- */
/* We match the variable name in the style string */
div[style*="--color-fd-info"] {
background-color: #eff6ff !important;
border-left-color: #3b82f6 !important;
color: #1e3a8a !important;
}
div[style*="--color-fd-info"] svg {
color: #3b82f6 !important;
fill: transparent !important; /* Remove fill to look cleaner */
}
/* Dark Mode Info */
:is(.dark div[style*="--color-fd-info"]) {
background-color: rgba(59, 130, 246, 0.1) !important;
color: #dbeafe !important;
border-top-color: rgba(255,255,255,0.05) !important;
border-right-color: rgba(255,255,255,0.05) !important;
border-bottom-color: rgba(255,255,255,0.05) !important;
}
/* --- WARNING (Amber) --- */
div[style*="--color-fd-warn"] {
background-color: #fffbeb !important;
border-left-color: #f59e0b !important;
color: #78350f !important;
}
div[style*="--color-fd-warn"] svg {
color: #f59e0b !important;
fill: transparent !important;
}
/* Dark Mode Warning */
:is(.dark div[style*="--color-fd-warn"]) {
background-color: rgba(245, 158, 11, 0.1) !important;
color: #fef3c7 !important;
border-top-color: rgba(255,255,255,0.05) !important;
border-right-color: rgba(255,255,255,0.05) !important;
border-bottom-color: rgba(255,255,255,0.05) !important;
}
/* --- ERROR (Red) --- */
div[style*="--color-fd-error"] {
background-color: #fef2f2 !important;
border-left-color: #ef4444 !important;
color: #7f1d1d !important;
}
div[style*="--color-fd-error"] svg {
color: #ef4444 !important;
fill: transparent !important;
}
/* Dark Mode Error */
:is(.dark div[style*="--color-fd-error"]) {
background-color: rgba(239, 68, 68, 0.12) !important;
color: #fee2e2 !important;
border-top-color: rgba(255,255,255,0.05) !important;
border-right-color: rgba(255,255,255,0.05) !important;
border-bottom-color: rgba(255,255,255,0.05) !important;
}
/* --- TITLE BOLD --- */
div[style*="--callout-color"] strong,
div[style*="--callout-color"] p:first-child strong {
font-weight: 700 !important;
}
}
@layer base {
/* HEADINGS */
h1, h2, h3, h4, h5, h6 {
font-family: var(--font-sans);
color: hsl(var(--foreground)) !important;
margin-bottom: 1rem;
letter-spacing: -0.025em;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}
h1 a, h2 a, h3 a, h4 a, h5 a, h6 a {
color: inherit !important;
text-decoration: none !important;
}
h1 {
font-size: 3.5rem !important;
font-weight: 700 !important;
line-height: 1.1 !important;
margin-bottom: 1.5rem !important;
}
h2 {
font-size: 2.25rem !important;
font-weight: 600 !important;
margin-top: 3rem !important;
margin-bottom: 1rem !important;
padding-bottom: 0.5rem !important;
border-bottom: 1px solid hsl(var(--border)) !important;
}
h3 {
font-size: 2rem !important;
font-weight: 600 !important;
margin-top: 2.5rem !important;
margin-bottom: 1rem !important;
}
h4 {
font-size: 1.5rem !important;
font-weight: 600 !important;
margin-top: 2.5rem !important;
margin-bottom: 1rem !important;
}
p {
font-size: 1rem;
line-height: 1.7;
margin-bottom: 1.5rem;
}
html, body {
background-color: hsl(var(--background));
color: hsl(var(--foreground));
}
a {
color: hsl(var(--primary));
text-decoration: none;
transition: opacity 0.2s;
}
a:hover {
opacity: 0.8;
}
}
apps/docs/app/layout.config.tsx
+29
View File
@@ -0,0 +1,29 @@
import { type BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
import { BookOpen, Code2, Server } from 'lucide-react';
export const baseOptions: BaseLayoutProps = {
nav: {
title: 'ZITADEL Docs',
},
links: [
{
text: 'Guides',
url: '/',
active: 'nested-url',
icon: <BookOpen />,
},
{
text: 'APIs',
url: '/apis/introduction',
active: 'nested-url',
icon: <Code2 />,
},
{
text: 'Legal',
url: '/legal/terms-of-service',
active: 'nested-url',
icon: <Server />, // Using Server icon as placeholder or pick another one
},
],
githubUrl: 'https://github.com/zitadel/zitadel',
};
apps/docs/app/layout.tsx
+25
View File
@@ -0,0 +1,25 @@
import './global.css';
import type { Metadata } from 'next';
import { Providers } from './providers';
export const metadata: Metadata = {
metadataBase: new URL(process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000'),
icons: {
other: [
{
rel: 'stylesheet',
url: '/docs/img/icons/line-awesome/css/line-awesome.min.css',
},
],
},
};
export default function Layout({ children }: any) {
return (
<html lang="en" suppressHydrationWarning>
<body className="flex flex-col min-h-screen font-sans bg-fd-background text-fd-foreground">
<Providers>{children}</Providers>
</body>
</html>
);
}
apps/docs/app/llms-full.txt/route.ts
+10
View File
@@ -0,0 +1,10 @@
import { getLLMText, source } from '@/lib/source';
export const revalidate = false;
export async function GET() {
const scan = source.getPages().map(getLLMText);
const scanned = await Promise.all(scan);
return new Response(scanned.join('\n\n'));
}
apps/docs/app/og/docs/[...slug]/route.tsx
+28
View File
@@ -0,0 +1,28 @@
import { ImageResponse } from 'next/og';
import { notFound } from 'next/navigation';
import { source } from '@/lib/source';
import { generate as DefaultImage } from 'fumadocs-ui/og';
export const revalidate = false;
export async function GET(request: Request, context: any) {
const { slug } = context.params;
const page = source.getPage(slug.slice(0, -1));
if (!page) notFound();
return new ImageResponse(
<DefaultImage
title={page.data.title}
description={page.data.description}
site="My App"
/>,
{
width: 1200,
height: 630,
},
);
}
export function generateStaticParams() {
return [];
}
apps/docs/app/providers.tsx
+26
View File
@@ -0,0 +1,26 @@
'use client';
import { RootProvider } from 'fumadocs-ui/provider/next';
import dynamic from "next/dynamic";
import { ThemeProvider } from 'next-themes';
import MixpanelProvider from '@/components/mixpanel-provider';
import PlausibleProvider from '@/components/plausible-provider';
const SearchDialog = dynamic(() => import("@/components/inkeep-search"));
export function Providers({ children }: { children: React.ReactNode }) {
return (
<RootProvider
search={{
enabled: true,
SearchDialog: SearchDialog as any,
}}
>
<PlausibleProvider />
<MixpanelProvider>
{children}
</MixpanelProvider>
</RootProvider>
);
}
apps/docs/app/sitemap.ts
+27
View File
@@ -0,0 +1,27 @@
import { MetadataRoute } from 'next';
import { source } from '@/lib/source';
export default function sitemap(): MetadataRoute.Sitemap {
const baseUrl = 'https://zitadel.com/docs';
const docsPages = source.getPages().map((page) => ({
url: `${baseUrl}${page.url === '/' ? '' : page.url}`,
lastModified: new Date(),
changeFrequency: 'weekly' as const,
priority: 0.8,
}));
return [
{
url: baseUrl,
lastModified: new Date(),
changeFrequency: 'daily' as const,
priority: 1,
},
...docsPages,
].filter((item, index, self) =>
index === self.findIndex((t) => t.url === item.url)
);
}
apps/docs/buf.gen.yaml
+6
View File
@@ -0,0 +1,6 @@
version: v2
plugins:
- remote: buf.build/community/sudorandom-connect-openapi:v0.19.1
out: .
opt:
- format=json
apps/docs/components/PermissionTable/index.jsx
+111
View File
@@ -0,0 +1,111 @@
import React, { useMemo } from 'react';
import yaml from 'js-yaml';
import { Check, X } from 'lucide-react';
import { cn } from '@/utils/cn'; // Assuming utils/cn exists or I'll use clsx/tailwind-merge directly if not sure
// Fallback utility if generic cn doesn't exist, checking imports first is safer but I'll inline a simple merge if needed
// Checking package.json I saw clsx and tailwind-merge are dependencies.
function classNames(...classes) {
return classes.filter(Boolean).join(' ');
}
export default function PermissionTable({ data }) {
const { roles, permissions, matrix } = useMemo(() => {
if (!data) return { roles: [], permissions: [], matrix: {} };
let parsedData = data;
if (typeof data === 'string') {
try {
parsedData = yaml.load(data);
} catch (e) {
console.error('Failed to parse YAML data:', e);
return { roles: [], permissions: [], matrix: {} };
}
}
// 1. Identify all sources.
const sources = [
parsedData?.InternalAuthZ?.RolePermissionMappings,
parsedData?.SystemAuthZ?.RolePermissionMappings,
].filter(Boolean).flat();
// 2. Aggregate Data
const roleMap = new Map();
const allPermissions = new Set();
sources.forEach((mapping) => {
const roleName = mapping.Role;
const rolePerms = mapping.Permissions || [];
if (!roleMap.has(roleName)) {
roleMap.set(roleName, new Set());
}
rolePerms.forEach((perm) => {
roleMap.get(roleName).add(perm);
allPermissions.add(perm);
});
});
// 3. Sort for display
const sortedRoles = Array.from(roleMap.keys()).sort();
const sortedPermissions = Array.from(allPermissions).sort();
return {
roles: sortedRoles,
permissions: sortedPermissions,
matrix: roleMap,
};
}, [data]);
if (!roles.length) {
return <div className="p-4 text-sm text-fd-muted-foreground bg-fd-muted rounded-md border border-fd-border">No permission data available.</div>;
}
return (
<div className="overflow-x-auto my-6 rounded-lg border border-fd-border bg-fd-card shadow-sm">
<table className="w-full text-sm text-left">
<thead className="text-xs font-semibold text-fd-muted-foreground uppercase bg-fd-muted/50 border-b border-fd-border">
<tr>
<th scope="col" className="px-4 py-3 sticky left-0 z-10 bg-fd-muted/95 backdrop-blur shadow-[1px_0_0_0_rgba(0,0,0,0.1)] dark:shadow-[1px_0_0_0_rgba(255,255,255,0.1)]">
Permission
</th>
{roles.map((role) => (
<th key={role} scope="col" className="px-4 py-3 whitespace-nowrap text-center min-w-[100px]">
{role.replace(/_/g, ' ')}
</th>
))}
</tr>
</thead>
<tbody className="divide-y divide-fd-border">
{permissions.map((perm) => (
<tr key={perm} className="hover:bg-fd-accent/50 transition-colors">
<th scope="row" className="px-4 py-2 font-medium text-fd-foreground whitespace-nowrap sticky left-0 z-10 bg-fd-card shadow-[1px_0_0_0_rgba(0,0,0,0.1)] dark:shadow-[1px_0_0_0_rgba(255,255,255,0.1)]">
{perm}
</th>
{roles.map((role) => {
const hasPermission = matrix.get(role).has(perm);
return (
<td
key={`${role}-${perm}`}
className={classNames(
"px-4 py-2 text-center",
hasPermission ? "bg-green-50/50 dark:bg-green-900/10" : ""
)}
>
{hasPermission ? (
<Check className="w-4 h-4 text-green-600 dark:text-green-400 mx-auto" strokeWidth={3} />
) : (
<span className="sr-only">No</span>
)}
</td>
);
})}
</tr>
))}
</tbody>
</table>
</div>
);
}
apps/docs/components/api-page.client.tsx
+4
View File
@@ -0,0 +1,4 @@
'use client';
import { defineClientConfig } from 'fumadocs-openapi/ui/client';
export default defineClientConfig();
apps/docs/components/api-page.tsx
+27
View File
@@ -0,0 +1,27 @@
import { createOpenAPI } from 'fumadocs-openapi/server';
import { createAPIPage } from 'fumadocs-openapi/ui';
import path from 'path';
import client from './api-page.client';
export function APIPage({ document, operations }: { document: string; operations: any[] }) {
if (!path.isAbsolute(document) && !document.startsWith('openapi/')) {
throw new Error(`APIPage document path MUST start with 'openapi/'. Received: ${document}`);
}
const absoluteDocument = path.isAbsolute(document)
? document
: path.join(process.cwd(), 'openapi', document.slice('openapi/'.length));
const openapi = createOpenAPI({
input: [absoluteDocument],
});
const InnerAPIPage = createAPIPage(openapi, {
client,
});
return <InnerAPIPage document={absoluteDocument} operations={operations} />;
}
docs/src/components/apicard.jsx → apps/docs/components/apicard.jsx
+1 -1
View File
@@ -1,6 +1,6 @@
import React from "react";
import styles from "../css/apicard.module.css";
import styles from "@/css/apicard.module.css";
export function ApiCard({ type, children }) {
let classes = "";
docs/src/components/b2b.jsx → apps/docs/components/b2b.jsx
View File
docs/src/components/benchmark_chart.jsx → apps/docs/components/benchmark_chart.jsx
+1
View File
@@ -1,3 +1,4 @@
"use client";
import React from "react";
import Chart from "react-google-charts";
docs/src/components/column.jsx → apps/docs/components/column.jsx
View File
apps/docs/components/docusaurus/admonition.tsx
+19
View File
@@ -0,0 +1,19 @@
import { Callout } from 'fumadocs-ui/components/callout';
export default function Admonition({ type, title, children, icon }: any) {
let calloutType: 'info' | 'warn' | 'error' = 'info';
switch (type) {
case 'note': calloutType = 'info'; break;
case 'tip': calloutType = 'info'; break;
case 'info': calloutType = 'info'; break;
case 'warning': calloutType = 'warn'; break;
case 'danger': calloutType = 'error'; break;
case 'caution': calloutType = 'warn'; break;
}
return (
<Callout title={title} type={calloutType} icon={icon}>
{children}
</Callout>
);
}
apps/docs/components/docusaurus/browser-only.tsx
+12
View File
@@ -0,0 +1,12 @@
"use client";
import { useEffect, useState } from 'react';
export default function BrowserOnly({ children, fallback }: any) {
const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
if (!mounted) return fallback || null;
return children();
}
apps/docs/components/docusaurus/code-block.tsx
+14
View File
@@ -0,0 +1,14 @@
import React from 'react';
export default function CodeBlock({ children, language, title, className, showLineNumbers: _showLineNumbers }: any) {
return (
<div className="my-4">
{title && <div className="bg-secondary text-secondary-foreground px-4 py-2 text-sm font-medium rounded-t-md">{title}</div>}
<pre className={`p-4 overflow-x-auto bg-secondary/50 rounded-b-md ${title ? 'rounded-t-none' : 'rounded-md'} ${className || ''}`}>
<code className={language ? `language-${language}` : ''}>
{children}
</code>
</pre>
</div>
);
}
apps/docs/components/docusaurus/doc-card-list.tsx
+30
View File
@@ -0,0 +1,30 @@
import React from 'react';
import { Cards, Card } from 'fumadocs-ui/components/card';
export default function DocCardList({ items }: { items?: any[] }) {
// If items are provided (manual list), render them
if (items) {
return (
<Cards>
{items.map((item, index) => (
<Card key={index} href={item.href} title={item.label} />
))}
</Cards>
);
}
// If no items, it's likely an auto-generated list for the current sidebar category.
// Fumadocs doesn't have a direct equivalent to "current sidebar category items" in a component easily accessible here without context.
// For now, we'll render a placeholder or nothing to avoid build errors.
// In a real migration, we'd use `useTreeContext` or similar if available, or rely on Fumadocs' index page generation.
return (
<div className="admonition admonition-info alert alert--info">
<div className="admonition-heading">
<h5>DocCardList Placeholder</h5>
</div>
<div className="admonition-content">
<p>Auto-generated card lists are not yet fully supported in the migration.</p>
</div>
</div>
);
}
apps/docs/components/docusaurus/tabs.tsx
+58
View File
@@ -0,0 +1,58 @@
import { Tabs as FumadocsTabs, Tab as FumadocsTab } from 'fumadocs-ui/components/tabs';
import React, { isValidElement } from 'react';
export function TabItem({ value, label: _label, children, default: _isDefault, className, attributes }: any) {
return <FumadocsTab value={value} className={className} {...attributes}>{children}</FumadocsTab>;
}
export default function Tabs({ children, defaultValue, values, groupId, className }: any) {
let items: string[] = [];
const childrenArray = React.Children.toArray(children);
if (values) {
items = values.map((v: any) => v.label);
} else {
childrenArray.forEach((child) => {
if (isValidElement(child)) {
const props = child.props as any;
const label = props.label || props.value;
items.push(label);
}
});
}
const newChildren = childrenArray.map((child, index) => {
if (isValidElement(child)) {
const props = child.props as any;
let label = props.label;
if (!label && values) {
const valObj = values.find((v: any) => v.value === props.value);
if (valObj) label = valObj.label;
}
if (!label) label = props.value;
return <FumadocsTab key={index} value={label} {...props}>{props.children}</FumadocsTab>;
}
return child;
});
let newDefaultValue = defaultValue;
if (defaultValue && values) {
const valObj = values.find((v: any) => v.value === defaultValue);
if (valObj) newDefaultValue = valObj.label;
} else if (defaultValue) {
const child = childrenArray.find((c: any) => (c as any).props.value === defaultValue);
if (child) {
newDefaultValue = (child as any).props.label || (child as any).props.value;
}
}
return (
<FumadocsTabs items={items} defaultValue={newDefaultValue} groupId={groupId} className={className}>
{newChildren}
</FumadocsTabs>
);
}
apps/docs/components/docusaurus/themed-image.tsx
+17
View File
@@ -0,0 +1,17 @@
"use client";
import Image from 'next/image';
import { useTheme } from 'next-themes';
import { useEffect, useState } from 'react';
export default function ThemedImage({ sources, alt, ...props }: any) {
const { resolvedTheme } = useTheme();
const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
if (!mounted) return <Image src={sources.light} alt={alt} {...props} />;
const src = resolvedTheme === 'dark' ? sources.dark : sources.light;
return <Image src={src} alt={alt} {...props} />;
}
apps/docs/components/feedback.tsx
+56
View File
@@ -0,0 +1,56 @@
'use client';
import { useState } from 'react';
import { mixpanelClient } from '@/utils/mixpanel';
import { usePathname } from 'next/navigation';
import { ThumbsUp, ThumbsDown } from 'lucide-react';
import { cn } from '@/utils/cn';
export function Feedback() {
const pathname = usePathname();
const [voted, setVoted] = useState<boolean | null>(null);
const handleVote = (useful: boolean) => {
setVoted(useful);
mixpanelClient.track('helpfulness_vote', {
path: pathname,
useful: useful,
});
};
if (voted !== null) {
return (
<div className="flex flex-col gap-2 border-t pt-8 mt-8">
<p className="text-sm text-fd-muted-foreground">
Thanks for your feedback!
</p>
</div>
);
}
return (
<div className="flex flex-col gap-2 border-t pt-8 mt-8">
<p className="text-sm text-fd-muted-foreground">Was this page helpful?</p>
<div className="flex gap-2">
<button
onClick={() => handleVote(true)}
className={cn(
"p-2 rounded-md transition-colors border hover:bg-fd-accent hover:text-fd-accent-foreground border-fd-border text-fd-muted-foreground"
)}
aria-label="Helpful"
>
<ThumbsUp className="size-4" />
</button>
<button
onClick={() => handleVote(false)}
className={cn(
"p-2 rounded-md transition-colors border hover:bg-fd-accent hover:text-fd-accent-foreground border-fd-border text-fd-muted-foreground"
)}
aria-label="Not helpful"
>
<ThumbsDown className="size-4" />
</button>
</div>
</div>
);
}
docs/src/components/frameworks.jsx → apps/docs/components/frameworks.jsx
+1 -1
View File
@@ -1,6 +1,6 @@
import React from "react";
import { Tile } from "./tile";
import frameworks from "../../frameworks.json";
import frameworks from "../frameworks.json";
export function Frameworks({ filter }) {
const filteredFrameworks = frameworks.filter((framework) => {
apps/docs/components/inkeep-search.tsx
+71
View File
@@ -0,0 +1,71 @@
"use client";
import type { SharedProps } from "fumadocs-ui/components/dialog/search";
import {
InkeepModalSearchAndChat,
type InkeepModalSearchAndChatProps,
} from "@inkeep/cxkit-react";
import { useEffect, useState } from "react";
export default function CustomDialog(props: SharedProps) {
const [syncTarget, setSyncTarget] = useState<HTMLElement | null>(null);
const { open, onOpenChange } = props;
// We do this because document is not available in the server
useEffect(() => {
setSyncTarget(document.documentElement);
}, []);
const config: InkeepModalSearchAndChatProps = {
baseSettings: {
apiKey: process.env.NEXT_PUBLIC_INKEEP_API_KEY,
primaryBrandColor: '#425b76',
organizationDisplayName: "Zitadel",
colorMode: {
sync: {
target: syncTarget,
attributes: ["class"],
isDarkMode: (attributes) => !!attributes.class?.includes("dark"),
},
},
},
modalSettings: {
isOpen: open,
onOpenChange,
// optional settings
},
searchSettings: {
// optional settings
},
aiChatSettings: {
aiAssistantName: 'Zitadel AI Assistant',
chatSubjectName: 'Zitadel',
placeholder: 'How can I enable MFA?',
introMessage: 'Hey! I’m the Zitadel AI assistant 🤖 — throw your questions my way!',
aiAssistantAvatar: '/icons/favicon-32x32.png',
userAvatar: '/icons/user.png',
exampleQuestionsLabel: 'Example Questions:',
exampleQuestions: [
'What is an Instance?',
'What is an Organization?',
'How to create an Action?',
'How to integrate Zitadel to my React app?',
],
isFirstExampleQuestionHighlighted: true,
shouldOpenLinksInNewTab: true,
isCopyChatButtonVisible: true,
disclaimerSettings: {
isEnabled: true,
label: 'AI Assistant',
tooltip: 'Responses are AI-generated and may require verification.',
},
toolbarButtonLabels: {
clear: 'Start Over',
share: 'Share Chat',
getHelp: 'Get Help',
stop: 'Stop',
copyChat: 'Copy Chat',
},
},
};
return <InkeepModalSearchAndChat {...config} />;
}
apps/docs/components/mixpanel-provider.tsx
+51
View File
@@ -0,0 +1,51 @@
'use client';
import { initMixpanel, mixpanelClient, optInTracking, optOutTracking } from '@/utils/mixpanel';
import React, { useEffect } from 'react';
export default function MixpanelProvider({ children }: { children: React.ReactNode }) {
useEffect(() => {
const setup = async () => {
await initMixpanel();
const CookieConsent = await import('vanilla-cookieconsent');
const cookie = CookieConsent.getCookie();
// @ts-ignore
if (!cookie || !cookie.services || !cookie.services.analytics) {
// We only send data when people opt-in, not just if they have not opted out.
return;
}
// @ts-ignore
const hasMixpanelConsent = cookie?.services?.analytics?.indexOf('mixpanel') !== -1;
if (hasMixpanelConsent) {
optInTracking();
} else {
optOutTracking();
}
};
setup().catch((error) => {
console.error('Error setting up Mixpanel:', error);
});
const handleConsentChange = async () => {
const CookieConsent = await import('vanilla-cookieconsent');
const cookie = CookieConsent.getCookie();
// @ts-ignore
const hasMixpanelConsent = cookie?.services?.analytics?.indexOf('mixpanel') !== -1;
if (hasMixpanelConsent) {
optInTracking();
} else {
optOutTracking();
}
};
window.addEventListener('cc:onChange:mixpanel', handleConsentChange);
return () => {
window.removeEventListener('cc:onChange:mixpanel', handleConsentChange);
};
}, []);
return <>{children}</>;
}
docs/src/components/pii_table.jsx → apps/docs/components/pii_table.jsx
+15 -7
View File
@@ -85,22 +85,30 @@ export function PiiTable() {
return (
<table className="text-xs">
<thead>
<tr>
<th>Type of personal data</th>
<th>Examples</th>
<th>Affected data subjects</th>
</tr>
</thead>
<tbody>
{
pii.map((row, rowID) => {
return (
<tr>
<td key={rowID}>{row.type}</td>
<td><ul>{row.examples.map((example) => { return ( <li>{example}</li> )})}</ul></td>
pii.map((row) => (
<tr key={row.type}>
<td>{row.type}</td>
<td>
<ul>
{row.examples.map((example) => (
<li key={example}>{example}</li>
))}
</ul>
</td>
<td>{row.subjects}</td>
</tr>
)
})
))
}
</tbody>
</table>
);
}
apps/docs/components/plausible-provider.tsx
+17
View File
@@ -0,0 +1,17 @@
'use client';
import Script from 'next/script';
export default function PlausibleProvider() {
const domain = process.env.NEXT_PUBLIC_PLAUSIBLE_DOMAIN || 'zitadel.com';
return (
<Script
defer
data-domain={domain}
data-api="/docs/pl/api/event"
src="/docs/pl/js/script.js"
strategy="afterInteractive"
/>
);
}
apps/docs/components/player.jsx
+37
View File
@@ -0,0 +1,37 @@
"use client";
import React from "react";
export function ResponsivePlayer({ url }) {
const getYouTubeId = (url) => {
if (!url) return null;
const regExp = /^.*(youtu.be\/|v\/|u\/\w\/|embed\/|watch\?v=|&v=)([^#&?]*).*/;
const match = url.match(regExp);
return (match && match[2].length === 11) ? match[2] : null;
};
const videoId = getYouTubeId(url);
if (videoId) {
return (
/* 1. Removed 'player-wrapper' class to avoid global.css conflict (double height).
2. Reduced max-width to 'max-w-2xl' so it fits better in the text flow.
*/
<div className="relative w-full max-w-2xl mx-auto h-0 pb-[56.25%] mb-8 rounded-lg overflow-hidden border border-zinc-200 dark:border-zinc-800 bg-black shadow-md">
<iframe
src={`https://www.youtube.com/embed/${videoId}`}
title="YouTube video player"
className="absolute top-0 left-0 w-full h-full"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
/>
</div>
);
}
return (
<div className="p-4 mb-8 border border-red-200 bg-red-50 text-red-600 rounded-lg text-sm">
Video source not supported: {url}
</div>
);
}
docs/src/components/tile.jsx → apps/docs/components/tile.jsx
+1 -1
View File
@@ -1,5 +1,5 @@
import React from "react";
import styles from "../css/tile.module.css";
import styles from '@/css/tile.module.css';
export function Tile({ title, imageSource, imageSourceLight, link, external }) {
return (
apps/docs/components/version-selector.tsx
+93
View File
@@ -0,0 +1,93 @@
'use client';
import * as React from 'react';
import { usePathname, useRouter } from 'next/navigation';
interface DocVersion {
param: string;
label: string;
url: string;
ref: string;
refType: string;
type?: 'external';
}
import rawVersions from '../content/versions.json';
const versions = rawVersions as DocVersion[];
export function VersionSelector() {
const pathname = usePathname();
const router = useRouter();
// Handle basePath issues: usePathname() typically returns path relative to basePath if configured?
// But purely relying on that is tricky. Let's normalize.
// If pathname starts with /docs, assume it's the full path and we strip it for logic,
// then let router handle re-adding it if needed (or we check behaviors).
// Actually, Next.js router.push() expects path relative to basePath usually?
// Let's implement robust segment swapping.
const normalizePath = (p: string) => {
if (p.startsWith('/docs')) return p.slice(5) || '/';
return p;
};
const normalizedPath = normalizePath(pathname);
const currentVersionObj = versions.find((v) => {
if (!v.param || v.param === 'latest') return false;
return normalizedPath.startsWith(`/${v.param}`);
});
const currentVersion = currentVersionObj ? currentVersionObj.param : 'latest';
const handleChange = (e: React.ChangeEvent<HTMLSelectElement>) => {
const value = e.target.value;
const version = versions.find((v) => (v.param || v.label) === value);
if (!version) return;
if (!version.param) return;
// Calculate the 'tail' of the path (content path)
let tail = normalizedPath;
if (currentVersion !== 'latest') {
// Strip current version prefix
// e.g. /v4.10/foo -> /foo
tail = normalizedPath.replace(new RegExp(`^/${currentVersion}`), '') || '/';
}
// Construct new path
let newPath = tail;
if (version.param !== 'latest') {
// Add new version prefix
// e.g. /foo -> /v4.9/foo
// Handle root slash
if (tail === '/') {
newPath = `/${version.param}`;
} else {
newPath = `/${version.param}${tail}`;
}
}
// Next.js router handles basePath automatically if configured correctly.
// If we push '/v4.10', it becomes '/docs/v4.10'.
router.push(newPath);
};
return (
<select
value={currentVersion}
onChange={handleChange}
className="p-2 bg-transparent text-sm font-medium rounded-md border border-fd-border hover:bg-fd-accent/50 focus:outline-none focus:ring-2 focus:ring-fd-ring text-fd-foreground w-full mb-4"
>
{versions.map((v) => (
<option
key={v.param || v.label}
value={v.param || v.label}
className="bg-fd-background text-fd-foreground"
>
{v.label}
</option>
))}
</select>
);
}
apps/docs/content/apis/_meta.json
+203
View File
@@ -0,0 +1,203 @@
{
"root": true,
"pages": [
"introduction",
{
"title": "Core Resources",
"pages": [
{
"title": "V2",
"pages": [
{
"title": "User",
"pages": [
"../reference/api/user"
]
},
{
"title": "Session",
"pages": [
"../reference/api/session"
]
},
{
"title": "OIDC",
"pages": [
"../reference/api/oidc"
]
},
{
"title": "SAML",
"pages": [
"../reference/api/saml"
]
},
{
"title": "Settings",
"pages": [
"../reference/api/settings"
]
},
{
"title": "Feature",
"pages": [
"../reference/api/feature"
]
},
{
"title": "Organization",
"pages": [
"../reference/api/org"
]
},
{
"title": "Identity Provider",
"pages": [
"../reference/api/idp"
]
},
{
"title": "Web Key",
"pages": [
"../reference/api/webkey"
]
},
{
"title": "Action",
"pages": [
"../reference/api/action"
]
},
{
"title": "Instance",
"pages": [
"../reference/api/instance"
]
},
{
"title": "Project",
"pages": [
"../reference/api/project"
]
},
{
"title": "Application",
"pages": [
"../reference/api/application"
]
},
{
"title": "Authorizations",
"pages": [
"../reference/api/authorization"
]
},
{
"title": "Internal Permissions",
"pages": [
"../reference/api/internal_permission"
]
}
]
},
{
"title": "V1",
"pages": [
{
"title": "Authenticated User",
"pages": [
"../reference/api-v1/auth"
]
},
{
"title": "Organization Objects",
"pages": [
"../reference/api-v1/management"
]
},
{
"title": "Instance Objects",
"pages": [
"../reference/api-v1/admin"
]
},
{
"title": "Instance Lifecycle",
"pages": [
"../reference/api-v1/system"
]
},
"migration_v1_to_v2"
]
},
{
"title": "Assets",
"pages": [
"assets/assets"
]
}
]
},
{
"title": "Observability",
"pages": [
"observability/metrics",
"observability/health"
]
},
{
"title": "Provision Users",
"pages": [
"scim2"
]
},
{
"title": "gRPC Status Codes",
"url": "statuscodes"
},
{
"title": "Rate Limits (Cloud)",
"url": "/legal/policies/rate-limit-policy"
},
{
"title": "Benchmarks",
"pages": [
{
"title": "v2.65.0",
"pages": [
"benchmarks/v2.65.0/machine_jwt_profile_grant/index"
]
},
{
"title": "v2.66.0",
"pages": [
"benchmarks/v2.66.0/machine_jwt_profile_grant/index"
]
},
{
"title": "v2.70.0",
"pages": [
"benchmarks/v2.70.0/machine_jwt_profile_grant/index",
"benchmarks/v2.70.0/oidc_session/index"
]
},
{
"title": "v4",
"pages": [
"benchmarks/v4/add_session/index",
"benchmarks/v4/human_password_login/index",
"benchmarks/v4/introspect/index",
"benchmarks/v4/machine_client_credentials_login/index",
"benchmarks/v4/machine_jwt_profile_grant/index",
"benchmarks/v4/machine_pat_login/index",
"benchmarks/v4/manipulate_user/index",
"benchmarks/v4/oidc_session/index",
"benchmarks/v4/otp_session/index",
"benchmarks/v4/password_session/index",
"benchmarks/v4/user_info/index"
]
}
]
}
]
}
docs/docs/apis/actions/code-examples.mdx → apps/docs/content/apis/actions/code-examples.mdx
+21 -21
View File
@@ -13,7 +13,7 @@ Append claims returned on OIDC requests.
### Triggers
- Complement token
- [Pre Userinfo creation](./complement-token#pre-userinfo-creation-id_token--userinfo--introspection-endpoint)
- [Pre Userinfo creation](./complement-token#pre-userinfo-creation-id-token-userinfo-introspection-endpoint)
- [Pre access token creation](./complement-token#pre-access-token-creation)
### Set hardcoded claim
@@ -88,7 +88,7 @@ Append attributes returned on SAML requests.
### Triggers
- Complement SAMLResponse
- [Pre SAMLResponse creation](./customize-samlresponse#pre-samlresponse-creation)
- [Pre SAMLResponse creation](./customize-samlresponse#pre-saml-response-creation)
### Custom role mapping in attributes
@@ -127,9 +127,9 @@ Useful if you trust the provided information or don't want the users to verify t
#### Triggers
- Internal Authentication
- [Pre Creation](/docs/apis/actions/internal-authentication#pre-creation)
- [Pre Creation](/apis/actions/internal-authentication#pre-creation)
- External Authentication
- [Pre Creation](/docs/apis/actions/external-authentication#pre-creation)
- [Pre Creation](/apis/actions/external-authentication#pre-creation)
<details open="">
<summary>Code example</summary>
@@ -147,9 +147,9 @@ Allows you to add default user grants to a user after it was created or federate
#### Triggers
- Internal Authentication
- [Post Creation](/docs/apis/actions/internal-authentication#post-creation)
- [Post Creation](/apis/actions/internal-authentication#post-creation)
- External Authentication
- [Post Creation](/docs/apis/actions/external-authentication#post-creation)
- [Post Creation](/apis/actions/external-authentication#post-creation)
<details open="">
<summary>Code example</summary>
@@ -167,11 +167,11 @@ Adding metadata to users allows you to set default metadata on users.
#### Triggers
- Internal Authentication
- [Pre Creation](/docs/apis/actions/internal-authentication#pre-creation)
- [Post Authentication](/docs/apis/actions/internal-authentication#post-authentication)
- [Pre Creation](/apis/actions/internal-authentication#pre-creation)
- [Post Authentication](/apis/actions/internal-authentication#post-authentication)
- External Authentication
- [Pre Creation](/docs/apis/actions/internal-authentication#pre-creation)
- [Post Authentication](/docs/apis/actions/internal-authentication#post-authentication)
- [Pre Creation](/apis/actions/internal-authentication#pre-creation)
- [Post Authentication](/apis/actions/internal-authentication#post-authentication)
<details open="">
<summary>Code example</summary>
@@ -245,7 +245,7 @@ https://github.com/zitadel/actions/blob/main/examples/set_idp_picture_metadata.j
### Attributes provided by Okta as SAML IDP
If you use [Okta as an identity provider](/guides/integrate/identity-providers/okta-saml#add-attribute-statements) you can improve the onboarding experience of new users by prefilling some basic information during authentication.
If you use [Okta as an identity provider](/guides/integrate/identity-providers/okta_saml#add-attribute-statements) you can improve the onboarding experience of new users by prefilling some basic information during authentication.
<details open="">
<summary>Code example</summary>
@@ -293,13 +293,13 @@ Execution paths might change based on the application initiating the authenticat
#### Triggers
- Internal Authentication
- [Pre Creation](/docs/apis/actions/internal-authentication#pre-creation)
- [Post Creation](/docs/apis/actions/internal-authentication#post-creation)
- [Post Authentication](/docs/apis/actions/internal-authentication#post-authentication)
- [Pre Creation](/apis/actions/internal-authentication#pre-creation)
- [Post Creation](/apis/actions/internal-authentication#post-creation)
- [Post Authentication](/apis/actions/internal-authentication#post-authentication)
- External Authentication
- [Pre Creation](/docs/apis/actions/external-authentication#pre-creation)
- [Post Creation](/docs/apis/actions/external-authentication#post-creation)
- [Post Authentication](/docs/apis/actions/external-authentication#post-authentication)
- [Pre Creation](/apis/actions/external-authentication#pre-creation)
- [Post Creation](/apis/actions/external-authentication#post-creation)
- [Post Authentication](/apis/actions/external-authentication#post-authentication)
<details open="">
<summary>Code example</summary>
@@ -310,7 +310,7 @@ https://github.com/zitadel/actions/blob/main/examples/execute_action_on_specific
</details>
This example uses [zitadel's log module](/docs/apis/actions/modules#log)
This example uses [zitadel's log module](/apis/actions/modules#log)
### Check authentication error
@@ -319,9 +319,9 @@ Your action can also check for errors during the login process.
#### Triggers
- Internal Authentication
- [Post Authentication](/docs/apis/actions/internal-authentication#post-authentication)
- [Post Authentication](/apis/actions/internal-authentication#post-authentication)
- External Authentication
- [Post Authentication](/docs/apis/actions/external-authentication#post-authentication)
- [Post Authentication](/apis/actions/external-authentication#post-authentication)
<details open="">
<summary>Code example</summary>
@@ -332,7 +332,7 @@ https://github.com/zitadel/actions/blob/main/examples/post_auth_log.js
</details>
This example uses [zitadel's log module](/docs/apis/actions/modules#log)
This example uses [zitadel's log module](/apis/actions/modules#log)
### Throw an error
docs/docs/apis/actions/complement-token.md → apps/docs/content/apis/actions/complement-token.mdx
View File
docs/docs/apis/actions/customize-samlresponse.md → apps/docs/content/apis/actions/customize-samlresponse.mdx
View File
docs/docs/apis/actions/external-authentication.md → apps/docs/content/apis/actions/external-authentication.mdx
+6 -6
View File
@@ -30,8 +30,8 @@ The first parameter contains the following fields
- `externalUser` [*externalUser*](./objects#external-user)
- `authError` *string*
This is a verification errors string representation. If the verification succeeds, this is "none"
- `authRequest` [*auth request*](/docs/apis/actions/objects#auth-request)
- `httpRequest` [*http request*](/docs/apis/actions/objects#http-request)
- `authRequest` [*auth request*](/apis/actions/objects#auth-request)
- `httpRequest` [*http request*](/apis/actions/objects#http-request)
- `providerInfo` *Any*
Returns the response of the provider. In case the provider is a Generic OAuth Provider, the information is accessible through:
- `rawInfo` *Any*
@@ -78,8 +78,8 @@ The trigger is represented by the following Ids in the API: `TRIGGER_TYPE_PRE_CR
The first parameter contains the following fields
- `v1`
- `user` [*human*](./objects#human-user)
- `authRequest` [*auth request*](/docs/apis/actions/objects#auth-request)
- `httpRequest` [*http request*](/docs/apis/actions/objects#http-request)
- `authRequest` [*auth request*](/apis/actions/objects#auth-request)
- `httpRequest` [*http request*](/apis/actions/objects#http-request)
- `org`
- `getMetadata()` [*metadataResult*](./objects#metadata-result)
- `api`
@@ -126,8 +126,8 @@ The trigger is represented by the following Ids in the API: `TRIGGER_TYPE_POST_C
The first parameter contains the following fields
- `v1`
- `getUser()` [*user*](./objects#user)
- `authRequest` [*auth request*](/docs/apis/actions/objects#auth-request)
- `httpRequest` [*http request*](/docs/apis/actions/objects#http-request)
- `authRequest` [*auth request*](/apis/actions/objects#auth-request)
- `httpRequest` [*http request*](/apis/actions/objects#http-request)
- `org`
- `getMetadata()` [*metadataResult*](./objects#metadata-result)
- `api`
docs/docs/apis/actions/internal-authentication.md → apps/docs/content/apis/actions/internal-authentication.mdx
+6 -6
View File
@@ -23,8 +23,8 @@ The trigger is represented by the following Ids in the API: `TRIGGER_TYPE_POST_A
This is one of "password", "OTP", "U2F" or "passwordless"
- `authError` *string*
This is a verification errors string representation. If the verification succeeds, this is "none"
- `authRequest` [*auth request*](/docs/apis/actions/objects#auth-request)
- `httpRequest` [*http request*](/docs/apis/actions/objects#http-request)
- `authRequest` [*auth request*](/apis/actions/objects#auth-request)
- `httpRequest` [*http request*](/apis/actions/objects#http-request)
- `api`
The second parameter contains the following fields
- `metadata`
@@ -47,8 +47,8 @@ The trigger is represented by the following Ids in the API: `TRIGGER_TYPE_PRE_CR
The first parameter contains the following fields
- `v1`
- `user` [*human*](./objects#human-user)
- `authRequest` [*auth request*](/docs/apis/actions/objects#auth-request)
- `httpRequest` [*http request*](/docs/apis/actions/objects#http-request)
- `authRequest` [*auth request*](/apis/actions/objects#auth-request)
- `httpRequest` [*http request*](/apis/actions/objects#http-request)
- `api`
The second parameter contains the following fields
- `metadata`
@@ -94,8 +94,8 @@ The trigger is represented by the following Ids in the API: `TRIGGER_TYPE_POST_C
The first parameter contains the following fields
- `v1`
- `getUser()` [*user*](./objects#user)
- `authRequest` [*auth request*](/docs/apis/actions/objects#auth-request)
- `httpRequest` [*http request*](/docs/apis/actions/objects#http-request)
- `authRequest` [*auth request*](/apis/actions/objects#auth-request)
- `httpRequest` [*http request*](/apis/actions/objects#http-request)
- `api`
The second parameter contains the following fields
- `userGrants` Array of [*userGrant*](./objects#user-grant)'s
docs/docs/apis/actions/introduction.md → apps/docs/content/apis/actions/introduction.mdx
View File
docs/docs/apis/actions/modules.md → apps/docs/content/apis/actions/modules.mdx
View File
docs/docs/apis/actions/objects.md → apps/docs/content/apis/actions/objects.mdx
+2 -2
View File
@@ -111,7 +111,7 @@ title: Objects
## Auth Request
This object contains context information about the request to the [authorization endpoint](/docs/apis/openidoauth/endpoints#authorization_endpoint).
This object contains context information about the request to the [authorization endpoint](/apis/openidoauth/endpoints#authorization-endpoint).
- `id` *string*
- `agentId` *string*
@@ -194,7 +194,7 @@ This object represents a list of user grant stored in ZITADEL.
- `grants` Array of
- `id` *string*
- `projectGrantId` *string*
The id of the [project grant](/docs/guides/solution-scenarios/saas#project-grant)
The id of the [project grant](/guides/solution-scenarios/saas#project-grant)
- `state` *Number*
<ul><li>0: unspecified</li><li>1: active</li><li>2: inactive</li><li>3: removed</li></ul>
- `creationDate` *Date*
docs/docs/apis/apis/index.mdx → apps/docs/content/apis/apis/index.mdx
+1 -1
View File
@@ -3,7 +3,7 @@ title: Core Resources
sidebar_label: Core Resources
---
import DocCardList from '@theme/DocCardList';
import DocCardList from '@/components/docusaurus/doc-card-list';
ZITADEL provides multiple APIs to manage the system, instances and resources such as users, projects and more.
docs/docs/apis/assets/assets.md → apps/docs/content/apis/assets/assets.mdx
+12 -74
View File
@@ -4,256 +4,194 @@ title: zitadel/assets
## AssetsService
### UploadDefaultLabelPolicyFont()
> UploadDefaultLabelPolicyFont()
POST: /instance/policy/label/font
### GetDefaultLabelPolicyFont()
> GetDefaultLabelPolicyFont()
GET: /instance/policy/label/font
### GetPreviewDefaultLabelPolicyFont()
> GetPreviewDefaultLabelPolicyFont()
GET: /instance/policy/label/font/_preview
### UploadDefaultLabelPolicyIcon()
> UploadDefaultLabelPolicyIcon()
POST: /instance/policy/label/icon
### UploadDefaultLabelPolicyIcon()
### UploadDefaultLabelPolicyIconDark()
> UploadDefaultLabelPolicyIconDark()
POST: /instance/policy/label/icon/dark
### GetDefaultLabelPolicyIcon()
> GetDefaultLabelPolicyIcon()
GET: /instance/policy/label/icon
### GetDefaultLabelPolicyIcon()
### GetDefaultLabelPolicyIconDark()
> GetDefaultLabelPolicyIconDark()
GET: /instance/policy/label/icon/dark
### GetPreviewDefaultLabelPolicyIcon()
> GetPreviewDefaultLabelPolicyIcon()
GET: /instance/policy/label/icon/_preview
### GetPreviewDefaultLabelPolicyIcon()
### GetPreviewDefaultLabelPolicyIconDark()
> GetPreviewDefaultLabelPolicyIconDark()
GET: /instance/policy/label/icon/dark/_preview
### UploadDefaultLabelPolicyLogo()
> UploadDefaultLabelPolicyLogo()
POST: /instance/policy/label/logo
### UploadDefaultLabelPolicyLogo()
### UploadDefaultLabelPolicyLogoDark()
> UploadDefaultLabelPolicyLogoDark()
POST: /instance/policy/label/logo/dark
### GetDefaultLabelPolicyLogo()
> GetDefaultLabelPolicyLogo()
GET: /instance/policy/label/logo
### GetDefaultLabelPolicyLogo()
### GetDefaultLabelPolicyLogoDark()
> GetDefaultLabelPolicyLogoDark()
GET: /instance/policy/label/logo/dark
### GetPreviewDefaultLabelPolicyLogo()
> GetPreviewDefaultLabelPolicyLogo()
GET: /instance/policy/label/logo/_preview
### GetPreviewDefaultLabelPolicyLogo()
### GetPreviewDefaultLabelPolicyLogoDark()
> GetPreviewDefaultLabelPolicyLogoDark()
GET: /instance/policy/label/logo/dark/_preview
### UploadOrgLabelPolicyFont()
> UploadOrgLabelPolicyFont()
POST: /org/policy/label/font
### GetOrgLabelPolicyFont()
> GetOrgLabelPolicyFont()
GET: /org/policy/label/font
### GetPreviewOrgLabelPolicyFont()
> GetPreviewOrgLabelPolicyFont()
GET: /org/policy/label/font/_preview
### UploadOrgLabelPolicyIcon()
> UploadOrgLabelPolicyIcon()
POST: /org/policy/label/icon
### UploadOrgLabelPolicyIcon()
### UploadOrgLabelPolicyIconDark()
> UploadOrgLabelPolicyIconDark()
POST: /org/policy/label/icon/dark
### GetOrgLabelPolicyIcon()
> GetOrgLabelPolicyIcon()
GET: /org/policy/label/icon
### GetOrgLabelPolicyIcon()
### GetOrgLabelPolicyIconDark()
> GetOrgLabelPolicyIconDark()
GET: /org/policy/label/icon/dark
### GetPreviewOrgLabelPolicyIcon()
> GetPreviewOrgLabelPolicyIcon()
GET: /org/policy/label/icon/_preview
### GetPreviewOrgLabelPolicyIcon()
### GetPreviewOrgLabelPolicyIconDark()
> GetPreviewOrgLabelPolicyIconDark()
GET: /org/policy/label/icon/dark/_preview
### UploadOrgLabelPolicyLogo()
> UploadOrgLabelPolicyLogo()
POST: /org/policy/label/logo
### UploadOrgLabelPolicyLogo()
### UploadOrgLabelPolicyLogoDark()
> UploadOrgLabelPolicyLogoDark()
POST: /org/policy/label/logo/dark
### GetOrgLabelPolicyLogo()
> GetOrgLabelPolicyLogo()
GET: /org/policy/label/logo
### GetOrgLabelPolicyLogo()
### GetOrgLabelPolicyLogoDark()
> GetOrgLabelPolicyLogoDark()
GET: /org/policy/label/logo/dark
### GetPreviewOrgLabelPolicyLogo()
> GetPreviewOrgLabelPolicyLogo()
GET: /org/policy/label/logo/_preview
### GetPreviewOrgLabelPolicyLogo()
### GetPreviewOrgLabelPolicyLogoDark()
> GetPreviewOrgLabelPolicyLogoDark()
GET: /org/policy/label/logo/dark/_preview
### UploadMyUserAvatar()
> UploadMyUserAvatar()
POST: /users/me/avatar
### GetMyUserAvatar()
> GetMyUserAvatar()
GET: /users/me/avatar
docs/docs/apis/benchmarks/_template.mdx → apps/docs/content/apis/benchmarks/_template.mdx
+3 -37
View File
@@ -1,32 +1,5 @@
<!--
query data from output.csv:
Note: you might need to adjust the WHERE clause to only filter the required trends and the current placeholders
Warning: it's currently only possible to show data of one endpoint
```
copy (SELECT
metric_name
, to_timestamp(timestamp::DOUBLE) as timestamp
, approx_quantile(metric_value, 0.50) AS p50
, approx_quantile(metric_value, 0.95) AS p95
, approx_quantile(metric_value, 0.99) AS p99
FROM
read_csv('result.csv', auto_detect=false, null_padding=true, delim=',', quote='"', escape='"', new_line='\n', skip=0, comment='', header=true, columns={'metric_name': 'VARCHAR', 'timestamp': 'BIGINT', 'metric_value': 'DOUBLE', 'check': 'VARCHAR', 'error': 'VARCHAR', 'error_code': 'VARCHAR', 'expected_response': 'BOOLEAN', 'group': 'VARCHAR', 'method': 'VARCHAR', 'name': 'VARCHAR', 'proto': 'VARCHAR', 'scenario': 'VARCHAR', 'service': 'VARCHAR', 'status': 'BIGINT', 'subproto': 'VARCHAR', 'tls_version': 'VARCHAR', 'url': 'VARCHAR', 'extra_tags': 'VARCHAR', 'metadata': 'VARCHAR'})
WHERE
metric_name <> 'http_req_duration'
AND metric_name <> 'iteration_duration'
AND metric_name LIKE '%_duration'
GROUP BY
metric_name
, timestamp
ORDER BY
metric_name
, timestamp
) to 'output.json' (ARRAY);
```
-->
import OutputSource from "./output.json";
import { BenchmarkChart } from '@/components/benchmark_chart';
TODO: describe the outcome of the test?
@@ -60,18 +33,11 @@ TODO: describe the outcome of the test?
| k6 output | |
| flowchart outcome | |
## Endpoint latencies
import OutputSource from "./output.json";
import { BenchmarkChart } from '/src/components/benchmark_chart';
<BenchmarkChart testResults={OutputSource} />
## k6 output {#k6-output}
## k6 output
```bash
TODO: add summary of k6
```
docs/docs/apis/benchmarks/index.mdx → apps/docs/content/apis/benchmarks/index.mdx
+5 -9
View File
@@ -3,7 +3,7 @@ title: Benchmarks
sidebar_label: Benchmarks
---
import DocCardList from '@theme/DocCardList';
import DocCardList from '@/components/docusaurus/doc-card-list';
Benchmarks are crucial to understand if ZITADEL fulfills your expected workload and what resources it needs to do so.
@@ -29,7 +29,6 @@ After each iteration of load-test, we should consult the [After test procedure](
2. Log potential issuer and scale
3. Terminate testing and resolve issues
## Methodology
### Benchmark definition
@@ -82,23 +81,20 @@ After each iteration of load-test, we should consult the [Flowchart](#after-test
2. [Log potential issue and scale](#potential-issues)
3. [Terminate testing](#termination) and resolve issues
#### Scale {#scale}
#### Scale
An outcome of scale means that the service hit some kind of resource limit, like CPU or RAM which can be increased. In such cases we increase the suggested parameter and rerun the load-test for the same target. On the next test we should analyze if the increase in scale resulted in a performance improvement proportional to the scale parameter. For example if we scale from 1 to 2 containers, it might be reasonable to expect a doubling of iterations / sec. If such an increase is not noticed, there might be another bottleneck or underlying issue, such as locking.
#### Potential issues {#potential-issues}
#### Potential issues
A potential issue has an impact on performance, but does not prevent us to scale. Such issues must be logged in GH issues and load-testing can continue. The issue can be resolved at a later time and the load-tests repeated when it is. This is primarily for issues which require big changes to ZITADEL.
#### Termination {#termination}
#### Termination
Scaling no longer improves iterations / second, or some kind of critical error or bug is experienced. The root cause of the issue must be resolved before we can continue with increasing scale.
### After test procedure
This flowchart shows the procedure after running a test.
![Flowchart](/img/benchmark/Flowchart.svg)
![](../../../public/img/benchmark/Flowchart.svg)
## Baseline
docs/docs/apis/benchmarks/v2.65.0/machine_jwt_profile_grant/index.mdx → apps/docs/content/apis/benchmarks/v2.65.0/machine_jwt_profile_grant/index.mdx
+4 -7
View File
@@ -3,6 +3,9 @@ title: machine jwt profile grant benchmark of zitadel v2.65.0
sidebar_label: machine jwt profile grant
---
import OutputSource from "./output.json";
import { BenchmarkChart } from '@/components/benchmark_chart';
Tests are halted after this test run because of too many [client read events](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/wait-event.clientread.html) on the database.
## Performance test results
@@ -32,14 +35,9 @@ Tests are halted after this test run because of too many [client read events](ht
## /token endpoint latencies
import OutputSource from "./output.json";
import { BenchmarkChart } from '/src/components/benchmark_chart';
<BenchmarkChart testResults={OutputSource} />
## k6 output {#k6-output}
## k6 output
```bash
checks...............................: 100.00% ✓ 695739 ✗ 0
data_received........................: 479 MB 265 kB/s
@@ -70,4 +68,3 @@ vus_max..............................: 50 min=50 max=50
running (30m04.9s), 00/50 VUs, 347788 complete and 0 interrupted iterations
default ✓ [======================================] 50 VUs 30m0s
```
docs/docs/apis/benchmarks/v2.65.0/machine_jwt_profile_grant/output.json → apps/docs/content/apis/benchmarks/v2.65.0/machine_jwt_profile_grant/output.json
View File
docs/docs/apis/benchmarks/v2.66.0/machine_jwt_profile_grant/index.mdx → apps/docs/content/apis/benchmarks/v2.66.0/machine_jwt_profile_grant/index.mdx
+4 -8
View File
@@ -3,6 +3,9 @@ title: machine jwt profile grant benchmark of zitadel v2.66.0
sidebar_label: machine jwt profile grant
---
import OutputSource from "./output.json";
import { BenchmarkChart } from '@/components/benchmark_chart';
The tests showed heavy database load by time by the first two database queries. These queries need to be analyzed further.
## Performance test results
@@ -33,14 +36,9 @@ The tests showed heavy database load by time by the first two database queries.
## Endpoint latencies
import OutputSource from "./output.json";
import { BenchmarkChart } from '/src/components/benchmark_chart';
<BenchmarkChart testResults={OutputSource} />
## k6 output {#k6-output}
## k6 output
```bash
✓ openid configuration
✗ token status ok
@@ -95,8 +93,6 @@ import { BenchmarkChart } from '/src/components/benchmark_chart';
vus..................................: 150 min=0 max=150
vus_max..............................: 150 min=150 max=150
running (30m09.6s), 000/150 VUs, 790660 complete and 0 interrupted iterations
default ✓ [======================================] 150 VUs 30m0s
```
docs/docs/apis/benchmarks/v2.66.0/machine_jwt_profile_grant/output.json → apps/docs/content/apis/benchmarks/v2.66.0/machine_jwt_profile_grant/output.json
View File
docs/docs/apis/benchmarks/v2.70.0/machine_jwt_profile_grant/index.mdx → apps/docs/content/apis/benchmarks/v2.70.0/machine_jwt_profile_grant/index.mdx
+4 -8
View File
@@ -3,6 +3,9 @@ title: machine jwt profile grant benchmark of zitadel v2.70.0
sidebar_label: machine jwt profile grant
---
import OutputSource from "./output.json";
import { BenchmarkChart } from '@/components/benchmark_chart';
The performance goals of [this issue](https://github.com/zitadel/zitadel/issues/8352) are reached. Next we will test linear scalability.
## Performance test results
@@ -33,14 +36,9 @@ The performance goals of [this issue](https://github.com/zitadel/zitadel/issues/
## Endpoint latencies
import OutputSource from "./output.json";
import { BenchmarkChart } from '/src/components/benchmark_chart';
<BenchmarkChart testResults={OutputSource} />
## k6 output {#k6-output}
## k6 output
```bash
✓ openid configuration
✗ token status ok
@@ -95,8 +93,6 @@ import { BenchmarkChart } from '/src/components/benchmark_chart';
vus..................................: 425 min=0 max=600
vus_max..............................: 600 min=600 max=600
running (30m21.3s), 000/600 VUs, 3289564 complete and 0 interrupted iterations
default ✓ [======================================] 600 VUs 30m0s
```
docs/docs/apis/benchmarks/v2.70.0/machine_jwt_profile_grant/output.json → apps/docs/content/apis/benchmarks/v2.70.0/machine_jwt_profile_grant/output.json
View File
docs/docs/apis/benchmarks/v2.70.0/oidc_session/index.mdx → apps/docs/content/apis/benchmarks/v2.70.0/oidc_session/index.mdx
+4 -7
View File
@@ -3,6 +3,9 @@ title: oidc session benchmark of Zitadel v2.70.0
sidebar_label: oidc session
---
import OutputSource from "./output.json";
import { BenchmarkChart } from '@/components/benchmark_chart';
The test implements [Support for (OIDC) Standard in a Custom Login UI flow](https://zitadel.com/docs/guides/integrate/login-ui/oidc-standard).
The tests showed that querying the user takes too much time because Zitadel ensures the projection is up to date. This performance bottleneck must be resolved.
@@ -35,14 +38,9 @@ The tests showed that querying the user takes too much time because Zitadel ensu
## Endpoint latencies
import OutputSource from "./output.json";
import { BenchmarkChart } from '/src/components/benchmark_chart';
<BenchmarkChart testResults={OutputSource} />
## k6 output {#k6-output}
## k6 output
```bash
✓ authorize status ok
✓ auth request id returned
@@ -103,7 +101,6 @@ import { BenchmarkChart } from '/src/components/benchmark_chart';
vus..................................: 82 min=0 max=600
vus_max..............................: 600 min=600 max=600
running (30m04.0s), 000/600 VUs, 274271 complete and 0 interrupted iterations
default ✓ [======================================] 600 VUs 30m0s
```
docs/docs/apis/benchmarks/v2.70.0/oidc_session/output.json → apps/docs/content/apis/benchmarks/v2.70.0/oidc_session/output.json
View File
docs/docs/apis/benchmarks/v4/add_session/index.mdx → apps/docs/content/apis/benchmarks/v4/add_session/index.mdx
+4 -7
View File
@@ -3,6 +3,9 @@ title: create session benchmark of zitadel v4
sidebar_label: create session
---
import OutputSource from "./output.json";
import { BenchmarkChart } from '@/components/benchmark_chart';
Benchmark results of v4 release of Zitadel.
## Performance test results
@@ -35,14 +38,9 @@ Benchmark results of v4 release of Zitadel.
Until :37 were containers starting because it was a cold start test.
import OutputSource from "./output.json";
import { BenchmarkChart } from '/src/components/benchmark_chart';
<BenchmarkChart testResults={OutputSource} />
## k6 output {#k6-output}
## k6 output
```bash
█ TOTAL RESULTS
@@ -97,4 +95,3 @@ import { BenchmarkChart } from '/src/components/benchmark_chart';
running (30m49.3s), 000/600 VUs, 1121977 complete and 0 interrupted iterations
default ✓ [======================================] 600 VUs 30m0s
```
docs/docs/apis/benchmarks/v4/add_session/output.json → apps/docs/content/apis/benchmarks/v4/add_session/output.json
View File
docs/docs/apis/benchmarks/v4/human_password_login/index.mdx → apps/docs/content/apis/benchmarks/v4/human_password_login/index.mdx
+4 -7
View File
@@ -3,6 +3,9 @@ title: human password login benchmark of zitadel v4
sidebar_label: human password login
---
import OutputSource from "./output.json";
import { BenchmarkChart } from '@/components/benchmark_chart';
Benchmark results of v4 release of Zitadel.
This benchmark tests the flow of a user signing in to Zitadel using username and password which is a highly CPU intensive task for checking the password.
@@ -37,14 +40,9 @@ This benchmark tests the flow of a user signing in to Zitadel using username and
Until :45 were containers starting because it was a cold start test.
import OutputSource from "./output.json";
import { BenchmarkChart } from '/src/components/benchmark_chart';
<BenchmarkChart testResults={OutputSource} />
## k6 output {#k6-output}
## k6 output
```bash
█ TOTAL RESULTS
@@ -104,4 +102,3 @@ import { BenchmarkChart } from '/src/components/benchmark_chart';
running (31m07.4s), 000/600 VUs, 72904 complete and 0 interrupted iterations
```
docs/docs/apis/benchmarks/v4/human_password_login/output.json → apps/docs/content/apis/benchmarks/v4/human_password_login/output.json
View File
docs/docs/apis/benchmarks/v4/introspect/index.mdx → apps/docs/content/apis/benchmarks/v4/introspect/index.mdx
+4 -7
View File
@@ -3,6 +3,9 @@ title: introspection benchmark of zitadel v4
sidebar_label: introspection
---
import OutputSource from "./output.json";
import { BenchmarkChart } from '@/components/benchmark_chart';
Benchmark results of v4 release of Zitadel.
## Performance test results
@@ -33,14 +36,9 @@ Benchmark results of v4 release of Zitadel.
## Endpoint latencies
import OutputSource from "./output.json";
import { BenchmarkChart } from '/src/components/benchmark_chart';
<BenchmarkChart testResults={OutputSource} />
## k6 output {#k6-output}
## k6 output
```bash
█ TOTAL RESULTS
@@ -98,4 +96,3 @@ import { BenchmarkChart } from '/src/components/benchmark_chart';
running (30m41.3s), 000/600 VUs, 33794 complete and 0 interrupted iterations
default ✓ [======================================] 600 VUs 30m0s
```
docs/docs/apis/benchmarks/v4/introspect/output.json → apps/docs/content/apis/benchmarks/v4/introspect/output.json
View File
docs/docs/apis/benchmarks/v4/machine_client_credentials_login/index.mdx → apps/docs/content/apis/benchmarks/v4/machine_client_credentials_login/index.mdx
+4 -7
View File
@@ -3,6 +3,9 @@ title: machine client credentials login benchmark of zitadel v4
sidebar_label: machine client credentials login
---
import OutputSource from "./output.json";
import { BenchmarkChart } from '@/components/benchmark_chart';
Benchmark results of v4 release of Zitadel.
## Performance test results
@@ -35,14 +38,9 @@ Benchmark results of v4 release of Zitadel.
Until :37 were containers starting because it was a cold start test.
import OutputSource from "./output.json";
import { BenchmarkChart } from '/src/components/benchmark_chart';
<BenchmarkChart testResults={OutputSource} />
## k6 output {#k6-output}
## k6 output
```bash
█ TOTAL RESULTS
@@ -103,4 +101,3 @@ import { BenchmarkChart } from '/src/components/benchmark_chart';
running (30m33.4s), 000/600 VUs, 778149 complete and 0 interrupted iterations
default ✓ [======================================] 600 VUs 30m0s
```
docs/docs/apis/benchmarks/v4/machine_client_credentials_login/output.json → apps/docs/content/apis/benchmarks/v4/machine_client_credentials_login/output.json
View File
docs/docs/apis/benchmarks/v4/machine_jwt_profile_grant/index.mdx → apps/docs/content/apis/benchmarks/v4/machine_jwt_profile_grant/index.mdx
+4 -7
View File
@@ -3,6 +3,9 @@ title: machine jwt profile grant benchmark of zitadel v4
sidebar_label: machine jwt profile grant
---
import OutputSource from "./output.json";
import { BenchmarkChart } from '@/components/benchmark_chart';
Benchmark results of v4 release of Zitadel.
## Performance test results
@@ -33,14 +36,9 @@ Benchmark results of v4 release of Zitadel.
## Endpoint latencies
import OutputSource from "./output.json";
import { BenchmarkChart } from '/src/components/benchmark_chart';
<BenchmarkChart testResults={OutputSource} />
## k6 output {#k6-output}
## k6 output
```bash
█ TOTAL RESULTS
@@ -95,4 +93,3 @@ import { BenchmarkChart } from '/src/components/benchmark_chart';
running (30m37.3s), 000/600 VUs, 1563113 complete and 0 interrupted iterations
default ✓ [======================================] 600 VUs 30m0s
```
docs/docs/apis/benchmarks/v4/machine_jwt_profile_grant/output.json → apps/docs/content/apis/benchmarks/v4/machine_jwt_profile_grant/output.json
View File
docs/docs/apis/benchmarks/v4/machine_pat_login/index.mdx → apps/docs/content/apis/benchmarks/v4/machine_pat_login/index.mdx
+4 -7
View File
@@ -3,6 +3,9 @@ title: machine pat login benchmark of zitadel v4
sidebar_label: machine pat login
---
import OutputSource from "./output.json";
import { BenchmarkChart } from '@/components/benchmark_chart';
Benchmark results of v4 release of Zitadel.
## Performance test results
@@ -35,14 +38,9 @@ Benchmark results of v4 release of Zitadel.
Until :37 were containers starting because it was a cold start test.
import OutputSource from "./output.json";
import { BenchmarkChart } from '/src/components/benchmark_chart';
<BenchmarkChart testResults={OutputSource} />
## k6 output {#k6-output}
## k6 output
```bash
█ TOTAL RESULTS
@@ -102,4 +100,3 @@ import { BenchmarkChart } from '/src/components/benchmark_chart';
running (31m07.4s), 000/600 VUs, 72904 complete and 0 interrupted iterations
```
docs/docs/apis/benchmarks/v4/machine_pat_login/output.json → apps/docs/content/apis/benchmarks/v4/machine_pat_login/output.json
View File
docs/docs/apis/benchmarks/v4/manipulate_user/index.mdx → apps/docs/content/apis/benchmarks/v4/manipulate_user/index.mdx
+4 -7
View File
@@ -3,6 +3,9 @@ title: manipulate user benchmark of zitadel v4
sidebar_label: manipulate user
---
import OutputSource from "./output.json";
import { BenchmarkChart } from '@/components/benchmark_chart';
Benchmark results of v4 release of Zitadel.
## Performance test results
@@ -35,14 +38,9 @@ Benchmark results of v4 release of Zitadel.
Each iteration creates, updates and deletes a user.
import OutputSource from "./output.json";
import { BenchmarkChart } from '/src/components/benchmark_chart';
<BenchmarkChart testResults={OutputSource} />
## k6 output {#k6-output}
## k6 output
```bash
█ TOTAL RESULTS
@@ -102,4 +100,3 @@ import { BenchmarkChart } from '/src/components/benchmark_chart';
running (30m32.1s), 000/600 VUs, 28434 complete and 98 interrupted iterations
default ✓ [======================================] 600 VUs 30m0s
```
docs/docs/apis/benchmarks/v4/manipulate_user/output.json → apps/docs/content/apis/benchmarks/v4/manipulate_user/output.json
View File
docs/docs/apis/benchmarks/v4/oidc_session/index.mdx → apps/docs/content/apis/benchmarks/v4/oidc_session/index.mdx
+4 -7
View File
@@ -3,6 +3,9 @@ title: oidc session benchmark of zitadel v4
sidebar_label: oidc session
---
import OutputSource from "./output.json";
import { BenchmarkChart } from '@/components/benchmark_chart';
Benchmark results of v4 release of Zitadel.
## Performance test results
@@ -33,14 +36,9 @@ Benchmark results of v4 release of Zitadel.
## Endpoint latencies
import OutputSource from "./output.json";
import { BenchmarkChart } from '/src/components/benchmark_chart';
<BenchmarkChart testResults={OutputSource} />
## k6 output {#k6-output}
## k6 output
```bash
█ TOTAL RESULTS
@@ -104,4 +102,3 @@ import { BenchmarkChart } from '/src/components/benchmark_chart';
running (42m06.8s), 000/600 VUs, 265104 complete and 600 interrupted iterations
default ✓ [======================================] 600 VUs 30m0s
```
docs/docs/apis/benchmarks/v4/oidc_session/output.json → apps/docs/content/apis/benchmarks/v4/oidc_session/output.json
View File
docs/docs/apis/benchmarks/v4/otp_session/index.mdx → apps/docs/content/apis/benchmarks/v4/otp_session/index.mdx
+4 -7
View File
@@ -3,6 +3,9 @@ title: otp session benchmark of zitadel v4
sidebar_label: otp session
---
import OutputSource from "./output.json";
import { BenchmarkChart } from '@/components/benchmark_chart';
Benchmark results of v4 release of Zitadel.
## Performance test results
@@ -33,14 +36,9 @@ Benchmark results of v4 release of Zitadel.
## Endpoint latencies
import OutputSource from "./output.json";
import { BenchmarkChart } from '/src/components/benchmark_chart';
<BenchmarkChart testResults={OutputSource} />
## k6 output {#k6-output}
## k6 output
```bash
█ TOTAL RESULTS
@@ -98,4 +96,3 @@ import { BenchmarkChart } from '/src/components/benchmark_chart';
running (30m58.0s), 000/600 VUs, 112282 complete and 0 interrupted iterations
default ✓ [======================================] 600 VUs 30m0s
```
docs/docs/apis/benchmarks/v4/otp_session/output.json → apps/docs/content/apis/benchmarks/v4/otp_session/output.json
View File
docs/docs/apis/benchmarks/v4/password_session/index.mdx → apps/docs/content/apis/benchmarks/v4/password_session/index.mdx
+4 -7
View File
@@ -3,6 +3,9 @@ title: session with password benchmark of zitadel v4
sidebar_label: password session
---
import OutputSource from "./output.json";
import { BenchmarkChart } from '@/components/benchmark_chart';
Benchmark results of v4 release of Zitadel.
## Performance test results
@@ -33,14 +36,9 @@ Benchmark results of v4 release of Zitadel.
## Endpoint latencies
import OutputSource from "./output.json";
import { BenchmarkChart } from '/src/components/benchmark_chart';
<BenchmarkChart testResults={OutputSource} />
## k6 output {#k6-output}
## k6 output
```bash
█ TOTAL RESULTS
@@ -99,4 +97,3 @@ import { BenchmarkChart } from '/src/components/benchmark_chart';
running (31m03.7s), 000/600 VUs, 94143 complete and 0 interrupted iterations
default ✓ [======================================] 600 VUs 30m0s
```
docs/docs/apis/benchmarks/v4/password_session/output.json → apps/docs/content/apis/benchmarks/v4/password_session/output.json
View File
docs/docs/apis/benchmarks/v4/user_info/index.mdx → apps/docs/content/apis/benchmarks/v4/user_info/index.mdx
+4 -7
View File
@@ -3,6 +3,9 @@ title: user info benchmark of zitadel v4
sidebar_label: user info
---
import OutputSource from "./output.json";
import { BenchmarkChart } from '@/components/benchmark_chart';
Benchmark results of v4 release of Zitadel.
## Performance test results
@@ -33,14 +36,9 @@ Benchmark results of v4 release of Zitadel.
## Endpoint latencies
import OutputSource from "./output.json";
import { BenchmarkChart } from '/src/components/benchmark_chart';
<BenchmarkChart testResults={OutputSource} />
## k6 output {#k6-output}
## k6 output
```bash
█ TOTAL RESULTS
@@ -96,4 +94,3 @@ import { BenchmarkChart } from '/src/components/benchmark_chart';
running (30m03.3s), 000/600 VUs, 4783719 complete and 0 interrupted iterations
default ✓ [======================================] 600 VUs 30m0s
```
docs/docs/apis/benchmarks/v4/user_info/output.json → apps/docs/content/apis/benchmarks/v4/user_info/output.json
View File
docs/docs/apis/introduction.mdx → apps/docs/content/apis/introduction.mdx
+40 -40
View File
@@ -3,75 +3,75 @@ title: ZITADEL API Reference Overview
sidebar_label: Overview
---
import { ApiCard } from "../../src/components/apicard";
import Column from "../../src/components/column";
import { ApiCard } from "@/components/apicard";
import Column from "@/components/column";
ZITADEL exposes all features via different gRPC and REST APIs and provides SDKs for popular languages and frameworks.
The [OpenID Connect & OAuth endpoints](/docs/apis/openidoauth/endpoints) and [SAML 2.0 endpoints](/docs/apis/saml/endpoints) are implemented and exposed according to the specific standards. Managing resources such as users, organizations, instances, or settings must be done with the different [ZITADEL APIs](#zitadel-apis-resource-based).
The [OpenID Connect & OAuth endpoints](/apis/openidoauth/endpoints) and [SAML 2.0 endpoints](/apis/saml/endpoints) are implemented and exposed according to the specific standards. Managing resources such as users, organizations, instances, or settings must be done with the different [ZITADEL APIs](#zitadel-apis-resource-based).
[Actions](/docs/guides/manage/console/actions-overview) allow to extend ZITADEL with custom code to change default behaviors or calling external systems.
[Actions](/guides/manage/console/actions-overview) allow to extend ZITADEL with custom code to change default behaviors or calling external systems.
## Authentication & authorization
### Authentication for human users (interactive)
ZITADEL implements industry standards such as OpenID Connect, OAuth 2.0, or SAML for authentication.
Please refer to our guides how to [authenticate users](/docs/guides/integrate/login/login-users) through an interactive authentication process.
Please refer to our guides how to [authenticate users](/guides/integrate/login/login-users) through an interactive authentication process.
For user authentication on devices with limited accessibility (eg, SmartTV, Smart Watch etc.) use the [device authorization grant](/docs/guides/integrate/login/oidc/device-authorization).
For user authentication on devices with limited accessibility (eg, SmartTV, Smart Watch etc.) use the [device authorization grant](/guides/integrate/login/oidc/device-authorization).
Additionally, you can use the [session API](../apis/resources/session_service_v2/) to authenticate users, for example by building a [custom login UI](/docs/guides/integrate/login-ui/).
Additionally, you can use the [session API](/reference/api/session) to authenticate users, for example by building a [custom login UI](/guides/integrate/login-ui).
### Authenticate service users and machines
Service users allow for machine-to-machine (M2M) communication.
Follow the guides to learn how to [authenticate service users](/docs/guides/integrate/service-users/authenticate-service-users).
Follow the guides to learn how to [authenticate service users](/guides/integrate/service-users/authenticate-service-users).
Accessing the ZITADEL APIs through a service user might require additional steps, please follow the guide on how to [access ZITADEL APIs](../guides/integrate/zitadel-apis/access-zitadel-apis) to include the correct audience scope in your requests.
### OpenID Connect & OAuth
- [OpenID Connect endpoints](/docs/apis/openidoauth/endpoints) definition
- Standard and reserved [scopes reference](/docs/apis/openidoauth/scopes)
- Standard, custom, and reserved [claims reference](/docs/apis/openidoauth/claims)
- [OpenID Connect endpoints](/apis/openidoauth/endpoints) definition
- Standard and reserved [scopes reference](/apis/openidoauth/scopes)
- Standard, custom, and reserved [claims reference](/apis/openidoauth/claims)
The [OIDC Playground](https://zitadel.com/playgrounds/oidc) is for testing OpenID authentication requests and their parameters.
### SAML 2.0
- [SAML 2.0 endpoints](/docs/apis/saml/endpoints) definition
- [SAML 2.0 endpoints](/apis/saml/endpoints) definition
- [Custom attributes](https://github.com/zitadel/actions/blob/main/examples/set_custom_attribute.js) can be added with an action
### Custom
ZITADEL allows to authenticate users by creating a session with the [Session API](/docs/apis/resources/session_service_v2), get OIDC authentication request details with the [OIDC service API](/docs/apis/resources/oidc_service_v2) or get SAML request details with the [SAML service API](/docs/apis/resources/saml_service_v2).
User authorizations can be [retrieved as roles from our APIs](/docs/guides/integrate/retrieve-user-roles).
ZITADEL allows to authenticate users by creating a session with the [Session API](/reference/api/session), get OIDC authentication request details with the [OIDC service API](/reference/api/oidc) or get SAML request details with the [SAML service API](/reference/api/saml).
User authorizations can be [retrieved as roles from our APIs](/guides/integrate/retrieve-user-roles).
Refer to our guide to learn how to [build your own login UI](/docs/guides/integrate/login-ui)
Refer to our guide to learn how to [build your own login UI](/guides/integrate/login-ui)
## ZITADEL APIs (resource-based)
ZITADEL provides APIs for each [core resource](/docs/apis/v2):
ZITADEL provides APIs for each [core resource](/apis/v2):
- [User](/docs/apis/resources/user_service_v2)
- [Session](/docs/apis/resources/session_service_v2)
- [Settings](/docs/apis/resources/settings_service_v2)
- [User](/reference/api/user)
- [Session](/reference/api/session)
- [Settings](/reference/api/settings)
:::info
<Callout>
We are migrating to a resource-based API approach.
You might need to use the existing [service-based](#zitadel-apis-service-based) APIs for now to manage Organizations, Instances, Assets etc.
:::
</Callout>
## ZITADEL APIs (service-based)
:::info Prefer resource-based API
<Callout title="Prefer resource-based API">
ZITADEL APIs were organized by UseCase/Context, such as Auth API for authenticated users and Management API for organization managers.
This led to confusion about which API to use, particularly for requests that could be useful across multiple APIs but with different filters.
For instance, SearchUsers on an Instance Level or on an Organization Level.
To address this issue, ZITADEL is migrating to a [resource-based API](#zitadel-apis-resource-based).
:::
</Callout>
<ApiCard title="Authentication" type="AUTH">
<Column>
@@ -84,7 +84,7 @@ The authentication API (aka Auth API) is used for all operations on the currentl
</div>
<div className="apicard-right">
#### GRPC
#### Auth GRPC
Endpoint:
`${CUSTOM_DOMAIN}/zitadel.auth.v1.AuthService/`
@@ -92,13 +92,13 @@ Endpoint:
Definition:
[Auth Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/auth.proto)
#### REST
#### Auth REST
Endpoint:
`${CUSTOM_DOMAIN}/auth/v1/`
API Reference:
[OpenAPI Docs](/apis/resources/auth)
[OpenAPI Docs](/reference/api/auth)
</div>
</Column>
@@ -117,7 +117,7 @@ To identify the current organization you can send a header `x-zitadel-orgid` or
</div>
<div className="apicard-right">
#### GRPC
#### Mgmt GRPC
Endpoint:
`${CUSTOM_DOMAIN}/zitadel.management.v1.ManagementService/`
@@ -125,13 +125,13 @@ Endpoint:
Definition:
[Management Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/management.proto)
#### REST
#### Mgmt REST
Endpoint:
`${CUSTOM_DOMAIN}/management/v1/`
API Reference:
[OpenAPI Docs](/apis/resources/mgmt)
[OpenAPI Docs](/reference/api/management)
</div>
</Column>
@@ -148,7 +148,7 @@ This API is intended to configure and manage one ZITADEL instance itself.
</div>
<div className="apicard-right">
#### GRPC
#### Admin GRPC
Endpoint:
`${CUSTOM_DOMAIN}/zitadel.admin.v1.AdminService/`
@@ -156,13 +156,13 @@ Endpoint:
Definition:
[Admin Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/admin.proto)
#### REST
#### Admin REST
Endpoint:
`${CUSTOM_DOMAIN}/admin/v1/`
API Reference:
[OpenAPI Docs](/apis/resources/admin)
[OpenAPI Docs](/reference/api/admin)
</div>
</Column>
@@ -176,12 +176,12 @@ API Reference:
This API is intended to manage the different ZITADEL instances within the system.
Checkout the guide how to [access the ZITADEL System API](/docs/guides/integrate/zitadel-apis/access-zitadel-system-api).
Checkout the guide how to [access the ZITADEL System API](/guides/integrate/zitadel-apis/access-zitadel-system-api).
</div>
<div className="apicard-right">
#### GRPC
#### System GRPC
Endpoint:
`${CUSTOM_DOMAIN}/zitadel.system.v1.SystemService/`
@@ -189,13 +189,13 @@ Endpoint:
Definition:
[System Proto](https://github.com/zitadel/zitadel/blob/main/proto/zitadel/system.proto)
#### REST
#### System REST
Endpoint:
`${CUSTOM_DOMAIN}/system/v1/`
API Reference:
[OpenAPI Docs](/apis/resources/system)
[OpenAPI Docs](/reference/api/system)
</div>
</Column>
@@ -212,13 +212,13 @@ The Assets API allows you to up- and download all kinds of assets. This can be f
</div>
<div>
#### REST
#### Assets REST
Endpoint:
`${CUSTOM_DOMAIN}/assets/v1/`
Definition:
[Assets](./assets/assets.md)
[Assets](./assets/assets)
</div>
</Column>
@@ -233,7 +233,7 @@ The last API (assets) is only a REST API because ZITADEL uses multipart form dat
### SDKs
ZITADEL provides some [official and community supported SDKs](/docs/sdk-examples/introduction) for multiple languages and frameworks.
ZITADEL provides some [official and community supported SDKs](/sdk-examples/introduction) for multiple languages and frameworks.
Most languages allow you to build a client from proto definitions, which allows you to build your own client in case an SDK is missing.
### Proto
@@ -274,7 +274,7 @@ ZITADEL hosts everything under a single domain: `{instance}.zitadel.cloud` or yo
The domain is used as the OIDC issuer and as the base url for the gRPC and REST APIs, the Login and Management Console UI, which you'll find under `${CUSTOM_DOMAIN}/ui/console/`.
Are you self-hosting and having troubles with _Instance not found_ errors? [Check out this page](/docs/self-hosting/manage/custom-domain).
Are you self-hosting and having troubles with _Instance not found_ errors? [Check out this page](/self-hosting/manage/custom-domain).
## API path prefixes
docs/docs/apis/migration_v1_to_v2.mdx → apps/docs/content/apis/migration_v1_to_v2.mdx
+1 -1
View File
@@ -110,7 +110,7 @@ When migrating your user management from v1 to v2, the most significant updates
- You can choose at user creation whether an email verification code should be sent automatically.
- Alternatively, the API can return the verification code directly to you, empowering you to send a customized verification email.
[Users API v2 Documentation](/docs/apis/resources/user_service_v2)
[Users API v2 Documentation](/reference/api/user)
### Projects
docs/docs/apis/observability/health.md → apps/docs/content/apis/observability/health.mdx
+4 -4
View File
@@ -10,15 +10,15 @@ ZITADEL exposes a `Ready`- and `Healthy` endpoint to allow external systems like
The `Ready` endpoint is located on the path `/debug/ready` and allows systems to probe if a ZITADEL process is ready to serve and accept traffic.
This endpoint is useful for operations like [zero downtime upgrade](../../concepts/architecture/solution#zero-downtime-updates) since it allows systems like Kubernetes to verify that ZITADEL is working on something (e.g. database schema migration) but is not yet ready to accept traffic.
:::info
<Callout>
In Kubernetes this is called the `readinessProbe`.
:::
</Callout>
## Healthy
The `Health` endpoint is located on the path `/debug/healthz` and allows systems to probe if a ZITADEL process is still alive.
This helps system like kubernetes or a load balancer to observe if the process is still alive to accept traffic.
:::info
<Callout>
In Kubernetes this is called the `livenessProbe`.
:::
</Callout>
docs/docs/apis/observability/metrics.md → apps/docs/content/apis/observability/metrics.mdx
+2 -2
View File
@@ -9,7 +9,7 @@ If you are self-hosting ZITADEL, you can access this endpoint with on the path `
For example when running ZITADEL locally the endpoint is accessible on `http://localhost:8080/debug/metrics`.
The metrics endpoint can be scrubbed by any tool of choice that supports the `otel` format, e.g an existing Prometheus.
For our [Kubernetes/Helm](/docs/self-hosting/deploy/kubernetes) users, we provide an out of the box support for the [ServiceMonitor](https://github.com/zitadel/zitadel-charts/blob/main/charts/zitadel/templates/servicemonitor.yaml) custom resource.
For our [Kubernetes/Helm](/self-hosting/deploy/kubernetes) users, we provide an out of the box support for the [ServiceMonitor](https://github.com/zitadel/zitadel-charts/blob/main/charts/zitadel/templates/servicemonitor.yaml) custom resource.
By default, metrics are enabled but can be turned off through ZITADEL's [configuration](/docs/self-hosting/manage/configure).
By default, metrics are enabled but can be turned off through ZITADEL's [configuration](/self-hosting/manage/configure).
The (default) configuration is located in the [defaults.yaml](https://github.com/zitadel/zitadel/blob/main/cmd/defaults.yaml).
docs/docs/apis/openidoauth/_token_exchange_request.mdx → apps/docs/content/apis/openidoauth/_token_exchange_request.mdx
+1 -1
View File
@@ -6,6 +6,6 @@
| actor_token | Optional. A token that represents the identity of the acting party. In ZITADEL this the impersonator. |
| actor_token_type | An identifier that indicates the type of the token in the actor_token parameter. Required when actor_token is provided |
| requested_token_type | Optional. An identifier that indicates the type of the token requested. Defaults to access token if not provided. |
| scope | [Scopes](/docs/apis/openidoauth/scopes) you would like to request from ZITADEL for the requested token. Scopes are space delimited, e.g. `openid email profile`. |
| scope | [Scopes](/apis/openidoauth/scopes) you would like to request from ZITADEL for the requested token. Scopes are space delimited, e.g. `openid email profile`. |
| audience | Optional. Must be a subset of the combined audiences from both subject and actor tokens. |
| resource | Currently not supported |
docs/docs/apis/openidoauth/_token_exchange_response.mdx → apps/docs/content/apis/openidoauth/_token_exchange_response.mdx
View File
docs/docs/apis/openidoauth/_token_exchange_types.mdx → apps/docs/content/apis/openidoauth/_token_exchange_types.mdx
View File
docs/docs/apis/openidoauth/authn-methods.md → apps/docs/content/apis/openidoauth/authn-methods.mdx
+2 -2
View File
@@ -30,7 +30,7 @@ Key JSON
| clientId | `78366401571920522@acme` | The client_id of the application, this is the same as the subject from tokens |
| appId | `78366403256846242` | The id of the application (just for completeness, not used for JWT) |
```JSON
```json
{
"type": "application",
"keyId": "81693565968962154",
@@ -52,7 +52,7 @@ JWT
| iss | `"78366401571920522@acme"` | String which represents the requesting party (owner of the key), normally the `clientID` from the json key file |
| sub | `"78366401571920522@acme"` | The subject ID of the application, normally the `clientID` from the json key file |
```JSON
```json
{
"iss": "78366401571920522@acme",
"sub": "78366401571920522@acme",
docs/docs/apis/openidoauth/authrequest.mdx → apps/docs/content/apis/openidoauth/authrequest.mdx
+7 -5
View File
@@ -3,13 +3,15 @@ title: ZITADEL OIDC Authentication Request Playground
sidebar_label: OIDC Playground
---
import { SetAuthRequest } from "../../../src/components/authrequest";
import { ExternalLink } from "lucide-react";
The OIDC Playground is for testing OpenID Authentication Requests, giving you more insight how OpenID Connect works and how you can customize ZITADEL behavior with different parameters.
An OpenID Connect (OIDC) [authentication request](https://openid.net/specs/openid-connect-core-1_0.html) is an OAuth 2.0 Authorization Request using additional parameters and scopes to request that the end-user be authenticated by ZITADEL.
<SetAuthRequest />
<a href="https://zitadel.com/playgrounds/oidc" target="_blank" className="flex items-center gap-2 text-primary hover:underline">
Go to the OIDC Playground <ExternalLink className="h-4 w-4" />
</a>
## Why this OIDC playground?
@@ -20,7 +22,7 @@ This playground should help you to initially craft an authentication request and
## Request parameters explained
Not all request parameters are available in the playground. Please refer to the full documentation of the [authorization endpoint](/apis/openidoauth/endpoints#authorization_endpoint).
Not all request parameters are available in the playground. Please refer to the full documentation of the [authorization endpoint](/apis/openidoauth/endpoints#authorization-endpoint).
### Your Domain
@@ -57,7 +59,7 @@ Depending on the authentication and authorization flow of your application you m
for most application types. The playground appends automatically a code challenge
for PKCE flows.
You need to append a "Code Challenge" by providing a random <span className="text-teal-600">Code Verifier</span> that is being hashed and encoded in the request to the token endpoint, please see our [guide](/guides/integrate/login/oidc/login-users#token-request) for more details.
You need to append a "Code Challenge" by providing a random <span className="text-teal-600">Code Verifier</span> that is being hashed and encoded in the request to the token endpoint, please see our [guide](/guides/integrate/login/oidc/oauth-recommended-flows#our-recommended-authorization-flows) for more details.
More in the [documentation](/apis/openidoauth/authn-methods) about authentication methods.
@@ -125,4 +127,4 @@ This can be achieved by adding the scope `urn:zitadel:iam:org:project:id:zitadel
Please refer to our [guide](/guides/integrate/login/oidc/login-users) on how to login users.
OpenID Connect certified libraries should allow you to customize the parameters and define scopes for the authorization request. You can also continue by using one of our [example applications](/docs/sdk-examples/introduction).
OpenID Connect certified libraries should allow you to customize the parameters and define scopes for the authorization request. You can also continue by using one of our [example applications](/sdk-examples/introduction).
docs/docs/apis/openidoauth/claims.md → apps/docs/content/apis/openidoauth/claims.mdx
+5 -3
View File
@@ -47,7 +47,7 @@ Please check below the matrix for an overview where which scope is asserted.
| Claims | Example | Description |
|:-------------------|:---------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| acr | TBA | TBA |
| act | `{"iss": "${CUSTOM_DOMAIN}","sub": "259241944654282754"}` | JSON object describing the actor from the `actor_token` after [token exchange](/docs/guides/integrate/token-exchange#actor-token) |
| 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 |
@@ -58,8 +58,10 @@ Please check below the matrix for an overview where which scope is asserted.
| 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 |
@@ -78,7 +80,7 @@ Please check below the matrix for an overview where which scope is asserted.
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](/docs/apis/actions/complement-token) of the [actions feature](/docs/guides/manage/console/actions-overview).
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).
@@ -102,7 +104,7 @@ 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).
ZITADEL reserves some claims to assert certain data. Please check out the [reserved scopes](./scopes#reserved-scopes).
| Claims | Example | Description |
|:--------------------------------------------------|:---------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
docs/docs/apis/openidoauth/endpoints.mdx → apps/docs/content/apis/openidoauth/endpoints.mdx
+102 -113
View File
@@ -3,8 +3,6 @@ title: OpenID Connect Endpoints in ZITADEL
sidebar_label: OpenID Connect Endpoints
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import TokenExchangeRequest from "./_token_exchange_request.mdx";
import TokenExchangeResponse from "./_token_exchange_response.mdx";
import TokenExchangeTypes from "./_token_exchange_types.mdx";
@@ -20,9 +18,9 @@ This would give us `${CUSTOM_DOMAIN}/.well-known/openid-configuration`.
`${CUSTOM_DOMAIN}/oauth/v2/authorize`
:::note
<Callout>
The authorization_endpoint is located with the login page, due to the need of accessing the same cookie domain
:::
</Callout>
The authorization_endpoint is the starting point for all initial user authentications. The user agent (browser) will be redirected to this endpoint to
authenticate the user in exchange for an authorization_code (authorization code flow) or tokens (implicit flow).
@@ -50,15 +48,15 @@ authenticate the user in exchange for an authorization_code (authorization code
| client_id | The id of your client as shown in Console. |
| redirect_uri | Callback uri of the authorization request where the code or tokens will be sent to. Must match exactly one of the preregistered in Console. |
| response_type | Determines whether a `code`, `id_token token` or just `id_token` will be returned. Most use cases will need `code`. See flow guide for more info. |
| scope | `openid` is required, see [Scopes](scopes) for more possible values. Scopes are space delimited, e.g. `openid email profile` |
| scope | `openid` is required, see [Scopes](./scopes) for more possible values. Scopes are space delimited, e.g. `openid email profile` |
:::important
<Callout>
Following the [OIDC Core 1.0 specs](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) whenever an access_token is issued,
the id_token will not contain any claims of the scopes `profile`, `email`, `phone` and `address`.
Send the access_token to the [userinfo_endpoint](#userinfo_endpoint) or [introspection_endpoint](#introspection_endpoint) the retrieve these claims
Send the access_token to the [userinfo_endpoint](#userinfo-endpoint) or [introspection_endpoint](#introspection-endpoint) the retrieve these claims
or set the `id_token_userinfo_assertion` Option ("User Info inside ID Token" in Management Console) to true.
:::
</Callout>
Depending on your authorization method you will have to provide additional parameters or headers:
@@ -72,13 +70,13 @@ Depending on your authorization method you will have to provide additional param
{label: 'private_key_jwt', value: 'private_key_jwt'},
]}
>
<TabItem value="client_secret_basic">
<Tab value="client_secret_basic">
no additional parameters required
</TabItem>
<TabItem value="client_secret_post">
</Tab>
<Tab value="client_secret_post">
no additional parameters required
</TabItem>
<TabItem value="none">
</Tab>
<Tab value="none">
| Parameter | Description |
| --------------------- | ----------------------------------------------------- |
@@ -87,10 +85,10 @@ no additional parameters required
see PKCE guide for more information
</TabItem>
<TabItem value="private_key_jwt">
</Tab>
<Tab value="private_key_jwt">
no additional parameters required
</TabItem>
</Tab>
</Tabs>
### Additional parameters
@@ -108,6 +106,7 @@ no additional parameters required
#### Response modes
ZITADEL supports the following `response_mode` values. When no response mode is requested, the response mode is chosen based on the configured Response Type of the application.
ZITADEL supports the following `response_mode` values. When no response mode is requested, the response mode is chosen based on the configured Response Type of the application.
As per [OpenID Connect Core 1.0, Section 3.1.2.1](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest):
@@ -115,8 +114,8 @@ As per [OpenID Connect Core 1.0, Section 3.1.2.1](https://openid.net/specs/openi
| Response Mode | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| query | Encode the returned parameters in the URL query string. This is the default when the Response type is `code`, for example [Web applications](/docs/guides/manage/console/applications-overview#web). |
| fragment | Encode the returned parameters in the URL fragment. This is the default when the Response Type is `id_token`, for example implicit [User Agent apps](/docs/guides/manage/console/applications-overview#user-agent). This mode will not work for server-side applications, because fragments are never sent by the browser to the server. |
| query | Encode the returned parameters in the URL query string. This is the default when the Response type is `code`, for example [Web applications](/guides/manage/console/applications-overview#web). |
| fragment | Encode the returned parameters in the URL fragment. This is the default when the Response Type is `id_token`, for example implicit [User Agent apps](/guides/manage/console/applications-overview#user-agent). This mode will not work for server-side applications, because fragments are never sent by the browser to the server. |
| form_post[^1] | ZITADEL serves a small JavaScript to the browser which will send the returned parameters to the `redirect_uri` using HTTP POST. This mode only works for server-side applications and user agents which support / allow JavaScript. |
[^1]: Implements [OAuth 2.0 Form Post Response Mode](https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html)
@@ -147,10 +146,10 @@ When your `response_type` was either `id_token` or `id_token token` and no error
Regardless of the authorization flow chosen, if an error occurs the following response will be returned to the redirect_uri.
:::note
<Callout>
If the redirect_uri is not provided, was not registered or anything other prevents the auth server form returning the response to the client,
the error will be display directly to the user on the auth server
:::
</Callout>
| Property | Description |
| ----------------- | -------------------------------------------------------------------- |
@@ -158,8 +157,7 @@ the error will be display directly to the user on the auth server
| error_description | Description of the error type or additional information of the error |
| state | Unmodified `state` parameter from the request |
#### Possible errors {#authorize-errors}
#### Possible errors
| error_type | Possible reason |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| invalid_request | The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. |
@@ -202,12 +200,12 @@ Depending on your authorization method you will have to provide additional param
{label: 'private_key_jwt', value: 'private_key_jwt'},
]}
>
<TabItem value="client_secret_basic">
<Tab value="client_secret_basic">
Send your `client_id` and `client_secret` as Basic Auth Header. Check [Client Secret Basic Auth Method](authn-methods#client-secret-basic) on how to build it correctly.
Send your `client_id` and `client_secret` as Basic Auth Header. Check [Client Secret Basic Auth Method](./authn-methods#client-secret-basic) on how to build it correctly.
</TabItem>
<TabItem value="client_secret_post">
</Tab>
<Tab value="client_secret_post">
Send your `client_id` and `client_secret` as parameters in the body:
@@ -216,8 +214,8 @@ Send your `client_id` and `client_secret` as parameters in the body:
| client_id | client_id of the application |
| client_secret | client_secret of the application |
</TabItem>
<TabItem value="none">
</Tab>
<Tab value="none">
Send your `client_id` and `code_verifier` for us to recompute the `code_challenge` of the authorization request.
@@ -226,21 +224,20 @@ Send your `client_id` and `code_verifier` for us to recompute the `code_challeng
| client_id | client_id of the application |
| code_verifier | code_verifier previously used to generate the code_challenge |
</TabItem>
<TabItem value="private_key_jwt">
</Tab>
<Tab value="private_key_jwt">
Send a client assertion as JWT for us to validate the signature against the registered public key.
| Parameter | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| client_assertion | JWT built and signed according to [Using JWTs for Client Authentication](authn-methods#jwt-with-private-key) |
| client_assertion | JWT built and signed according to [Using JWTs for Client Authentication](./authn-methods#jwt-with-private-key) |
| client_assertion_type | Must be `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` |
</TabItem>
</Tab>
</Tabs>
#### Successful code response {#token-code-response}
#### Successful code response
| Property | Description |
| ------------- | ------------------------------------------------------------------------------------- |
| access_token | An `access_token` as JWT or opaque token |
@@ -257,10 +254,10 @@ Send a client assertion as JWT for us to validate the signature against the regi
| Parameter | Description |
| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| grant_type | Must be `urn:ietf:params:oauth:grant-type:jwt-bearer` |
| assertion | JWT built and signed according to [Using JWTs for Authorization Grants](grant-types#using-jwts-as-authorization-grants) |
| scope | [Scopes](scopes) you would like to request from ZITADEL. Scopes are space delimited, e.g. `openid email profile` |
| assertion | JWT built and signed according to [Using JWTs for Authorization Grants](./grant-types#using-jw-ts-as-authorization-grants) |
| scope | [Scopes](./scopes) you would like to request from ZITADEL. Scopes are space delimited, e.g. `openid email profile` |
```BASH
```bash
curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
@@ -268,8 +265,7 @@ curl --request POST \
--data assertion=eyJhbGciOiJSUzI1Ni...
```
#### Successful JWT profile response {#token-jwt-response}
#### Successful JWT profile response
| Property | Description |
| ------------ | ------------------------------------------------------------------------------------- |
| access_token | An `access_token` as JWT or opaque token |
@@ -281,7 +277,7 @@ curl --request POST \
### Refresh token grant
To request a new `access_token` without user interaction, you can use the `refresh_token` grant.
See [offline_access Scope](scopes#standard-scopes) for how to request a `refresh_token` in the authorization request.
See [offline_access Scope](./scopes#standard-scopes) for how to request a `refresh_token` in the authorization request.
#### Required request parameters
@@ -289,7 +285,7 @@ See [offline_access Scope](scopes#standard-scopes) for how to request a `refresh
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| grant_type | Must be `refresh_token` |
| refresh_token | The refresh_token previously issued in the last authorization_code or refresh_token request. |
| scope | [Scopes](scopes) you would like to request from ZITADEL for the new access_token. Must be a subset of the scope originally requested by the corresponding auth request. When omitted, the scopes requested by the original auth request will be reused. Scopes are space delimited, e.g. `openid email profile` |
| scope | [Scopes](./scopes) you would like to request from ZITADEL for the new access_token. Must be a subset of the scope originally requested by the corresponding auth request. When omitted, the scopes requested by the original auth request will be reused. Scopes are space delimited, e.g. `openid email profile` |
Depending on your authorization method you will have to provide additional parameters or headers:
@@ -303,12 +299,12 @@ Depending on your authorization method you will have to provide additional param
{label: 'private_key_jwt', value: 'private_key_jwt'},
]}
>
<TabItem value="client_secret_basic">
<Tab value="client_secret_basic">
Send your `client_id` and `client_secret` as Basic Auth Header. Check [Client Secret Basic Auth Method](authn-methods#client-secret-basic) on how to build it correctly.
Send your `client_id` and `client_secret` as Basic Auth Header. Check [Client Secret Basic Auth Method](./authn-methods#client-secret-basic) on how to build it correctly.
</TabItem>
<TabItem value="client_secret_post">
</Tab>
<Tab value="client_secret_post">
Send your `client_id` and `client_secret` as parameters in the body:
@@ -317,26 +313,25 @@ Send your `client_id` and `client_secret` as parameters in the body:
| client_id | client_id of the application |
| client_secret | client_secret of the application |
</TabItem>
<TabItem value="none">
</Tab>
<Tab value="none">
Send your `client_id` as parameter in the body. No authentication is required.
</TabItem>
<TabItem value="private_key_jwt">
</Tab>
<Tab value="private_key_jwt">
Send a `client_assertion` as JWT for us to validate the signature against the registered public key.
| Parameter | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| client_assertion | JWT built and signed according to [Using JWTs for Client Authentication](authn-methods#jwt-with-private-key) |
| client_assertion | JWT built and signed according to [Using JWTs for Client Authentication](./authn-methods#jwt-with-private-key) |
| client_assertion_type | Must be `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` |
</TabItem>
</Tab>
</Tabs>
#### Successful refresh token response {#token-refresh-response}
#### Successful refresh token response
| Property | Description |
| ------------- | ------------------------------------------------------------------------------------- |
| access_token | An `access_token` as JWT or opaque token |
@@ -353,12 +348,12 @@ Send a `client_assertion` as JWT for us to validate the signature against the re
| Parameter | Description |
| ---------- | ---------------------------------------------------------------------------------------------------------- |
| grant_type | Must be `client_credentials` |
| scope | [Scopes](scopes) you would like to request from ZITADEL. Scopes are space delimited, e.g. `openid profile` |
| scope | [Scopes](./scopes) you would like to request from ZITADEL. Scopes are space delimited, e.g. `openid profile` |
Additionally, you need to authenticate your client by either sending `client_id` and `client_secret` as Basic Auth Header.
Check [Client Secret Basic Auth Method](authn-methods#client-secret-basic) on how to build it correctly.
Check [Client Secret Basic Auth Method](./authn-methods#client-secret-basic) on how to build it correctly.
```BASH
```bash
curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
@@ -374,7 +369,7 @@ Or you can also send your `client_id` and `client_secret` as parameters in the b
| client_id | client_id of the application |
| client_secret | client_secret of the application |
```BASH
```bash
curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
@@ -384,8 +379,7 @@ curl --request POST \
--data scope=openid profile
```
#### Successful client credentials response {#token-client-credentials-response}
#### Successful client credentials response
| Property | Description |
| ------------ | ------------------------------------------------------------------------------------- |
| access_token | An `access_token` as JWT or opaque token |
@@ -395,15 +389,15 @@ curl --request POST \
### Token Exchange grant
The Token Exchange grant implements [RFC 8693, OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693) and can be used to exchange tokens to a different scope, audience or subject. Changing the subject of an authenticated token is called impersonation or delegation. ZITADEL also provides a [token exchange guide](/docs/guides/integrate/token-exchange) with more details on using the Token Exchange Grant.
The Token Exchange grant implements [RFC 8693, OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693) and can be used to exchange tokens to a different scope, audience or subject. Changing the subject of an authenticated token is called impersonation or delegation. ZITADEL also provides a [token exchange guide](/guides/integrate/token-exchange) with more details on using the Token Exchange Grant.
:::info
Token Exchange is currently an experimental [beta](https://help.zitadel.com/zitadel-software-release-cycle#beta) feature. Be sure to enable it on the [feature API](/docs/guides/integrate/token-exchange#feature-api) before using it.
:::
<Callout>
Token Exchange is currently an experimental [beta](https://help.zitadel.com/zitadel-software-release-cycle#beta) feature. Be sure to enable it on the [feature API](/guides/integrate/token-exchange#feature-api) before using it.
</Callout>
#### Request parameters
<TokenExchangeRequest />
<TokenExchangeRequest components={props.components} />
Depending on your authorization method you will have to provide additional parameters or headers:
@@ -418,12 +412,12 @@ Depending on your authorization method you will have to provide additional param
]}
>
<TabItem value="client_secret_basic">
<Tab value="client_secret_basic">
Send your `client_id` and `client_secret` as Basic Auth Header. Check [Client Secret Basic Auth Method](authn-methods#client-secret-basic) on how to build it correctly.
Send your `client_id` and `client_secret` as Basic Auth Header. Check [Client Secret Basic Auth Method](./authn-methods#client-secret-basic) on how to build it correctly.
</TabItem>
<TabItem value="client_secret_post">
</Tab>
<Tab value="client_secret_post">
Send your `client_id` and `client_secret` as parameters in the body:
@@ -432,31 +426,30 @@ Send your `client_id` and `client_secret` as parameters in the body:
| client_id | client_id of the application |
| client_secret | client_secret of the application |
</TabItem>
<TabItem value="none">
</Tab>
<Tab value="none">
Send your `client_id` as parameter in the body. No authentication is required.
</TabItem>
<TabItem value="private_key_jwt">
</Tab>
<Tab value="private_key_jwt">
Send a `client_assertion` as JWT for us to validate the signature against the registered public key.
| Parameter | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| client_assertion | JWT built and signed according to [Using JWTs for Client Authentication](authn-methods#jwt-with-private-key) |
| client_assertion | JWT built and signed according to [Using JWTs for Client Authentication](./authn-methods#jwt-with-private-key) |
| client_assertion_type | Must be `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` |
</TabItem>
</Tab>
</Tabs>
#### Successful token exchange response {#token-exchange-response}
<TokenExchangeResponse />
#### Successful token exchange response
<TokenExchangeResponse components={props.components} />
#### Token types
<TokenExchangeTypes />
<TokenExchangeTypes components={props.components} />
### Error response
@@ -491,11 +484,11 @@ values={[
{label: 'private_key_jwt', value: 'private_key_jwt'},
]}
>
<TabItem value="client_secret_basic">
<Tab value="client_secret_basic">
Send your `client_id` and `client_secret` as Basic Auth Header. Check [Client Secret Basic Auth Method](authn-methods#client-secret-basic) on how to build it correctly.
Send your `client_id` and `client_secret` as Basic Auth Header. Check [Client Secret Basic Auth Method](./authn-methods#client-secret-basic) on how to build it correctly.
```BASH
```bash
curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/introspect \
--header 'Content-Type: application/x-www-form-urlencoded' \
@@ -503,18 +496,18 @@ curl --request POST \
--data token=VjVxyCZmRmWYqd3_F5db9Pb9mHR5fqzhn...
```
</TabItem>
</Tab>
<TabItem value="private_key_jwt">
<Tab value="private_key_jwt">
Send a `client_assertion` as JWT for us to validate the signature against the registered public key.
| Parameter | Description |
| --------------------- | ----------------------------------------------------------------------------------------------------------- |
| client_assertion | JWT built and signed according to [Using JWTs for Client Authentication](authn-methods#client-secret-basic) |
| client_assertion | JWT built and signed according to [Using JWTs for Client Authentication](./authn-methods#client-secret-basic) |
| client_assertion_type | must be `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` |
```BASH
```bash
curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/introspect \
--header 'Content-Type: application/x-www-form-urlencoded' \
@@ -523,11 +516,10 @@ curl --request POST \
--data token=VjVxyCZmRmWYqd3_F5db9Pb9mHR5fqzhn...
```
</TabItem>
</Tab>
</Tabs>
### Successful introspection response {#introspect-response}
### Successful introspection response
Upon successful authorization of the client a response with the boolean `active` is returned, indicating if the provided token
is active and the requesting client is part of the token audience.
@@ -547,10 +539,9 @@ If `active` is **true**, further information will be provided:
| username | ZITADEL's login name of the user. Consist of `username@primarydomain` |
Additionally and depending on the granted scopes, information about the authorized user is provided.
Check the [Claims](claims) page if a specific claims might be returned and for detailed description.
### Error response {#introspect-error-response}
Check the [Claims](./claims) page if a specific claims might be returned and for detailed description.
### Error response
If the authorization fails, an HTTP 401 with `invalid_client` will be returned.
## userinfo_endpoint
@@ -561,19 +552,17 @@ This endpoint will return information about the authorized user.
Send the `access_token` of the **user** (not the client) as Bearer Token in the `authorization` header:
```BASH
```bash
curl --request GET \
--url ${CUSTOM_DOMAIN}/oidc/v1/userinfo
--header 'Authorization: Bearer dsfdsjk29fm2as...'
```
### Successful userinfo response {#userinfo-response}
### Successful userinfo response
If the `access_token` is valid, the information about the user depending on the granted scopes is returned.
Check the [Claims](claims) page if a specific claims might be returned and for detailed description.
### Error response {#userinfo-error-response}
Check the [Claims](./claims) page if a specific claims might be returned and for detailed description.
### Error response
If the token is invalid or expired, an HTTP 401 will be returned.
## revocation_endpoint
@@ -582,10 +571,10 @@ If the token is invalid or expired, an HTTP 401 will be returned.
This endpoint enables clients to revoke an `access_token` or `refresh_token` they have been granted.
:::important
<Callout>
If you revoke an `access_token` only the specific token will be revoked. When revoking a `refresh_token`,
the corresponding `access_token` will be revoked as well.
:::
</Callout>
| Parameter | Description |
| --------- | -------------------------------- |
@@ -603,12 +592,12 @@ values={[
{label: 'private_key_jwt', value: 'private_key_jwt'},
]}
>
<TabItem value="client_secret_basic">
<Tab value="client_secret_basic">
Send your `client_id` and `client_secret` as Basic Auth Header. Check [Client Secret Basic Auth Method](authn-methods#client-secret-basic) on how to construct a request correctly.
Send your `client_id` and `client_secret` as Basic Auth Header. Check [Client Secret Basic Auth Method](./authn-methods#client-secret-basic) on how to construct a request correctly.
</TabItem>
<TabItem value="client_secret_post">
</Tab>
<Tab value="client_secret_post">
Send your `client_id` and `client_secret` as parameters in the body:
@@ -617,8 +606,8 @@ Send your `client_id` and `client_secret` as parameters in the body:
| client_id | client_id of the application |
| client_secret | client_secret of the application |
</TabItem>
<TabItem value="none">
</Tab>
<Tab value="none">
Send your `client_id` as parameters in the body:
@@ -626,17 +615,17 @@ Send your `client_id` as parameters in the body:
| --------- | ---------------------------- |
| client_id | client_id of the application |
</TabItem>
<TabItem value="private_key_jwt">
</Tab>
<Tab value="private_key_jwt">
Send a `client_assertion` as JWT for ZITADEL to verify the signature against the registered public key.
| Parameter | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------- |
| client_assertion | JWT created and signed according to [Using JWTs for Client Authentication](authn-methods#client-secret-basic) |
| client_assertion | JWT created and signed according to [Using JWTs for Client Authentication](./authn-methods#client-secret-basic) |
| client_assertion_type | must be `urn:ietf:params:oauth:client-assertion-type:jwt-bearer` |
```BASH
```bash
curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/revoke \
--header 'Content-Type: application/x-www-form-urlencoded' \
@@ -645,7 +634,7 @@ curl --request POST \
--data token=VjVxyCZmRmWYqd3_F5db9Pb9mHR5fqzhn...
```
</TabItem>
</Tab>
</Tabs>
## end_session_endpoint
@@ -675,16 +664,16 @@ If neither an `id_token_hint` nor a `client_id` parameter is provided, the `post
`${CUSTOM_DOMAIN}/oauth/v2/keys`
The endpoint returns a JSON Web Key Set (JWKS) containing the public keys that can be used to locally validate JWTs you received from ZITADEL.
The alternative would be to validate tokens with the [introspection endpoint](#introspection_endpoint).
The alternative would be to validate tokens with the [introspection endpoint](#introspection-endpoint).
### Key rotation
Keys are automatically rotated on a regular basis or on demand, meaning keys can change in irregular intervals.
ZITADEL ensures that a proper `kid` is set with each key.
:::info Keys rotate without prior notice
<Callout title="Keys rotate without prior notice">
Be aware that these keys can be rotated without any prior notice.
:::
</Callout>
### Caching

Some files were not shown because too many files have changed in this diff Show More