Where Zitadel fits
Zitadel is an identity and access management platform for applications. It issues tokens over OpenID Connect and OAuth 2.0, acts as a SAML 2.0 identity provider, and handles registration, login, MFA and passkeys. Teams usually choose it for customer identity (CIAM) and B2B products, where each customer organization needs its own users, login policy, branding and delegated administrators. It can also give internal applications single sign-on by brokering an existing directory.
An instance is the top-level identity system. Inside it, organizations hold users and policies, projects group applications and roles, and project grants let one organization delegate roles in its project to another. Decide early how customers, partners and internal teams map to these objects; changing the mapping after people have signed in means moving users, grants and role assignments.
Zitadel stores every change as an immutable event in PostgreSQL and builds query views from those events. That gives a built-in audit trail and one clear backup target, and it makes database health the same thing as identity health.
Connect applications and upstream identity
Applications
Register each application with the protocol it supports: OIDC for web, mobile and API clients, SAML 2.0 for older enterprise software, and device authorization for clients without a browser. Record redirect URIs, token lifetimes and the role claims each one reads.
Upstream identity providers
Broker logins from LDAP directories, enterprise identity providers and social logins. For B2B tenants, domain discovery routes users to their company's provider by email domain. Test what happens when the upstream account is disabled.
Machine identities
Service accounts authenticate with JWT profile, personal access tokens or client credentials. Give each one an owner, a scope and a rotation date.
Provisioning and events
Zitadel includes a SCIM 2.0 server for inbound provisioning, and Actions for webhooks and token enrichment. Review every action and webhook target like code, since each can change who gets access.
Choose a deployment topology
Docker Compose with the Zitadel API, the login service and PostgreSQL is enough to model tenants, test integrations and rehearse an upgrade. Use the production hostname pattern so issuer URLs and redirect URIs behave the same way.
The official Helm chart runs Zitadel as stateless replicas behind an ingress, with init and setup as separate steps so new pods start quickly. Size PostgreSQL for connections and write load.
From v4, the hosted Login V2 runs as a separate zitadel-login service. The reverse proxy sends /ui/v2/login to it and everything else to the API. Include it in health checks, scaling and upgrade plans.
Mirror images and the Helm chart into an internal registry, keep SMTP and upstream identity providers reachable inside the network, and decide whether to turn off service ping telemetry (v4 and later).
Settle production settings before go-live
These follow the Zitadel production checklist, plus the settings that are hard to change once tenants exist.
| Setting | Decision | Check |
|---|---|---|
| PostgreSQL | Run a highly available PostgreSQL on a version the target release supports (the current docs list 14 to 18), on an internal network. | A primary failover is tested while users sign in, and connection limits hold under expected load. |
| Masterkey | Generate the masterkey that encrypts sensitive data at rest and keep it in a secrets manager, separate from database backups. | The recovery runbook can retrieve the key without depending on the Zitadel instance it protects. |
| External domain | Set ExternalDomain, ExternalPort and ExternalSecure to the address users and applications reach through the proxy. | Discovery documents and issuer URLs show the public hostname over HTTPS. |
| Edge and TLS | Use a trusted certificate on a fully qualified domain and a layer 7 proxy or WAF with HTTP/2, rate limiting and bot controls. | Browser, gRPC and REST traffic all pass the proxy, and a test client triggers the rate limit. |
Harden the identity plane and prove recovery
Set login policies per organization: required MFA or passkeys, password rules, lockout and session lifetimes. Record which policy each organization inherits and which it overrides. Keep instance administrators in a dedicated organization, and restrict who can create organizations, add identity providers or edit actions. Send audit events to the SIEM the security team already watches.
Back up PostgreSQL with a method that supports point-in-time recovery, and keep the masterkey and configuration with the recovery runbook. The event store is the record that matters most, since projections can be rebuilt from it. A restore test should start Zitadel against the restored database in an isolated network, then sign in as a human user, obtain a token for a test application and authenticate a service account.
Version and license notes that affect a deployment
Confirm each point against the release notes for the exact version you deploy.
| Topic | What to know | Deployment impact |
|---|---|---|
| License | With v3, Zitadel moved from Apache 2.0 to AGPL-3.0. SDKs and API definitions stay under Apache 2.0, and a commercial license is offered. | Zitadel states that organizations using it as their identity platform are not affected. Review AGPL with counsel if you modify Zitadel and offer it to others. |
| Database | Zitadel v3 and later require PostgreSQL and will not start with CockroachDB configured. | Deployments still on CockroachDB must move to PostgreSQL before upgrading to v3. |
| Login UI | v4 made Login V2 the default. Existing installations stay on Login V1 until switched per application or instance. | Treat the login service, proxy routes and branding review as a change of its own. |
| Release tags | Zitadel ships frequent major releases, each preceded by release candidates, and it retired the floating stable image tag. | Pin an exact version tag and test each upgrade on a staging copy of production data. |
Migrate users, clients and tenants in stages
Typical sources are Keycloak, a hosted identity service or an identity layer built into the application. Inventory users, password hash formats, MFA enrollments, identity provider links, clients, redirect URIs and the claims each application reads; role claims differ between products, so code that parses tokens may need changes. Map each source tenant or realm to Zitadel organizations and projects, import users through the API, and plan password resets for hashes your version cannot import and MFA re-enrollment unless factors can be carried over.
Cut over one application at a time. Run the old and new issuers side by side, move a low-risk application first, and keep a rollback path that points the application back to the previous issuer until token validation, session behavior and logout are confirmed.
Zitadel operating ownership
Identity sits in front of every application that uses it, so name owners for the platform, the tenants and the integrations.
Platform team
- Runs Zitadel, the login service, PostgreSQL and the proxy.
- Pins versions and rehearses upgrades and restores.
- Watches database connections, latency and errors.
Identity administrators
- Create organizations and apply login policies.
- Approve identity providers and domain discovery entries.
- Handle delegated administrator requests.
Application teams
- Register clients with exact redirect URIs and minimal scopes.
- Validate tokens and role claims, and implement logout.
- Own and rotate their service account credentials.
Security
- Reviews administrator roles, actions and webhooks.
- Alerts on policy changes from audit events.
- Protects the masterkey and backups.
Zitadel deployment questions
Should each customer get an organization or an instance?
Organizations are the usual unit for B2B tenants inside one instance. Each can have its own users, policies, branding and identity providers. Separate instances add stronger separation and separate administration, with more objects to operate. Choose based on how much isolation contracts and regulators require.
What proves a restore worked?
Zitadel starts against the restored database with the original masterkey, a test user signs in with MFA, an application receives a valid token, a service account authenticates, and audit events are present up to the recovery point.
Can Zitadel run in an air-gapped network?
Yes, with images mirrored internally and SMTP, SMS and identity providers reachable inside the network. Turn off service ping and review any action or webhook that calls an external endpoint.
Scope and handover
Effort depends on the number of tenants and applications, upstream identity providers, the migration source and its password formats, availability targets, the PostgreSQL platform and whether the network allows outbound access. Tenant design and application cutover usually take more time than installing Zitadel.
DeployOpen plans the tenant model, deploys Zitadel, the login service and PostgreSQL in your environment, hardens the edge and administration, integrates identity providers and applications, sets up backups, tests a restore and documents upgrades. Handover includes the configuration repository, organization and policy map, client register, service account inventory, restore test record and support route.
