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
Files
27ce10276b2eb35763a10ee585ca817cf209043b
zitadel/apps/docs/lib/sidebar-data.ts
T
zitadel-knowledge-bot[bot]GitHubzitadel-knowledge-bot[bot] <296006658+zitadel-knowledge-bot[bot]@users.noreply.github.com>Matías RacedoCopilot Autofix powered by AI
 27ce10276b docs: create knowledge gap ID 65 (#12646) 
Automatically generated PR resolving Knowledge Gap ID 65.

**Thread ID:** manual-1787771291264
**Action:** CREATE
**New File:**
`apps/docs/content/guides/integrate/login-ui/fork-and-deploy-login-app.mdx`

### AI Summary
> My recommendation is to publish a a new Deploy & Operate guide for the
Login App, then link to it from the existing Login App page. The
existing pages address architecture/development, login-client
authorization, and Login V2 adoption separately, but none currently
explains long-term fork ownership and upgrades. (Contribution guide,
login-client setup, adoption guide)

The article should cover:

Full-repository fork as the simplest current recommendation.
The customer’s history-preserving slim-fork approach as an advanced
alternative.
Why copying only apps/login is unsafe while the current npm packages
remain unavailable, linked to #12250.
Release-tag pinning and versioning such as v4.17.0-custom.1.
Development, generation, linting, tests, and Docker builds.
An EKS/Kubernetes Deployment and Service example.
PAT handling through ZITADEL_SERVICE_USER_TOKEN_FILE.
Same-origin versus separate-domain proxy requirements.
Gradual rollout, break-glass access, rollback, and troubleshooting.
A repeatable upstream synchronization and release process.

### Human Reviewer Instructions
> Sample content:
> Maintain and deploy a customized ZITADEL Login UI
> 
> The ZITADEL Login UI is an MIT-licensed Next.js application maintained
in the ZITADEL monorepo. You can customize and deploy it independently,
but your fork becomes an application that your team must build, test,
secure, monitor, and update.
> 
> This guide describes the current workflow for maintaining a customized
Login UI. It is intended for teams that need source-code changes beyond
the branding and text customization available through ZITADEL settings.
> 
> If you only need to change colors, logos, fonts, or translated login
text, first use ZITADEL's supported branding and customization settings.
A source fork creates an ongoing maintenance responsibility.
> 
> Understand the source dependencies
> 
> The Login UI is not currently an isolated project in the repository.
Its relevant dependency chain is:
> 
> apps/login
> └── packages/zitadel-client
>     └── packages/zitadel-proto
>         └── proto
> 
> The root pnpm workspace and Nx configuration also participate in
installing, generating, testing, and building these projects. Copying
only apps/login can therefore fail or silently separate the UI from the
API definitions against which it was developed.
> 
> For the current monorepo workflow, keep the Login UI and these
workspace dependencies on the same upstream ZITADEL revision.
> 
> Choose a fork strategy
> 
> Full repository fork — recommended
> 
> Fork the complete zitadel/zitadel repository and limit your own
changes to apps/login wherever possible. This is the simplest model to
understand and the least likely to miss a new build-time dependency when
upstream changes.
> 
> Use two remotes:
> 
> git clone [email protected]:YOUR_ORGANIZATION/zitadel.git
> cd zitadel
> git remote add upstream https://github.com/zitadel/zitadel.git
> git fetch upstream --tags
> 
> Start customization from a released tag rather than an arbitrary
commit on main:
> 
> git checkout -b custom-login/vX.Y.Z vX.Y.Z
> 
> Replace vX.Y.Z with the ZITADEL release you have selected. A release
tag gives you a reproducible compatibility baseline and a corresponding
changelog.
> 
> History-preserving slim fork — advanced
> 
> If repository size or internal policy makes a full fork impractical,
you can maintain a filtered fork containing only:
> 
> apps/login
> 
> packages/zitadel-client
> 
> packages/zitadel-proto
> 
> proto
> 
> the root pnpm, lockfile, Node, and Nx configuration required by those
projects
> 
> Use git filter-repo identically both when bootstrapping the fork and
during every later synchronization. The list of retained paths and all
filter arguments must remain stable so that freshly filtered upstream
history shares commit ancestry with your fork.
> 
> Important constraints for this model:
> 
> Bootstrap and update with one shared filtering implementation; do not
duplicate the path list in separate scripts.
> 
> Merge the initial import and subsequent update branches with a merge
commit or fast-forward. Do not squash them, because squashing removes
the filtered upstream ancestry needed for future three-way merges.
> 
> Treat any change to the retained path list as a new bootstrap. Adding
or removing paths rewrites the filtered commit IDs.
> 
> Re-run pnpm install after filtering or merging so the lockfile is
reconciled with the retained workspace.
> 
> Review the retained path list whenever upstream changes the Login
build graph.
> 
> This is a valid Git maintenance technique, but it adds machinery that
ZITADEL's normal build does not require. Own and test the filtering
automation as part of your fork.
> 
> Why a standalone apps/login copy is not recommended today
> 
> At the time of writing, current @zitadel/client and @zitadel/proto
releases are not available as version-matched npm dependencies for the
Login UI. The application consumes their workspace sources from the
monorepo. Until version-matched packages are published, retain those
sources rather than replacing the workspace dependencies with old npm
versions. Progress is tracked in zitadel/zitadel#12250.
> 
> Configure a development environment
> 
> The current contribution guide requires Node.js 22.x, Corepack/pnpm,
and Nx. From the repository root:
> 
> corepack enable
> pnpm install
> pnpm nx run-many --target generate
> 
> To develop the Login UI against an existing ZITADEL instance, create
apps/login/.env.dev.local:
> 
> ZITADEL_API_URL=https://your-zitadel-instance.example.com
> ZITADEL_SERVICE_USER_TOKEN=your-login-client-pat
> 
> Do not commit this file or its token. ZITADEL_API_URL must not have a
trailing slash.
> 
> Start the development server:
> 
> pnpm nx run @zitadel/login:dev
> 
> The token must belong to a machine user with the Instance Login Client
role (IAM_LOGIN_CLIENT). See Connect your self-hosted Login UI to
ZITADEL for the supported setup.
> 
> Run the required quality checks
> 
> Run the checks for all three affected projects, not only the Next.js
application:
> 
> pnpm nx run-many \
>   --projects @zitadel/login @zitadel/client @zitadel/proto \
>   --targets lint build test
> 
> If your update includes .proto changes, regenerate the TypeScript
clients before testing:
> 
> pnpm nx run @zitadel/proto:generate
> 
> For meaningful Login UI changes, also perform end-to-end tests against
a staging ZITADEL instance. At minimum, cover the authentication methods
and policies you enable in production:
> 
> Authorization Code Flow with PKCE and callback to the application
> 
> password, passkey, external identity provider, and applicable MFA/OTP
flows
> 
> registration, account selection, password reset, verification, and
logout
> 
> organization-specific policies, branding, and translated text
> 
> expected negative cases such as invalid or expired codes
> 
> desktop and mobile browsers supported by your application
> 
> Build an immutable image
> 
> The repository's documented Docker build flow is:
> 
> pnpm nx run @zitadel/login:build
> docker build -t
registry.example.com/identity/zitadel-login:vX.Y.Z-custom.1 apps/login
> docker push
registry.example.com/identity/zitadel-login:vX.Y.Z-custom.1
> 
> Use an immutable tag that records both the upstream ZITADEL baseline
and your customization revision. For example:
> 
> v4.17.0-custom.1
> 
> Also retain the source commit and image digest in your release record.
Do not deploy a mutable latest tag to production.
> 
> Deploy outside Vercel
> 
> Vercel is not required. The Login UI can run as the Node.js
application produced by the Next.js build or as a container. In
Kubernetes or EKS, run it as a separate Deployment and Service behind
your ingress or load balancer.
> 
> The following fragment shows the important application settings. Adapt
registry authentication, resources, topology, and ingress to your
platform:
> 
> apiVersion: apps/v1
> kind: Deployment
> metadata:
>   name: zitadel-login
> spec:
>   replicas: 2
>   selector:
>     matchLabels:
>       app: zitadel-login
>   template:
>     metadata:
>       labels:
>         app: zitadel-login
>     spec:
>       containers:
>         - name: login
> image: registry.example.com/identity/zitadel-login:vX.Y.Z-custom.1
>           ports:
>             - name: http
>               containerPort: 3000
>           env:
>             - name: ZITADEL_API_URL
>               value: https://zitadel.example.com
>             - name: NEXT_PUBLIC_BASE_PATH
>               value: /ui/v2/login
>             - name: ZITADEL_SERVICE_USER_TOKEN_FILE
>               value: /var/run/secrets/zitadel/login-client.pat
>           volumeMounts:
>             - name: login-client
>               mountPath: /var/run/secrets/zitadel
>               readOnly: true
>           readinessProbe:
>             tcpSocket:
>               port: http
>           livenessProbe:
>             tcpSocket:
>               port: http
>       volumes:
>         - name: login-client
>           secret:
>             secretName: zitadel-login-client
> ---
> apiVersion: v1
> kind: Service
> metadata:
>   name: zitadel-login
> spec:
>   selector:
>     app: zitadel-login
>   ports:
>     - name: http
>       port: 3000
>       targetPort: http
> 
> Store the PAT in a Kubernetes Secret or external secrets manager and
expose it as a read-only file. Restrict access to the Secret and plan
token rotation. Do not bake the PAT into the image.
> 
> Add CPU and memory requests and limits based on load tests from your
own authentication traffic. Use multiple replicas, disruption controls,
and multi-zone scheduling according to your availability requirements.
> 
> Configure routing and domains
> 
> The Login UI contains a server-side component and Next.js middleware
that proxies OIDC-related requests to ZITADEL. Correct proxy routing is
part of the authentication flow, not only static frontend delivery.
> 
> Same public origin
> 
> When the Login UI and ZITADEL share a public origin, route:
> 
> /ui/v2/login to the Login UI service
> 
> all other ZITADEL paths to the ZITADEL API service
> 
> Set NEXT_PUBLIC_BASE_PATH=/ui/v2/login at build and runtime as
required by your packaging. Keep the value consistent with the Login V2
base URI configured in ZITADEL.
> 
> Separate Login domain
> 
> If the Login UI uses a separate public domain such as
login.example.com:
> 
> Serve it over HTTPS.
> 
> Add the Login domain to the instance's Trusted Domains.
> 
> Configure the proxy in front of the Login UI as documented by ZITADEL:
> 
> x-zitadel-public-host: the public Login UI host, for example
login.example.com
> 
> x-zitadel-instance-host: the ZITADEL instance host, for example
auth.example.com
> 
> Test OIDC and SAML callbacks and every configured external identity
provider through the public route.
> 
> Do not assume that setting only ZITADEL_API_URL replaces the required
host-routing behavior for every topology. The Login App architectural
and proxy guidance is the source of truth for these headers.
> 
> Enable Login V2 safely
> 
> For an existing self-hosted ZITADEL installation, follow Adopt Login
V2 on an existing installation.
> 
> Prefer a gradual rollout:
> 
> Deploy the custom Login UI without changing the instance-wide setting.
> 
> Enable the new Login UI for a non-production test application and set
its custom base URL.
> 
> Run the complete authentication test matrix.
> 
> Expand to selected applications.
> 
> Enable it instance-wide only after validation, if that is your
intended topology.
> 
> Keep a break-glass PAT for a machine user with the Instance Owner role
(IAM_OWNER) so that you can revert the Login V2 setting if interactive
login becomes unavailable. Store and audit this credential according to
your incident-access policy.
> 
> Keep the fork synchronized
> 
> Treat upstream synchronization as a normal application dependency
update, not an automatic deployment.
> 
> For a full repository fork:
> 
> git fetch upstream --tags
> git checkout -b update-login-vX.Y.Z
> git merge vX.Y.Z
> 
> Resolve conflicts while preserving the intent of your customizations.
Then install, generate, test, and build again. For a slim fork, fetch a
freshly filtered copy of the same release and merge its history using
the identical filter configuration used during bootstrap.
> 
> Recommended update workflow:
> 
> Select a released ZITADEL version and read its release notes and
migration guidance.
> 
> Merge that release into a dedicated update branch.
> 
> Review changes to apps/login, packages/zitadel-client,
packages/zitadel-proto, proto, and the root build files.
> 
> Reconcile dependencies and generated code.
> 
> Run lint, build, unit, and staging end-to-end tests.
> 
> Build an immutable custom image and scan it using your normal
supply-chain controls.
> 
> Deploy to staging, then canary or gradually roll out to production.
> 
> Retain the previous image digest and configuration for rollback.
> 
> Do not merge upstream continuously into production without
qualification. Login changes can affect cookies, redirects, external IdP
callbacks, API contracts, and authentication-policy behavior.
> 
> Recommended release policy for your fork
> 
> ZITADEL releases are the upstream input; your custom Login UI image is
your own release artifact. A useful version format is:
> 
> <upstream-zitadel-version>-custom.<revision>
> 
> Maintain a short release record containing:
> 
> upstream tag and commit
> 
> custom fork commit
> 
> container image digest
> 
> applicable ZITADEL backend version or tested range
> 
> configuration changes and migrations
> 
> test evidence and known limitations
> 
> Subscribe to ZITADEL releases and security notices. Decide
deliberately which releases to adopt; prioritize security fixes and
changes that affect Login V2 or the APIs it consumes.
> 
> Troubleshooting checklist
> 
> If the Login UI returns an internal error or an authentication flow
redirects incorrectly, verify:
> 
> the PAT is readable and belongs to a user with IAM_LOGIN_CLIENT
> 
> ZITADEL_API_URL is reachable from the Login pod and has no trailing
slash
> 
> the public Login domain is trusted by the ZITADEL instance
> 
> the configured Login V2 base URI exactly matches the public route and
base path
> 
> the ingress sends Login UI traffic to the correct service
> 
> separate-domain deployments set the public-host and instance-host
headers correctly
> 
> the selected Login source, client package, proto package, and ZITADEL
API version were tested together
> 
> external IdP callback URLs reach the expected public endpoint
> 
> the prior known-good image and configuration can still be restored
> 
> Related documentation
> 
> Login App architecture and setup
> 
> Contribute to the Login UI
> 
> Connect your self-hosted Login UI to ZITADEL
> 
> Adopt Login V2 on an existing installation
> 
> ZITADEL releases

### ⚠️ Manual Action Required
> **Sidebar Update Needed:** Because this PR creates a brand new
document, it will not automatically appear in the site's navigation.
Please review the file location and manually update
`apps/docs/lib/sidebar-data.ts` to include a reference to this new page
before merging.

---
🤖 **Need adjustments?**
Leave a comment below and tag **@zitadel-knowledge-bot** with your
requested changes, and I will automatically update the files and push a
new commit!

---------

Co-authored-by: zitadel-knowledge-bot[bot] <296006658+zitadel-knowledge-bot[bot]@users.noreply.github.com>
Co-authored-by: Matías Racedo <[email protected]>
Co-authored-by: Copilot Autofix powered by AI <[email protected]>
2026-08-27 17:13:04 -03:00

1092 lines
36 KiB
TypeScript
Raw Blame History

// --- 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",
],
},
],
},
] 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[] = [];
Reference in New Issue View Git Blame Copy Permalink