mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 05:52:51 +00:00
3be21ccbf0
Publishes the v4.17.1 benchmark sweep and the harness fixes the sweep uncovered. ## Results All 11 published targets ran for 30 minutes each against a fixed 7-container deployment (vCPU 6 / 6 Gi, psql v17.4, US1 client and server), at 600 VUs except where noted. Latencies are `http_req_duration` over the test phase. | target | VUs | iter/s | p50 | p95 | p99 | failed requests | |:---|---:|---:|---:|---:|---:|:---| | machine_pat_login | 600 | 3452 | 24.53ms | 872ms | 1.00s | 29 / 6,335,633 (0.00%) | | user_info | 600 | 3217 | 29.32ms | 943ms | 1.13s | 66 / 5,800,788 (0.00%) | | introspect | 600 | 2297 | 46.49ms | 1.16s | 1.36s | 1,400 / 4,159,863 (0.03%) | | machine_jwt_profile_grant | 600 | 1076 | 85.34ms | 2.57s | 2.93s | 97 / 1,986,156 (0.00%) | | machine_client_credentials_login | 600 | 834 | 56.78ms | 1.74s | 2.42s | 1,789 / 3,073,497 (0.05%) | | add_session | 600 | 767 | 95.25ms | 3.53s | 4.15s | 1 / 1,416,546 (0.00%) | | oidc_session | 600 | 326 | 77.47ms | 3.41s | 4.43s | 3 / 1,767,162 (0.00%) | | otp_session | 600 | 84 | 47.80ms | 13.83s | 20.22s | 182 / 466,756 (0.03%) | | password_session | 600 | 68 | 408.63ms | 20.00s | 24.05s | 1 / 253,280 (0.00%) | | human_password_login | 600 | 49 | 146.67ms | 4.08s | 1m0s | 9,227 / 683,256 (1.35%) | | manipulate_user | **200** | 19 | 304.58ms | 10.23s | 38.43s | 225 / 171,987 (0.13%) | Against the goals: - **#8352 is met.** `machine_jwt_profile_grant` reached **1076/s** against the 1000/s goal, with p50 at 85ms. - **#4424 is not met.** `human_password_login` runs at **49/s** against a 1200/s goal. The sweep ran with `improvedPerformance` enabled (`PROJECT_GRANT`, `PROJECT`, `USER_GRANT`, `ORG_DOMAIN_VERIFIED`), captured from the instance before the first target rather than assumed; the full flag set is on every page. ## What the observability rows show The containers were never the constraint. ZITADEL CPU sat at 9–50% (p50), memory at 6–7% (p50, peaking at 16%) of 6 GiB, and instance count was flat at 7 with no container startups in any window. Database CPU was at **86–98% median on nine of eleven targets**. Any "ZITADEL achieves N/s" figure that omits which resource ran out is true and misleading, so the pages say. The query breakdown then shows what the CPU numbers cannot: **advisory lock wait is the single largest category of database time across the sweep (91,857 s accumulated)**, ahead of event reads (64,805 s), event push (26,411 s) and projection reads (14,625 s). The three locks are the projection handler lock (`handler/v2/handler.go`), the eventstore read barrier (`repository/sql/query.go`) and the shared lock every push takes (`eventstore/v3/push.go`). That is what sets the `flowchart outcome` on each page, and it is not uniform: - **Scale** on the seven targets where a resource genuinely ran out — database CPU at 92–98% with 0% lock share. - **Potential issues** on `human_password_login`, `password_session`, `otp_session` and `manipulate_user`, where 45–74% of the top query time is lock wait. `password_session` runs at 51% database CPU and 50% container CPU and still only manages 68 iter/s; adding vCPU there buys nothing. Autovacuum is cleared as a contributor: 93.9% median DB CPU in buckets containing a vacuum against 93.1% without, within noise. The new v4.17 eventstore autovacuum is barely triggered — `events2` is not in the top twenty vacuumed tables. ## Harness fixes Defects found during the sweep, all of which corrupted published numbers or aborted runs: 1. **Colliding check names.** `updateHuman`, `lockUser` and `deleteUser` all registered checks as `update user is status ok`, two of them asserting `status === 201` against endpoints returning 200. k6 aggregates checks by name, so this produced a permanent, fictional 28% failure rate. Each check now has its own name and accepts 2xx. 2. **User-creation read-after-write race**, in three variants, each found after the previous fix. The read-back resolved `undefined` when the projection was behind, surfacing much later as `Cannot read property '0' of undefined`; then an unguarded `res.json()` turned every request timeout into a killed iteration; then a *partial* read — a valid user object with `loginNames` not yet projected — passed an `if (user)` guard and failed identically. `readUserAfterCreate()` now guards status and body before parsing, requires the field rather than the object, and retries with backoff, rejecting with the user id and username. 3. **Metric cardinality.** Id-bearing URLs produced 800k+ time series against k6's suggested 100k, driving k6 to 6.8 GB and an OOM mid-run. All 16 such call sites now set a grouped `name` tag. 4. **`password_session` wrote its CSV to `otp_session`'s filename** in the Makefile, silently overwriting the previous target's output. The read-back race is not only a harness defect: at 600 VUs it measures real load-induced projection lag, exceeding 25 s for login-name projection and 100 s for the user projection, against instant reads on an unloaded instance. ## Stable v2 user API Four calls in `benchmark/src/user.ts` still went to `/v2beta/users` — update, lock, delete and the machine read-back. They date from the original load-test bootstrap in April 2024 (#7635), when the user service was still v2beta, and were never moved when it was promoted; they surfaced in this diff only because the read-after-write fix rewrote the surrounding functions. All four are now on stable v2. `updateHuman` is the one that changed shape: `PUT /v2beta/users/{id}` is `UpdateHumanUser`, whose stable-v2 counterpart `PUT /v2/users/human/{id}` is deprecated in the proto, so it now calls `PATCH /v2/users/{id}` (`UpdateUser`) and `manipulate_user` nests the profile under `human`. Both RPCs land on `command.ChangeUserHuman`, so the measured work is unchanged. `lockUser`, `deleteUser` and the `createMachine` read-back move over unchanged in method and payload. No published result is affected: per-endpoint latencies come from custom Trends, and `run-bench.sh` drops the `name` system tag, so no artefact ever recorded a v2beta URL. The remaining `/management/v1` and `/admin/v1` calls are left alone — migrating those changes which API surface is benchmarked and would need a re-run. ## Timestamps Pages reported `Test start` as a bare `HH:MM`, so a run could not be correlated against monitoring the next day. Pages now carry the full UTC date and time and a `Test end` row, both derived from the first and last per-second row of `output.json`. `_template.mdx` is updated to match. ## Post-mortem `benchmark/postmortems/2026-08-27-503-burst.md` records two bursts of HTTP 503 `Service error -27` — an HTML page from the Google frontend, not a ZITADEL error — on `manipulate_user` and `human_password_login`, six hours apart. **The investigation is open**, and the note is explicit about what is established (no container startups; the two bursts have opposite server-side signatures), what is provisionally ruled out (restart, panic), and what is not yet known. It is included because both affected pages report the 503s as a separate population from the ZITADEL failures beside them, and that split needs its evidence somewhere. It also records two defects found by accident in the collected logs, unrelated to the 503s: `sql: transaction has already been committed or rolled back` (232 occurrences under load) and a missing i18n key, `"unable to get user by id" not found in language "en"`. ## Notes for review - **`manipulate_user` ran at 200 VUs, not 600, and the page says so.** Throughput saturates near 100 VUs; at 600 the same target produced 4,283 failed requests for identical throughput against 225 at 200 VUs. Its failure mode is degradation over sustained single-org churn — per-operation p50 climbs 1.7x–6x between the first and last five minutes of a run — not a concurrency threshold. - **Two `Observed errors` rows are hand-corrected** and deliberately differ from the generated text, on `manipulate_user` and `human_password_login`. Both cases are one generated number covering two unrelated failure populations; each page says it was corrected and why. - Org deletion failing with a 500 (`V3-C8l3V`) after heavy user churn is already tracked as #8510 and was hit repeatedly during cleanup. - **The run/publish tooling is no longer part of this PR.** It moved to a private repository, along with the cloud collection scripts, because deployment identity does not belong here. What remains is the published pages, the post-mortem findings and the harness fixes. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
1109 lines
37 KiB
TypeScript
1109 lines
37 KiB
TypeScript
// --- Type Definitions ---
|
|
|
|
export type SidebarLink = {
|
|
type: 'generated-index' | 'doc';
|
|
title?: string;
|
|
slug?: string;
|
|
id?: string;
|
|
description?: string;
|
|
};
|
|
|
|
export type SidebarItem =
|
|
| string
|
|
| {
|
|
type: 'category' | 'link' | 'doc' | 'autogenerated';
|
|
label?: string;
|
|
items?: readonly SidebarItem[];
|
|
collapsed?: boolean;
|
|
link?: SidebarLink;
|
|
href?: string;
|
|
id?: string;
|
|
dirName?: string;
|
|
icon?: any;
|
|
};
|
|
|
|
// --- Sidebar Data ---
|
|
|
|
export const guidesSidebar: readonly SidebarItem[] = [
|
|
{
|
|
type: "category",
|
|
label: "Get Started",
|
|
collapsed: false,
|
|
items: [
|
|
"guides/start/quickstart",
|
|
{
|
|
type: "category",
|
|
label: "Key Concepts",
|
|
link: {
|
|
type: "generated-index",
|
|
title: "Key Concepts",
|
|
slug: "concepts",
|
|
description:
|
|
"Learn about ZITADEL's core architecture and terminology. This section covers identity management concepts, multi-tenancy, and technical structures essential for understanding our platform.",
|
|
},
|
|
items: [
|
|
"concepts/structure/instance",
|
|
"guides/manage/console/organizations-overview",
|
|
"guides/manage/console/projects-overview",
|
|
"guides/manage/console/applications-overview",
|
|
"guides/manage/console/users-overview",
|
|
"concepts/structure/administrators",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Authenticate Users",
|
|
link: {
|
|
type: "generated-index",
|
|
title: "Login users with ZITADEL",
|
|
slug: "guides/integrate/login",
|
|
description:
|
|
"Sign-in users and application with ZITADEL. In this section you will find resources on how to authenticate your users by using the hosted login via OpenID Connect and SAML. Follow our dedicated guides to build your custom login user interface, if you want to customize the login behavior further.",
|
|
},
|
|
items: [
|
|
"guides/integrate/login/login-users",
|
|
"guides/integrate/login/hosted-login",
|
|
"guides/integrate/login/oidc/logout",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Example Applications",
|
|
link: {
|
|
type: "generated-index",
|
|
title: "Example Applications",
|
|
slug: "/examples/introduction",
|
|
description:
|
|
"Discover practical quickstart guides and example applications for ZITADEL. We provide step-by-step instructions for popular frameworks like React, Angular, Vue, Next.js, and more.",
|
|
},
|
|
items: [
|
|
{
|
|
type: "category",
|
|
label: "Frontend (SPA)",
|
|
link: {
|
|
type: "generated-index",
|
|
title: "Frontend (SPA) Quickstart Guides",
|
|
slug: "/examples/introduction/frontend",
|
|
description:
|
|
"Step-by-step instructions for integrating ZITADEL authentication into your frontend single-page applications. Includes guides for React, Angular, Vue, and vanilla JS.",
|
|
},
|
|
items: [
|
|
"sdk-examples/angular",
|
|
"sdk-examples/react",
|
|
{
|
|
type: "link",
|
|
label: "Vanilla-JS",
|
|
href: "https://github.com/zitadel/zitadel-vanilla-js",
|
|
},
|
|
"sdk-examples/vue",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Mobile & Native",
|
|
link: {
|
|
type: "generated-index",
|
|
title: "Mobile & Native Quickstart Guides",
|
|
slug: "/examples/introduction/mobile",
|
|
description:
|
|
"Quickstart guides for integrating ZITADEL authentication into mobile and native applications. Learn how to secure your mobile apps with our Flutter and .NET guides.",
|
|
},
|
|
items: [
|
|
"examples/login/flutter",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Full-Stack / SSR",
|
|
link: {
|
|
type: "generated-index",
|
|
title: "Full-Stack / SSR Quickstart Guides",
|
|
slug: "/examples/introduction/fullstack",
|
|
description:
|
|
"Integrate ZITADEL with your full-stack and server-side rendered (SSR) applications. Follow our guides for Next.js, B2B scenarios, and other modern web frameworks.",
|
|
},
|
|
items: [
|
|
"sdk-examples/astro",
|
|
"sdk-examples/dotnet",
|
|
"sdk-examples/expressjs",
|
|
"sdk-examples/flask",
|
|
"sdk-examples/fastapi",
|
|
"sdk-examples/fastify",
|
|
"sdk-examples/laravel",
|
|
"sdk-examples/nestjs",
|
|
"sdk-examples/nextjs",
|
|
"examples/login/nextjs-b2b",
|
|
"sdk-examples/nuxtjs",
|
|
"sdk-examples/qwik",
|
|
"sdk-examples/solidstart",
|
|
"sdk-examples/sveltekit",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Web App (Server-Side)",
|
|
link: {
|
|
type: "generated-index",
|
|
title: "Web App (Server-Side) Quickstart Guides",
|
|
slug: "/examples/introduction/webapp",
|
|
description:
|
|
"Step-by-step guides for integrating ZITADEL into traditional server-side web applications. Learn how to secure Java Spring, PHP Symfony, Django, and Go apps.",
|
|
},
|
|
items: [
|
|
"sdk-examples/django",
|
|
"examples/login/go",
|
|
"sdk-examples/symfony",
|
|
"sdk-examples/spring",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "APIs / Backend Services",
|
|
link: {
|
|
type: "generated-index",
|
|
title: "APIs / Backend Quickstart Guides",
|
|
slug: "/examples/introduction/backend",
|
|
description:
|
|
"Learn how to secure your APIs and backend services using ZITADEL. Includes examples for Node.js, Python, Go, Java, and NestJS to implement robust authentication.",
|
|
},
|
|
items: [
|
|
"examples/secure-api/go",
|
|
"examples/secure-api/java-spring",
|
|
"examples/secure-api/nodejs-nestjs",
|
|
"examples/secure-api/pylon",
|
|
"examples/secure-api/python-django",
|
|
],
|
|
},
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Use Cases",
|
|
link: {
|
|
type: "generated-index",
|
|
title: "Use Cases",
|
|
slug: "guides/solution-scenarios/introduction",
|
|
description:
|
|
"Customers of an SaaS Identity and access management system usually have all distinct use cases and requirements. This guide attempts to explain real-world implementations and break them down into solution scenarios which aim to help you getting started with ZITADEL.",
|
|
},
|
|
items: [
|
|
"guides/solution-scenarios/b2b",
|
|
"guides/solution-scenarios/configurations",
|
|
"guides/solution-scenarios/saas",
|
|
"guides/solution-scenarios/b2c",
|
|
"guides/solution-scenarios/frontend-calling-backend-API",
|
|
"guides/solution-scenarios/guest-auth",
|
|
{
|
|
type: "category",
|
|
label: "Machine-to-Machine (M2M)",
|
|
items: [
|
|
"guides/integrate/service-accounts/authenticate-service-accounts",
|
|
"guides/integrate/service-accounts/private-key-jwt",
|
|
"guides/integrate/service-accounts/client-credentials",
|
|
"guides/integrate/service-accounts/personal-access-token",
|
|
],
|
|
},
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Onboard Customers and Users",
|
|
link: {
|
|
type: "generated-index",
|
|
title: "Onboard Customers and Users",
|
|
slug: "/guides/integrate/onboarding",
|
|
description:
|
|
"When building your own application, one of the first questions you have to face, is 'How do my customers onboard to my application?'\n" +
|
|
"These guides will explain the built-in solution for onboarding new tenants, customers, and users and how you can handle more advanced onboarding use cases. ",
|
|
},
|
|
collapsed: true,
|
|
items: [
|
|
"guides/integrate/onboarding/b2b",
|
|
"guides/integrate/onboarding/end-users",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Branding & Customization",
|
|
items: [
|
|
"guides/manage/customize/branding",
|
|
"guides/manage/customize/texts",
|
|
"guides/manage/customize/restrictions",
|
|
"guides/manage/customize/user-metadata",
|
|
"guides/manage/customize/notification-providers",
|
|
"concepts/features/custom-domain",
|
|
]
|
|
},
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Integrate & Authenticate",
|
|
link: {
|
|
type: "generated-index",
|
|
title: "Integrate",
|
|
slug: "guides/integrate",
|
|
description:
|
|
"Integrate your users and application with ZITADEL. In this section you will find resource on how to authenticate your users, configure external identity providers, access the ZITADEL APIs to manage resources, and integrate with third party services and tools.",
|
|
},
|
|
collapsed: true,
|
|
items: [
|
|
{
|
|
type: "category",
|
|
label: "OIDC & OAuth Flows",
|
|
link: {
|
|
type: "generated-index",
|
|
title: "Authenticate users with OpenID Connect (OIDC)",
|
|
slug: "guides/integrate/login/oidc",
|
|
description:
|
|
"Comprehensive guide to user authentication in ZITADEL using OpenID Connect (OIDC), including recommended flows and session management.",
|
|
},
|
|
items: [
|
|
"guides/integrate/login/oidc/oauth-recommended-flows",
|
|
"guides/integrate/login/oidc/login-users",
|
|
"guides/integrate/login/oidc/device-authorization",
|
|
"apis/openidoauth/endpoints",
|
|
"apis/openidoauth/authn-methods",
|
|
"apis/openidoauth/scopes",
|
|
"apis/openidoauth/claims",
|
|
"apis/openidoauth/grant-types",
|
|
"apis/openidoauth/authrequest",
|
|
"guides/integrate/login/oidc/webkeys",
|
|
"guides/integrate/login/oidc/native-app-links",
|
|
"guides/integrate/token-exchange",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "SAML",
|
|
items: [
|
|
"guides/integrate/login/saml",
|
|
"apis/saml/endpoints",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "API Access",
|
|
items: [
|
|
"guides/integrate/zitadel-apis/access-zitadel-apis",
|
|
"guides/integrate/zitadel-apis/access-zitadel-system-api",
|
|
"guides/integrate/zitadel-apis/event-api",
|
|
"guides/integrate/zitadel-apis/example-zitadel-api-with-go",
|
|
"guides/integrate/zitadel-apis/example-zitadel-api-with-dot-net",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "SDKs & Integrations",
|
|
items: [
|
|
"sdk-examples/introduction",
|
|
{
|
|
type: "category",
|
|
label: "Frontend & Mobile (OIDC/PKCE)",
|
|
items: [
|
|
{
|
|
type: "link",
|
|
label: "Angular",
|
|
href: "/docs/sdk-examples/oidc-libraries"
|
|
},
|
|
"sdk-examples/go",
|
|
{
|
|
type: "link",
|
|
label: ".NET (MAUI/Xamarin)",
|
|
href: "https://github.com/smartive/zitadel-net",
|
|
},
|
|
{
|
|
type: "link",
|
|
label: "NextAuth",
|
|
href: "https://next-auth.js.org/providers/zitadel",
|
|
},
|
|
{
|
|
type: "link",
|
|
label: "React",
|
|
href: "https://github.com/zitadel/zitadel-react",
|
|
},
|
|
{
|
|
type: "link",
|
|
label: "Vue",
|
|
href: "https://github.com/zitadel/zitadel-vue",
|
|
},
|
|
{
|
|
type: "link",
|
|
label: "Other",
|
|
href: "/docs/sdk-examples/oidc-libraries"
|
|
},
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Backend & API",
|
|
items: [
|
|
{
|
|
type: "link",
|
|
label: ".NET (MAUI/Xamarin)",
|
|
href: "https://github.com/smartive/zitadel-net",
|
|
},
|
|
"sdk-examples/go",
|
|
{
|
|
type: "link",
|
|
label: "Passport.js",
|
|
href: "https://github.com/buehler/node-passport-zitadel",
|
|
},
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Management API Clients",
|
|
items: [
|
|
{
|
|
type: "link",
|
|
label: "Dart / Flutter",
|
|
href: "https://github.com/smartive/zitadel-dart",
|
|
},
|
|
{
|
|
type: "link",
|
|
label: "Elixir",
|
|
href: "https://github.com/maennchen/zitadel_api",
|
|
},
|
|
"sdk-examples/go",
|
|
"sdk-examples/client-libraries/java",
|
|
{
|
|
type: "link",
|
|
label: ".NET (MAUI/Xamarin)",
|
|
href: "https://github.com/smartive/zitadel-net",
|
|
},
|
|
"sdk-examples/client-libraries/node",
|
|
{
|
|
type: "link",
|
|
label: "Node.js (Community)",
|
|
href: "https://github.com/smartive/zitadel-node",
|
|
},
|
|
"sdk-examples/client-libraries/php",
|
|
"sdk-examples/client-libraries/python",
|
|
"sdk-examples/client-libraries/ruby",
|
|
{
|
|
type: "link",
|
|
label: "Rust",
|
|
href: "https://github.com/smartive/zitadel-rust",
|
|
},
|
|
],
|
|
},
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "SCIM",
|
|
link: {
|
|
type: "doc",
|
|
id: "guides/manage/user/scim2",
|
|
},
|
|
items: ["guides/integrate/scim-okta-guide"]
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Token Introspection",
|
|
link: {
|
|
type: "doc",
|
|
id: "guides/integrate/token-introspection",
|
|
},
|
|
items: [
|
|
"guides/integrate/token-introspection/basic-auth",
|
|
"guides/integrate/token-introspection/private-key-jwt",
|
|
]
|
|
},
|
|
"guides/integrate/back-channel-logout",
|
|
{
|
|
type: "category",
|
|
label: "External Integrations",
|
|
items: [
|
|
{
|
|
type: "category",
|
|
label: "Services",
|
|
link: {
|
|
type: "generated-index",
|
|
title: "Integrate ZITADEL with your Favorite Services",
|
|
slug: "/guides/integrate/services",
|
|
description:
|
|
"Step-by-step guides for integrating ZITADEL with popular services and tools including Google Workspace, AWS, Atlassian, Cloudflare, GitLab, and many other software solutions.",
|
|
},
|
|
items: [
|
|
"guides/integrate/services/google-workspace",
|
|
"guides/integrate/services/aws-saml",
|
|
"guides/integrate/services/atlassian-saml",
|
|
"guides/integrate/services/pingidentity-saml",
|
|
"guides/integrate/services/google-cloud",
|
|
"guides/integrate/services/cloudflare-oidc",
|
|
"guides/integrate/services/gitlab-saml",
|
|
"guides/integrate/services/auth0-saml",
|
|
"guides/integrate/services/auth0-oidc",
|
|
"guides/integrate/services/gitlab-self-hosted",
|
|
{
|
|
type: "link",
|
|
label: "Bold BI",
|
|
href: "https://support.boldbi.com/kb/article/13708/how-to-configure-zitadel-oauth-login-in-bold-bi",
|
|
},
|
|
{
|
|
type: "link",
|
|
label: "Cloudflare Workers",
|
|
href: "https://zitadel.com/blog/increase-spa-security-with-cloudflare-workers",
|
|
},
|
|
{
|
|
type: "link",
|
|
label: "Firezone",
|
|
href: "https://www.firezone.dev/docs/authenticate/oidc/zitadel",
|
|
},
|
|
{
|
|
type: "link",
|
|
label: "Netbird",
|
|
href: "https://docs.netbird.io/selfhosted/identity-providers",
|
|
},
|
|
{
|
|
type: "link",
|
|
label: "Nextcloud",
|
|
href: "https://zitadel.com/blog/zitadel-as-sso-provider-for-selfhosting",
|
|
},
|
|
{
|
|
type: "link",
|
|
label: "Psono",
|
|
href: "https://doc.psono.com/admin/configuration/oidc-zitadel.html",
|
|
},
|
|
{
|
|
type: "link",
|
|
label: "Zoho Desk",
|
|
href: "https://help.zoho.com/portal/en/kb/desk/user-management-and-security/data-security/articles/setting-up-saml-single-signon-for-help-center#Zitadel_IDP",
|
|
},
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Tools",
|
|
items: [
|
|
{
|
|
type: "link",
|
|
label: "Argo CD",
|
|
href: "https://argo-cd.readthedocs.io/en/latest/operator-manual/user-management/zitadel/",
|
|
},
|
|
"guides/integrate/tools/apache2",
|
|
"guides/integrate/authenticated-mongodb-charts",
|
|
"examples/identity-proxy/oauth2-proxy",
|
|
],
|
|
},
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Build your own Login UI",
|
|
link: {
|
|
type: "generated-index",
|
|
title: "Build your own Login UI",
|
|
slug: "/guides/integrate/login-ui",
|
|
description:
|
|
"Create a completely customized login experience using the ZITADEL Session and OIDC APIs. Learn how to handle username/password, MFA, passkeys, and external identity providers.",
|
|
},
|
|
collapsed: true,
|
|
items: [
|
|
"guides/integrate/login-ui/session-validation",
|
|
"guides/integrate/login-ui/username-password",
|
|
"guides/integrate/login-ui/external-login",
|
|
"guides/integrate/login-ui/passkey",
|
|
"guides/integrate/login-ui/mfa",
|
|
"guides/integrate/login-ui/select-account",
|
|
"guides/integrate/login-ui/password-reset",
|
|
"guides/integrate/login-ui/logout",
|
|
"guides/integrate/login-ui/oidc-standard",
|
|
"guides/integrate/login-ui/saml-standard",
|
|
"guides/integrate/login-ui/device-auth",
|
|
"guides/integrate/login-ui/login-app",
|
|
"guides/integrate/login-ui/fork-and-deploy-login-app",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Actions",
|
|
items: [
|
|
{
|
|
type: "category",
|
|
label: "V1",
|
|
link: {
|
|
type: "doc",
|
|
id: "concepts/features/actions",
|
|
},
|
|
items: [
|
|
"guides/manage/console/actions-overview",
|
|
"apis/actions/modules",
|
|
"apis/actions/code-examples",
|
|
"apis/actions/internal-authentication",
|
|
"apis/actions/external-authentication",
|
|
"apis/actions/complement-token",
|
|
"apis/actions/customize-samlresponse",
|
|
"apis/actions/objects",
|
|
"guides/manage/customize/behavior",
|
|
]
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "V2",
|
|
link: {
|
|
type: "doc",
|
|
id: "concepts/features/actions_v2",
|
|
},
|
|
items: [
|
|
"guides/integrate/actions/usage",
|
|
"guides/integrate/actions/testing-request",
|
|
"guides/integrate/actions/testing-request-manipulation",
|
|
"guides/integrate/actions/testing-response",
|
|
"guides/integrate/actions/testing-response-manipulation",
|
|
"guides/integrate/actions/testing-function",
|
|
"guides/integrate/actions/testing-function-manipulation",
|
|
"guides/integrate/actions/testing-event",
|
|
"guides/integrate/actions/testing-request-signature",
|
|
"guides/integrate/actions/migrate-from-v1",
|
|
"guides/integrate/actions/webhook-site-setup",
|
|
],
|
|
},
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Migrate",
|
|
collapsed: true,
|
|
items: [
|
|
"guides/migrate/introduction",
|
|
"guides/migrate/users",
|
|
"guides/migrate/sources/zitadel",
|
|
"guides/migrate/sources/auth0",
|
|
"guides/migrate/sources/keycloak",
|
|
"guides/migrate/sources/firebase",
|
|
],
|
|
},
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Configure Identity & Policies",
|
|
collapsed: true,
|
|
items: [
|
|
"guides/manage/user/reg-create-user",
|
|
"guides/manage/user/self-deletion",
|
|
"guides/manage/terraform-provider",
|
|
{
|
|
type: "category",
|
|
label: "Identity Providers",
|
|
link: {
|
|
type: "doc",
|
|
id: "guides/integrate/identity-providers/introduction",
|
|
},
|
|
items: [
|
|
{
|
|
type: "category",
|
|
label: "Social Logins",
|
|
collapsed: true,
|
|
items: [
|
|
"guides/integrate/identity-providers/google",
|
|
"guides/integrate/identity-providers/apple",
|
|
"guides/integrate/identity-providers/github",
|
|
"guides/integrate/identity-providers/gitlab",
|
|
"guides/integrate/identity-providers/linkedin-oauth",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Enterprise (SAML & OIDC)",
|
|
collapsed: true,
|
|
items: [
|
|
"guides/integrate/identity-providers/azure-ad-oidc",
|
|
"guides/integrate/identity-providers/azure-ad-saml",
|
|
"guides/integrate/identity-providers/okta-oidc",
|
|
"guides/integrate/identity-providers/okta_saml",
|
|
"guides/integrate/identity-providers/keycloak",
|
|
"guides/integrate/identity-providers/onelogin-saml",
|
|
"guides/integrate/identity-providers/pingfederate-saml",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Legacy & Directory (LDAP)",
|
|
items: [
|
|
"guides/integrate/identity-providers/ldap",
|
|
"guides/integrate/identity-providers/openldap",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Custom & Generic",
|
|
items: [
|
|
"guides/integrate/identity-providers/generic-oidc",
|
|
"guides/integrate/identity-providers/jwt_idp",
|
|
"guides/integrate/identity-providers/mocksaml",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Guides",
|
|
items: [
|
|
"guides/integrate/identity-providers/migrate",
|
|
"guides/integrate/identity-providers/additional-information",
|
|
]
|
|
}
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Policies",
|
|
items: [
|
|
"guides/manage/console/default-settings",
|
|
"concepts/structure/policies",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Roles & Permissions",
|
|
items: [
|
|
"guides/manage/console/roles",
|
|
"guides/integrate/retrieve-user-roles",
|
|
"concepts/structure/granted_projects",
|
|
"guides/manage/console/administrators",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Compliance & Security",
|
|
items: [
|
|
"concepts/features/audit-trail",
|
|
"guides/integrate/external-audit-log",
|
|
],
|
|
},
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Test & Debug",
|
|
collapsed: true,
|
|
items: [
|
|
{
|
|
type: "link",
|
|
label: "OIDC Playground",
|
|
href: "https://zitadel.com/playgrounds/oidc",
|
|
},
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Deploy & Operate",
|
|
collapsed: true,
|
|
items: [
|
|
"guides/manage/console/console-overview",
|
|
"guides/manage/cloud/egress",
|
|
{
|
|
type: "category",
|
|
label: "Self-Hosted",
|
|
items: [
|
|
"self-hosting/deploy/overview",
|
|
"self-hosting/deploy/linux",
|
|
"self-hosting/deploy/macos",
|
|
"self-hosting/deploy/devcontainer",
|
|
"self-hosting/deploy/compose",
|
|
{
|
|
type: "category",
|
|
label: "Kubernetes",
|
|
collapsed: true,
|
|
link: {
|
|
type: "doc",
|
|
id: "self-hosting/deploy/kubernetes/index",
|
|
},
|
|
items: [
|
|
"self-hosting/deploy/kubernetes/configuration",
|
|
"self-hosting/deploy/kubernetes/ingress",
|
|
"self-hosting/deploy/kubernetes/database",
|
|
"self-hosting/deploy/kubernetes/caching",
|
|
"self-hosting/deploy/kubernetes/observability",
|
|
"self-hosting/deploy/kubernetes/operations",
|
|
"self-hosting/deploy/kubernetes/uninstalling",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Manage",
|
|
collapsed: true,
|
|
items: [
|
|
{
|
|
type: "category",
|
|
label: "Production & Operations",
|
|
collapsed: false,
|
|
items: [
|
|
"self-hosting/manage/requirements",
|
|
"self-hosting/manage/production",
|
|
"self-hosting/manage/productionchecklist",
|
|
"self-hosting/manage/usage_control",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Configuration",
|
|
collapsed: true,
|
|
items: [
|
|
"self-hosting/manage/configure/configure",
|
|
"self-hosting/manage/custom-domain",
|
|
"self-hosting/manage/tls_modes",
|
|
"self-hosting/manage/http2",
|
|
"self-hosting/manage/login-client",
|
|
"self-hosting/manage/adopt-login-v2",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
collapsed: true,
|
|
label: "Reverse Proxy",
|
|
link: {
|
|
type: "doc",
|
|
id: "self-hosting/manage/reverseproxy/reverse_proxy",
|
|
},
|
|
items: [
|
|
"self-hosting/manage/reverseproxy/traefik/traefik",
|
|
"self-hosting/manage/reverseproxy/nginx/nginx",
|
|
"self-hosting/manage/reverseproxy/caddy/caddy",
|
|
"self-hosting/manage/reverseproxy/httpd/httpd",
|
|
"self-hosting/manage/reverseproxy/cloudflare/cloudflare",
|
|
"self-hosting/manage/reverseproxy/cloudflare_tunnel/cloudflare_tunnel",
|
|
"self-hosting/manage/reverseproxy/zitadel_cloud/zitadel_cloud",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Observability",
|
|
collapsed: true,
|
|
items: [
|
|
"self-hosting/manage/service_ping",
|
|
{
|
|
type: "category",
|
|
label: "Metrics",
|
|
collapsed: true,
|
|
link: {
|
|
type: "doc",
|
|
id: "self-hosting/manage/metrics/overview",
|
|
},
|
|
items: ["self-hosting/manage/metrics/prometheus"],
|
|
},
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Tools",
|
|
collapsed: true,
|
|
items: [
|
|
{
|
|
type: "category",
|
|
label: "Command Line Interface",
|
|
collapsed: true,
|
|
link: {
|
|
type: "doc",
|
|
id: "self-hosting/manage/cli/overview",
|
|
},
|
|
items: ["self-hosting/manage/cli/mirror"],
|
|
},
|
|
],
|
|
},
|
|
],
|
|
},
|
|
"self-hosting/deploy/troubleshooting/troubleshooting",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Scaling & Performance",
|
|
items: [
|
|
"self-hosting/manage/updating_scaling",
|
|
"self-hosting/manage/upgrade-v3-to-v4",
|
|
"self-hosting/manage/database/database",
|
|
"self-hosting/manage/cache",
|
|
"self-hosting/manage/tuning",
|
|
],
|
|
},
|
|
|
|
"guides/manage/production-checklist",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Architecture & Concepts",
|
|
collapsed: true,
|
|
items: [
|
|
{
|
|
type: "category",
|
|
label: "System Architecture",
|
|
items: [
|
|
"concepts/architecture/solution",
|
|
"concepts/architecture/software",
|
|
"concepts/architecture/secrets",
|
|
],
|
|
},
|
|
"concepts/principles",
|
|
{
|
|
type: "category",
|
|
label: "Advanced Topics",
|
|
items: [
|
|
{
|
|
type: "category",
|
|
label: "Event Store",
|
|
items: [
|
|
"concepts/eventstore/overview",
|
|
"concepts/eventstore/implementation",
|
|
]
|
|
},
|
|
"concepts/features/selfservice",
|
|
"concepts/features/account-linking",
|
|
"concepts/features/external-user-grant",
|
|
"concepts/features/identity-brokering",
|
|
"concepts/features/passkeys",
|
|
"concepts/knowledge/opaque-tokens",
|
|
"guides/solution-scenarios/domain-discovery",
|
|
"guides/solution-scenarios/restrict-console",
|
|
],
|
|
},
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Product, Releases & Support",
|
|
collapsed: true,
|
|
items: [
|
|
{
|
|
type: "doc",
|
|
id: "product/roadmap",
|
|
label: "Roadmap",
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Support Resources",
|
|
items: [
|
|
"support/troubleshooting",
|
|
"support/technical_advisory",
|
|
{
|
|
type: "link",
|
|
label: "Support States",
|
|
href: "https://help.zitadel.com/zitadel-support-states",
|
|
},
|
|
{
|
|
type: "link",
|
|
label: "Zitadel Release Cycle",
|
|
href: "https://help.zitadel.com/zitadel-software-release-cycle",
|
|
},
|
|
{
|
|
type: "link",
|
|
label: "Knowledge Base",
|
|
href: "https://help.zitadel.com",
|
|
}
|
|
],
|
|
},
|
|
{
|
|
type: "link",
|
|
label: "Pricing",
|
|
href: "https://zitadel.com/pricing",
|
|
},
|
|
{
|
|
type: "link",
|
|
label: "Contact Us",
|
|
href: "https://zitadel.com/contact",
|
|
},
|
|
"guides/manage/cloud/support",
|
|
],
|
|
},
|
|
] as const;
|
|
|
|
export const apisSidebar: readonly SidebarItem[] = [
|
|
"apis/introduction",
|
|
{
|
|
type: "category",
|
|
label: "Core Resources",
|
|
items: [
|
|
{
|
|
type: "category",
|
|
label: "V2",
|
|
items: [
|
|
{ type: "category", label: "User", items: ["reference/api/user"] },
|
|
{ type: "category", label: "Session", items: ["reference/api/session"] },
|
|
{ type: "category", label: "OIDC", items: ["reference/api/oidc"] },
|
|
{ type: "category", label: "SAML", items: ["reference/api/saml"] },
|
|
{ type: "category", label: "Settings", items: ["reference/api/settings"] },
|
|
{ type: "category", label: "Feature", items: ["reference/api/feature"] },
|
|
{ type: "category", label: "Organization", items: ["reference/api/org"] },
|
|
{ type: "category", label: "Identity Provider", items: ["reference/api/idp"] },
|
|
{ type: "category", label: "Web Key", items: ["reference/api/webkey"] },
|
|
{ type: "category", label: "Action", items: ["reference/api/action"] },
|
|
{ type: "category", label: "Instance", items: ["reference/api/instance"] },
|
|
{ type: "category", label: "Project", items: ["reference/api/project"] },
|
|
{ type: "category", label: "Application", items: ["reference/api/application"] },
|
|
{ type: "category", label: "Role Assignment", items: ["reference/api/authorization"] },
|
|
{ type: "category", label: "ZITADEL Internal Permissions", items: ["reference/api/internal_permission"] },
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "V1",
|
|
items: [
|
|
{ type: "category", label: "Authenticated User", items: ["reference/api/auth"] },
|
|
{ type: "category", label: "Organization Objects", items: ["reference/api/management"] },
|
|
{ type: "category", label: "Instance Objects", items: ["reference/api/admin"] },
|
|
{ type: "category", label: "Instance Lifecycle", items: ["reference/api/system"] },
|
|
"apis/migration_v1_to_v2"
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Assets",
|
|
items: ["apis/assets/assets"],
|
|
},
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Observability",
|
|
items: [
|
|
"apis/observability/metrics",
|
|
"apis/observability/health",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Provision Users",
|
|
items: ["apis/scim2"],
|
|
},
|
|
{
|
|
type: "doc",
|
|
label: "gRPC Status Codes",
|
|
id: "apis/statuscodes",
|
|
},
|
|
{
|
|
type: "link",
|
|
label: "Rate Limits (Cloud)",
|
|
href: "/legal/policies/rate-limit-policy",
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Benchmarks",
|
|
link: {
|
|
type: "doc",
|
|
id: "apis/benchmarks/index",
|
|
},
|
|
items: [
|
|
{
|
|
type: "category",
|
|
label: "v2.65.0",
|
|
items: ["apis/benchmarks/v2.65.0/machine_jwt_profile_grant"],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "v2.66.0",
|
|
items: ["apis/benchmarks/v2.66.0/machine_jwt_profile_grant"],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "v2.70.0",
|
|
items: [
|
|
"apis/benchmarks/v2.70.0/machine_jwt_profile_grant",
|
|
"apis/benchmarks/v2.70.0/oidc_session",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "v4",
|
|
items: [
|
|
"apis/benchmarks/v4/add_session",
|
|
"apis/benchmarks/v4/human_password_login",
|
|
"apis/benchmarks/v4/introspect",
|
|
"apis/benchmarks/v4/machine_client_credentials_login",
|
|
"apis/benchmarks/v4/machine_jwt_profile_grant",
|
|
"apis/benchmarks/v4/machine_pat_login",
|
|
"apis/benchmarks/v4/manipulate_user",
|
|
"apis/benchmarks/v4/oidc_session",
|
|
"apis/benchmarks/v4/otp_session",
|
|
"apis/benchmarks/v4/password_session",
|
|
"apis/benchmarks/v4/user_info",
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "v4.17.1",
|
|
items: [
|
|
"apis/benchmarks/v4.17.1/add_session",
|
|
"apis/benchmarks/v4.17.1/human_password_login",
|
|
"apis/benchmarks/v4.17.1/introspect",
|
|
"apis/benchmarks/v4.17.1/machine_client_credentials_login",
|
|
"apis/benchmarks/v4.17.1/machine_jwt_profile_grant",
|
|
"apis/benchmarks/v4.17.1/machine_pat_login",
|
|
"apis/benchmarks/v4.17.1/manipulate_user",
|
|
"apis/benchmarks/v4.17.1/oidc_session",
|
|
"apis/benchmarks/v4.17.1/otp_session",
|
|
"apis/benchmarks/v4.17.1/password_session",
|
|
"apis/benchmarks/v4.17.1/user_info",
|
|
],
|
|
},
|
|
],
|
|
},
|
|
] as const;
|
|
|
|
export const legalSidebar: readonly SidebarItem[] = [
|
|
{
|
|
type: "category",
|
|
label: "Legal Agreements",
|
|
collapsed: true, // This will mean 'defaultOpen: false' in Fumadocs
|
|
link: {
|
|
type: "generated-index",
|
|
title: "Legal Agreements",
|
|
slug: "legal",
|
|
description:
|
|
"This section contains important agreements, policies and appendices relevant for users of our websites and services. All documents will be provided in English language.",
|
|
},
|
|
items: [
|
|
"legal/terms-of-service",
|
|
"legal/data-processing-agreement",
|
|
"legal/subprocessors",
|
|
"legal/annex-support-services",
|
|
{
|
|
type: "category",
|
|
label: "Service Description",
|
|
collapsed: true,
|
|
link: {
|
|
type: "generated-index",
|
|
title: "Service description",
|
|
slug: "/legal/service-description",
|
|
description:
|
|
"Detailed description of services, service levels (SLA), and support commitments for ZITADEL Cloud and Enterprise subscriptions to ensure transparency and reliability.",
|
|
},
|
|
items: [
|
|
{
|
|
type: "autogenerated",
|
|
dirName: "legal/service-description",
|
|
},
|
|
{
|
|
type: "link",
|
|
label: "Billing",
|
|
href: "https://help.zitadel.com/pricing-and-billing-of-zitadel-services"
|
|
}
|
|
],
|
|
},
|
|
{
|
|
type: "category",
|
|
label: "Policies",
|
|
collapsed: true,
|
|
link: {
|
|
type: "generated-index",
|
|
title: "Policies",
|
|
slug: "/legal/policies",
|
|
description:
|
|
"Find all policy documents and guidelines for ZITADEL services, including our privacy policy, acceptable use policy, and other legal frameworks that govern our platform.",
|
|
},
|
|
items: [
|
|
{
|
|
type: "autogenerated",
|
|
dirName: "legal/policies",
|
|
},
|
|
],
|
|
},
|
|
],
|
|
},
|
|
] as const;
|
|
|
|
// Self Hosting Sidebar (Exporting empty array if empty, or move logic here if needed)
|
|
export const selfHostingSidebar: readonly SidebarItem[] = [];
|