Zitadel SSO and identity provider federation guide

How to set up Zitadel SSO for apps and upstream identity providers

If you need one login layer for several applications, and some customers or staff already sign in through Entra ID, Okta, Google or LDAP, Zitadel can register your apps over OIDC or SAML and broker login to those upstream providers, including a different provider for each customer organization. The configuration itself is not the hard part. The hard part is making every application trust the right identity, in the right organization, for the right user, and then proving that the failure paths behave as designed.

Start by listing each application as a client in a project, then decide per application whether it uses OIDC (with the authorization code flow and PKCE for browser and mobile clients) or SAML 2.0. Each client needs exact redirect URIs. Wildcards and loose logout URIs are a common source of token leakage, so record the production, staging and local URIs in your design document and review them with the application owner. Confirm in the current Zitadel documentation which grant types and token settings each application type can use before you commit to a pattern.

Claim mapping is where most federation projects stall. An upstream provider such as Entra ID, Okta or Google sends its own attribute names, and some send email addresses that are not verified or are reused across tenants. Decide which upstream attribute becomes the stable link to a Zitadel user, how the email and display name are mapped, and what happens when a user's email changes at the source. Write the mapping as a table, test it with at least one account per provider, and confirm that roles or groups from the upstream provider are not granted automatically unless you intend that behavior. For LDAP, confirm the search base, bind account and attribute names with the directory team before you build anything.

Which Zitadel objects handle SSO and federation

Single sign-on and federation in Zitadel depend on a small set of objects, each set at a different level and owned by a different team. Knowing where each one lives tells you who can change a login path, who can grant access, and what a change in one place affects elsewhere.

Instances as isolated tenants

An instance is the top-level tenant in Zitadel, documented as a virtual tenant with full data isolation. Settings made at instance level apply to everything beneath it, and users, organizations and identity providers in one instance cannot see another's. Decide early whether you need one instance per environment, per business unit or per customer, because splitting or merging instances later is a migration project, not a configuration change. Confirm the isolation model against the current Zitadel documentation before you finalize the design.

Organizations hold users and identity providers

Organizations sit inside an instance and are where users and most projects live. An identity provider added to an organization is available only to that organization's login flow, which is how a single instance can send one customer to Entra ID and another to Okta. Ask which team will administer each organization, since organization administrators can change login options for their own users without touching the instance.

Instance-level identity providers

An identity provider configured at instance level is shared across organizations in that instance. This suits a workforce provider used by every internal organization, such as one corporate directory. The trade-off is blast radius: a misconfigured or rotated instance-level provider affects every organization that depends on it, so keep its ownership with the platform team and document who approves changes.

Projects group applications, roles and grants

A project groups the applications, roles and grants that belong to one product or service. Roles define what a user may do inside that project, and grants assign those roles to users or to other organizations. Cross-organization access depends on project grants, so a customer organization can only use a role that has been granted to it. Map each project to one accountable owner before you register applications.

OIDC and SAML application clients

Applications are registered inside a project as OIDC or SAML clients. Zitadel implements OpenID Connect, OAuth 2.0 and SAML 2.0, so the client type must match what the relying application expects. Redirect URIs, allowed grant types and token settings are set per application, and a mismatch is the most common cause of failed sign-in after go-live. Record each client's protocol, redirect URIs and owner in your inventory so changes go through review.

Upstream identity provider types

Zitadel can federate login with Google, GitHub, GitLab, Apple, Entra ID and Okta over OIDC or SAML, plus LDAP, OpenLDAP, Keycloak, JWT providers and any OIDC-compliant provider. Each provider type has its own required claims, attribute mappings and trust settings, so confirm the exact configuration fields against the identity providers documentation for the version you deploy. Test attribute mapping with real accounts from each upstream source before routing customers to it.

Which login model fits each application and customer

This table compares the five login decisions that shape a Zitadel SSO rollout: protocol per application, upstream identity provider per customer, federated or local accounts, direct LDAP or a bridge, and provisioning method. Read each row for when the option fits and what ongoing work it creates. The main takeaway is that federated options shift some maintenance to customer IdP administrators, so confirm edge cases with Zitadel before you commit.

Decision	When it fits	Operational cost to plan for
OIDC or SAML per application	OIDC for modern web and mobile apps. SAML for applications that only accept SAML assertions.	OIDC clients need redirect URI and secret management. SAML needs certificate and metadata upkeep on both sides.
One shared upstream IdP	A single workforce directory or one customer population that uses the same identity provider.	One metadata set and one set of certificates to rotate. Changes affect every application at once.
One upstream IdP per customer organization	Customers that require their own Entra ID, Okta or other identity provider. Zitadel supports a different provider per organization.	Each customer adds metadata, redirect URIs and a contact who administers their IdP. Support load grows with each customer.
Federated login	Customers or staff whose identities are already governed by their own identity provider.	Depends on upstream availability and claim mapping. Customer IdP changes can break login without notice to you.
Local Zitadel accounts	Partners, pilot users or customers with no identity provider of their own.	You own password resets, account recovery and MFA or passkey support for these users.
Direct LDAP or OpenLDAP	A directory on your network that cannot be fronted by an OIDC or SAML provider. Zitadel documents LDAP and OpenLDAP support.	Needs a network path, a bind account whose credentials you rotate, and checks on TLS and group handling. Confirm edge cases with Zitadel.
OIDC or SAML bridge in front of LDAP	A directory that a supported bridge or upstream provider can expose over OIDC or SAML.	Adds a component to patch, monitor and secure. Confirm which bridge and claim behavior your directory needs.
Just-in-time user creation	Access is driven by login, and the user record can be created at first sign-in.	Accounts for users who left upstream remain until changed or removed. Plan a separate deprovisioning step.
SCIM v2 provisioning	Customer IdPs must push create, update and deactivate events into Zitadel automatically.	Requires token issuance and rotation on the customer side and periodic reconciliation. Confirm supported SCIM operations and attributes with Zitadel.

How to federate Entra ID, Okta or Google into Zitadel

This sequence connects an upstream identity provider to a Zitadel organization and then to the applications that depend on it. It moves from the organization and project through provider registration, callback trust, claim mapping and application registration, ending with per-organization routing and optional LDAP directories. Each step closes with a check you can run yourself.

Create the organization and project
Create the Zitadel organization that will own this federation, then add a project to hold the applications and roles that federated users will access. Your platform or identity team does this in the Zitadel console or through the API, so confirm the instance and naming conventions before you start. Keep one organization per customer or business unit if each may later use its own identity provider. The check is that the organization and project appear in the console and that an administrator with rights in that organization can open both.
Register the upstream identity provider
In the organization, add the upstream provider and choose its protocol. Use OIDC for Entra ID, Okta or Google, or SAML 2.0 where the provider and your applications require it. For OIDC, enter the client ID and client secret created in the provider's admin portal. For SAML, supply the provider's metadata. Confirm issuer and endpoint values in the provider's own documentation, because tenant-specific values differ between customers. The check is that the provider appears in the organization's list with the expected issuer and that Zitadel accepts the configuration without validation errors.
Configure the callback URL at the provider
Copy the redirect (callback) URL that Zitadel displays for the provider and register it in the upstream application exactly as shown, including scheme, host, path and trailing slash. Upstream providers reject sign-ins when the redirect URI does not match a registered value, so this is the most common first failure. Also confirm which scopes the upstream app must release, such as openid, email and profile, and grant admin consent where the provider requires it. The check is a test login started from the Zitadel login page that reaches the upstream sign-in screen and returns to Zitadel without an error.
Map claims to Zitadel user attributes
Decide how upstream claims map to Zitadel user fields: email, given name, family name, and any group or role claim your authorization model needs. Configure the mapping so these claims populate the user on first login. Group and role claims are handled differently by each provider, so confirm the claim name and format in the provider's documentation before relying on them. The check uses a test user: after sign-in, the user record in Zitadel should show the expected email and name, and a decoded ID token or SAML assertion should contain the claims you mapped.
Register the downstream application
Create the application that will use Zitadel for sign-in inside the project. Choose OIDC with the authorization code flow and PKCE for web and single-page applications, or SAML 2.0 for applications that only support SAML. Set the redirect URIs, allowed logout URIs and the role grants users need. Store client secrets in your secret manager, not in application configuration files. The check is a full sign-in through the application: it should receive tokens, and the ID token or SAML response should include the federated email and the roles you granted.
Enable the provider for the organization
Turn on the upstream provider for the organization and set the login policy so users reach it. Decide whether users choose a provider on the login page or are sent directly to one. Then create a second test organization with a different provider to confirm that each login page offers only its own providers. The check has two parts: a user in the first organization signs in through its provider, and a user in the second organization sees only the second provider's option.
Connect LDAP or OpenLDAP directories
If users live in an LDAP or OpenLDAP directory, add it as an LDAP provider in place of a cloud provider. Zitadel must reach the directory over the network, so confirm that the Zitadel deployment can open connections to the directory host and port and that firewalls and certificate chains between them are allowed. Create a bind account with read rights to the user search base and to every attribute you map, and store its password as a secret. The check is a test login with a directory user, confirming that the expected attributes appear on the created user.

How federation differs for SaaS providers, LDAP and per-customer IdPs

Entra ID, Okta and Google are cloud identity providers that Zitadel can federate with over OIDC or SAML 2.0. The setup happens in two places: the provider's application registration, which trusts Zitadel as the relying party, and Zitadel's identity provider configuration, which holds the provider's endpoints and either client credentials or SAML metadata. Browsers carry the redirects, so the work centers on public URLs and trust settings rather than opening inbound paths into the client network.

Protocol choice: OIDC uses a client ID and secret and is often quicker to configure. SAML requires exchanging metadata and agreeing on attribute mappings. Confirm which protocol the customer's tenant administrators can support.
Callback URLs: The Zitadel callback address must match the provider registration exactly, including scheme, host and path. A mismatch is a common cause of the first failed login.
Reachability: Users' browsers must reach Zitadel's external domain, and Zitadel must reach the provider's discovery or metadata endpoints. Egress rules in regulated networks often block these calls.
What the customer supplies: The tenant or domain identifier, an application registration with credentials or SAML metadata, the scopes or claims the application needs, and a named administrator who can approve consent.
Usual failure points: Expired client secrets, clock skew that invalidates SAML assertions, unverified email domains, and existing local accounts that raise questions about account linking.

Before scheduling a test login, confirm the callback URLs, metadata validity and secret expiry dates with the customer's provider administrator.

What drives SSO integration effort and cost

This table lists the main drivers of Zitadel SSO integration effort and cost, and how each one changes the work. Read each row as a question to answer before build starts, since most overruns trace back to unclear protocols, claims or customer responsibilities. The main takeaway is that the scope, attribute contract and customer tasks should be written down before anyone configures an identity provider.

Driver	How it raises effort or cost	How to keep it down
Number of applications and protocols	Each OIDC or SAML client needs its own redirect URIs, claims, roles and test cycle, so effort grows with every protocol variant.	Standardize on OIDC for new web and mobile apps, and use SAML only where a vendor requires it.
Customer organizations with their own identity providers	Each organization needs its own IdP connection, attribute mapping and login test, multiplying configuration and support work.	Template the federation setup per IdP type and onboard customers in batches with a written checklist.
Quality of upstream claims and group data	Missing email verification, inconsistent names or unmapped groups force custom mapping and Actions logic in Zitadel.	Agree an attribute contract with each customer before build, naming the claims, group values and required fields.
Network reachability to LDAP or private IdPs	LDAP and private IdPs need open routes, trusted certificates and bind accounts reachable from Zitadel, often through firewall change windows.	Confirm connectivity, the TLS trust chain and bind accounts in the test environment before scheduling build work.
Environments (development, staging, production)	Each environment repeats instance, IdP and client setup, and secrets and redirect URIs differ between them.	Confirm which parts your team can manage as code, such as Terraform configurations, and promote changes through the same steps everywhere.
Customer IdP administrator availability	Federation testing waits on the customer's IdP administrator to create apps, grant consent and provide test accounts, which can stretch the schedule.	Ask each customer to name an IdP administrator and a test user before the schedule is agreed.
Need for SCIM provisioning	Automated user creation, updates and deactivation need a SCIM v2 setup, mapping rules and reconciliation tests on both sides.	Decide per application whether just-in-time login is enough or whether SCIM is required, and scope SCIM as a separate item.
Quote line items	Cost splits across internal staff, partner fixed-scope work and customer IdP administration, and each has a different owner.	Request a written quote listing each application, organization, IdP, environment and who performs each task.

Securing redirect URIs, trust material and claim mapping

Most SSO incidents in identity platforms trace back to a small set of trust decisions: where tokens may be sent, which secrets and certificates prove identity, and which upstream claims are allowed to grant access. The cards below cover those SSO-specific controls for a self-hosted Zitadel deployment. General platform hardening is covered in the security hardening guide.

Register exact redirect URIs

Each OIDC and SAML application in Zitadel should have its redirect URIs registered exactly, with no wildcards and no shared callback paths across applications. Check scheme, host, port and trailing slash, and separate development and production URIs. A loose redirect URI lets an attacker receive authorization codes or tokens, so review the list whenever an application is added, moved or retired.

Minimize requested scopes

Configure each client so it can request only the OpenID Connect and custom scopes it needs, such as profile and email, and nothing broader. Review which claims and roles end up in the ID token and access token for each application. Applications that receive more claims than they use widen the impact of a leaked token, so confirm the scope list with the application owner before go-live.

Protect client secrets and the LDAP bind account

Store client secrets for confidential applications in a secrets manager, not in configuration files or source control, and rotate them on a schedule and after staff changes. If you federate with LDAP or OpenLDAP, the bind account should be a read-only service account limited to the user search base and the attributes Zitadel needs. Confirm with your directory team which group and password policy applies to that account.

Rotate SAML signing certificates and metadata

SAML federation depends on signing certificates and IdP metadata that expire or change. Record the expiry date of each certificate used with Entra ID, Okta or another SAML provider, and schedule rotation before it lapses. After rotation, refresh the metadata in Zitadel and test a sign-in for each affected organization. Ask the upstream provider how it publishes new certificates and whether it keeps the old one valid during overlap.

Validate issuer and audience

Every application and API that accepts tokens from Zitadel should check the issuer and the audience claim against the expected values for that environment. Confirm that a token issued for one project or application is rejected by another, and that issuer values differ between staging and production. Resource servers that skip these checks will accept tokens meant for a different client, so include this in each integration test.

Control which claims grant roles

When an upstream identity provider sends group or attribute claims, Zitadel's action and role mapping decides which of them set project roles or organization membership. Only map claims that the upstream provider controls tightly, and avoid mapping free-text fields users can edit. Document each mapping rule and review it when the upstream directory changes, because a single new group can grant access to an entire organization.

Restrict sign-in per organization

Each customer organization can federate with its own identity provider, so set the allowed login methods and identity providers per organization rather than instance wide. Decide whether unknown users may self-register through a federated provider, and whether domain matching is enforced. Test that a user from one organization cannot sign in through another organization's provider, since that boundary is the main tenant isolation control for SSO.

How to test federated login and confirm it fails safely

Write down the expected result for every test case before anyone clicks through a login. A federation test is only useful if the team can say, in advance, what a correct outcome looks like: which Zitadel instance and organization should handle the request, which application should receive the token, which roles should appear in it, and what the user should see on failure. Without a written expectation, testers tend to accept whatever the first run shows, and misconfigurations that grant slightly too much access pass unnoticed. Keep the plan in a shared document that names the identity provider, the Zitadel organization, the project and each application under test. Start with the successful paths. Run a login for each application in each organization that will use federation, including a user who signs in for the first time so that Zitadel creates the local user record from the upstream claims. For each login, check the issued tokens or the SAML assertion attributes against the mapping you defined. Confirm that email, name and any custom attributes land where expected, and that project roles granted to the user match the grants in the target organization and nothing more. Repeat the check with a user who has no role grant to confirm that signing in alone does not confer access. Also test sign-out: end the session in the application, then confirm that a new login attempt requires upstream authentication again, and check how the session behaves after the upstream account is disabled. The negative cases matter as much as the positive ones. Cover an expired or revoked upstream account, a redirect URI that does not match the registered value, a signing certificate that differs from the one configured for the SAML or OIDC connection, and a user from an email domain that is not listed for the organization. Each of these should end in a denied login, with no session and no access token issued to the application, and with a log entry that an administrator can find. Confirm the exact log fields and the retention period with your own operations team, and verify them during the test rather than assuming Zitadel records them the way you expect. Record the observed result beside the expected one for each case. Some test plans stop at the vendor's documentation. Treat your own test results as one input, not as assurance. Independent testing of the resulting system, including attempts to bypass federation or abuse the login flow, is a separate engagement and should be scoped and written down on its own terms. Confirm with your security owner whether that testing is required before go-live and how its findings will be tracked against this plan.

What to monitor, rotate and document after SSO goes live

Go-live is where federation starts to drift. Upstream identity providers rotate keys, change claims and update tenants, and Zitadel itself moves to new releases. The work below keeps those changes visible, and the documents listed here let your own team or a later partner run the environment without rebuilding it from memory.

Monitor failed logins by organization

Failed logins and token errors should be tracked per Zitadel organization as well as across the instance, because each customer organization may use a different identity provider with its own failure modes. Set alerts on spikes in failed upstream callbacks, rejected tokens and login errors for each organization, and agree in advance who responds to each alert. Review trends weekly during the first months after go-live, since early problems often appear in one tenant before they spread to others.

Track upstream certificate and secret expiry

Each federated provider carries credentials that expire, including SAML signing certificates, OIDC client secrets and any keys used to verify provider tokens. Record the expiry date, owner and renewal path for every provider in the register, and set reminders well ahead of each date. Confirm with each upstream administrator how they will publish a replacement certificate, because an expired credential breaks login for every organization using that provider at once.

Review claim mappings after upstream changes

Upstream teams often rename attributes, restructure groups or change token contents without notifying downstream applications. Compare each provider's mapped claims against the claim contract after every upstream change, including tenant changes in Entra ID or Okta and group renames. Confirm that email, subject and role claims still map to the same Zitadel attributes, then rerun a login test with one user per role to verify the result.

Upgrade on the v4 line and retest

Zitadel v4.19.5 was released on 15 October 2026, and self-hosted deployments should follow the v4 line on a planned schedule. Each upgrade can change login behavior or database migrations, so apply it to a staging instance first and repeat the federation tests for every provider and organization. Check the PostgreSQL version against the supported range of 14 through 18 before and after the upgrade, and read the release notes for each version you move through.

Keep the application and provider register

The register records which applications and organizations use which protocol, OIDC or SAML, and which identity provider they rely on. It should also hold client IDs, redirect URIs, owners and environments for each entry. Update it in the same change request that adds or alters an application, provider or project grant. Without it, a certificate expiry or provider outage cannot be traced quickly to affected applications, and an upgrade test cannot be scoped correctly.

Hand over runbooks and test evidence

Hand over the application and provider register, the claim contract, runbooks for identity provider outages and certificate rotation, and the test evidence from go-live and each later retest. The outage runbook should state how users in each organization are affected and who can enable fallback login. Version the test evidence against the Zitadel release that was tested, so the next team can see what was verified and when.

Questions teams ask before scoping SSO with Zitadel

How much effort does an SSO integration with Zitadel take?

Effort depends mainly on how many applications need to connect, which protocol each one uses, and how many identity providers must be federated. A single OIDC application pointed at one upstream provider is a small piece of work. A set of SAML applications, several federated providers and custom login rules takes considerably more. Each application needs its redirect URIs, client settings, roles and grants configured and tested. Each federated provider needs its own trust setup, attribute mapping and test sign-in. Ask any partner to break the estimate down by application, by provider and by test cycle, so you can see which items you could take on yourselves.

How long does an SSO integration project usually take?

The duration depends on the scope written into the agreement, not on a standard figure. The number of applications, protocols, identity providers, environments (for example test and production) and the number of approval rounds all change the timeline. DeployOpen agrees timelines in writing as part of a fixed-scope engagement, before work starts, so the schedule reflects the deliverables you have approved. When you request a proposal, ask for milestones tied to each application and each provider, and for the dependencies on your side, such as administrator access and test accounts.

What does the client need to provide for an SSO project?

Most delays come from client-side inputs, so gather them early. You will typically need administrator access to each upstream identity provider (for example Entra ID, Okta, Google or an LDAP directory), its federation metadata or equivalent configuration, a set of test accounts that cover your user types and roles, and access to the applications being connected. You also need a named approver who can accept configuration decisions, such as attribute mappings and which organizations may sign in through which provider. Confirm with your identity team who holds each of these before scoping starts.

Can an internal team set up Zitadel SSO without a partner?

Yes, a capable internal team can do this with the Zitadel documentation, provided it can do three things reliably: test federated sign-in end to end, including failure cases, handle the SAML and OIDC settings of each upstream provider, and rotate trust material such as signing certificates and client secrets before they expire. Teams without recent experience with these protocols usually find the testing and rotation steps take the most effort. If your team lacks one of these skills, a partner can cover that part while your staff keep ownership of the configuration.

How do per-organization identity providers change the work?

Per-organization identity providers multiply the configuration and testing. Zitadel lets each customer organization use a different identity provider, so each organization needs its own provider settings, its own attribute and role mapping, and its own sign-in tests. You also need clear rules for which organization owns which provider, how new organizations are onboarded, and who can change those settings. The design of instances, organizations and projects affects this directly, so settle that model before connecting providers. Ask for the onboarding steps for a new organization to be documented as part of the deliverables.

What does a fixed-scope SSO engagement from DeployOpen include?

A fixed-scope engagement covers the work listed in a written statement of scope, along with the deliverables and timelines agreed before work starts. Typically this means reviewing the target design, configuring the agreed applications and identity providers, testing sign-in paths, and handing over documentation for your team. It does not include work outside the agreed scope unless both parties change the written scope. DeployOpen does not publish a price list, so a quote follows from the written scope. Ask for the list of applications, providers and test cases included, and for the handover items you will receive.

Which Zitadel protocols and identity providers does the integration cover?

Zitadel implements OpenID Connect, OAuth 2.0 and SAML 2.0 for applications, so the integration must match each application to one of these. For upstream federation, Zitadel can connect to Google, GitHub, GitLab, Apple, Entra ID and Okta over OIDC or SAML, to LDAP and OpenLDAP, to Keycloak, to JWT identity providers and to any OIDC-compliant provider. Confirm with your team which of these providers your users actually need, and check each provider's current configuration requirements with its vendor, since those settings change over time.

How DeployOpen scopes, builds and hands over Zitadel SSO work

DeployOpen plans, builds and supports Zitadel SSO and identity provider federation inside your own infrastructure, whether that is a cloud account, data center or air-gapped network. Each engagement starts with a written, fixed scope that names the applications, protocols and identity providers involved. Work moves from design to testing, documentation and handover, with ongoing support available as a retainer.

How we scope

The written scope lists each application, its OIDC or SAML client, and the redirect and logout behavior it needs.
It names each upstream identity provider (Entra ID, Okta, Google or LDAP) and the organizations that use it.
Engagements are fixed-scope, and ongoing support is available as a retainer after go-live.

How we build

Instance and organization design comes first, so each customer organization can hold its own identity provider connection.
Upstream federation is configured per provider, with claim mapping, attribute handling and login flows tested before cutover.
Test cases cover sign-in, sign-out, token contents, role grants and failure paths, with results recorded in the handover.

How we hand over

Runbooks document each application client, identity provider configuration and the steps to add a new customer organization.
Configuration is kept in version control where practical, so changes to providers and clients can be reviewed.
Your team receives console walkthroughs and a record of where secrets live, with the values kept out of the document.

How we support

Support after go-live can cover monitoring of sign-in failures, certificate and metadata renewals, and identity provider changes.
Zitadel version upgrades are tested against your federated providers before they reach production.
Ongoing support is available as a retainer, and its scope is agreed in writing like any other engagement.