Account linking
ZITADEL supports linking user accounts from different external identity providers, such as social logins or enterprise IdPs, to a single ZITADEL user profile. This enables users to be recognized as the same user in your applications, regardless of which external account they use to log in.
Each user in ZITADEL has one account for streamlined access management and a unified audit trail. Multiple external identities can be linked to this account.
Advantages​
- Users can log in with several identity providers without maintaining separate profiles
- Already registered users can link additional external profiles
- Provides backup authentication methods if an IdP is unavailable
- Enables unified auditing across all linked identities
How it works​
Account linking is controlled by your organization and identity provider configuration.
When external identity providers (such as social logins or enterprise SSO) are configured, a user account is created in ZITADEL, and the external identity is linked to the ZITADEL account.
Important: If a user account in ZITADEL is already linked to an external identity and the user enters their username during login, ZITADEL will automatically redirect to the linked external identity provider for authentication.
There is no choice presented to the user between authenticating with local username/password and an external IDP once accounts are linked.
Only if the external login fails (for example, due to an expired or invalid IDP secret), will ZITADEL fall back to local authentication.
Users are only shown options to pick local login or possible external IDPs during registration—that is, only when there is no existing account. For existing accounts that are linked to an external IDP, the system determines the authentication method automatically.
If only one external identity provider is configured and username/password login is disabled, all authentication requests are immediately redirected to the external provider.
In cases where a local account exists and a user registers or logs in through an external identity provider, ZITADEL can be instructed to link the new external identity to the local account based on matching criteria (such as email address or username).
Automatic account linking​
You can configure your identity provider to allow automatic account linking for users with the same email or username.
To enable this, set "Account linking allowed" in the identity provider template settings.
Automatic account linking helps users associate multiple login options with their ZITADEL account, offering flexibility—however, at login, the authentication method will be determined by the link, not by user choice.