Issue linking existing user with SAML IdP (External User Not Found)
Hi 👋,
I’m having an issue with SAML login and automatically linking an external user to an existing Zitadel user.
Problem
When logging in through a SAML IdP:
- We are correctly redirected to the IdP login page.
- Authentication succeeds.
- But when redirected back to Zitadel, we get the error: External User Not Found.
What we tried
- Tested all possible IdP configurations in the console.
- Tried linking the external user to the Zitadel user via email (both automatically and manually).
Our goal
- Create a user via the API.
- Send them an invitation code via the API.
- The user completes their account setup.
- When they log in via the SAML IdP, their external account should be automatically linked to their Zitadel account.
👉 This works correctly with OpenID Connect, but not with SAML.
Is this the expected behavior with SAML? Or is there a specific configuration needed to make the linking by email work?
6 Replies
Hi @Shengael, I'm an AI assistant for ZITADEL. While a team member reviews this question, I'll see if I can find relevant sources for your question.
Answer
This appears to be related to a known SAML implementation issue in ZITADEL. Based on the documentation, there are specific configuration options for SAML identity providers that control automatic linking behavior (1) .
For SAML IdP configuration, you can set the
-
autoLinking option to AUTO_LINKING_OPTION_EMAIL to enable automatic linking based on email addresses (1) (2) . The available options are:
- AUTO_LINKING_OPTION_UNSPECIFIED (default)
- AUTO_LINKING_OPTION_USERNAME
- AUTO_LINKING_OPTION_EMAIL (1)
However, there's a documented issue with SAML that may explain your problem. ZITADEL uses the Subject NameID element from the SAML response as the external user ID (3) . If your SAML IdP uses transient Name IDs (urn:oasis:names:tc:SAML:2.0:nameid-format:transient) , this can cause "User already exists" errors because the NameID changes between logins while the username remains the same .
Additionally, there's a reported issue where ZITADEL requests transient Name IDs by default in SAML requests, which can lead to linking problems even when the IdP supports persistent Name IDs .
The key SAML provider options you should verify are set correctly (1) :
- isAutoCreation: Enable automatic account creation
- isAutoUpdate: Enable automatic profile updates-
autoLinking: Set to AUTO_LINKING_OPTION_EMAIL
- isLinkingAllowed: Enable manual linking c
apability
If the issue persists, click the "Ask for help" button to tag a team member, as this may require investigation of your specific SAML IdP's NameID format implementation.
​
To learn more, see the sources I considered:
[1] Add SAML Identity Provider
[2] Get identity provider (IdP) by ID
[3] Ability to use a SAML attribute as the external user ID
​
Feel free to tag @Ask Inkeep with additional questions.Hi,
We discovered a working configuration to automatically link an external SAML user to an existing Zitadel account, using the JavaScript action snippet shown at the end of Zitadel’s documentation:
https://zitadel.com/docs/guides/integrate/identity-providers/mocksaml#optional-add-zitadel-action-to-autofill-userdata
At first, I thought this script was only for pre-filling the registration form, but it also enables automatic linking of the external user—exactly what we needed.
I see two issues I’d like some clarity on:
- Why is this script marked as optional in the documentation? It seems crucial for automatic linking—so is there an alternative configuration path, or a scenario where this script really isn't needed?
- The current solution is for Actions v1. In Actions v2, I can't find a way to attach scripts to the "External Authentication" flow with a "Post Authentication" trigger. What is the migration path for this functionality? Will that be supported soon in v2?
ZITADEL Docs
MockSAML is not intended for any production environment, only for test purposes
Got it. Tagging @Rajat for additional help.
You should be able to handle that in Actions V2 with a REST call on the response of UserService.RetrieveIdentityProviderIntent
hey @Luis VALDEZ this is the example @Arnau is talking about https://zitadel.com/docs/guides/integrate/actions/testing-response-manipulation
Glad I could be helpful. Feel free to create a new thread with any new questions you may have.