External SAML IdP integration - multiple issues

Hello,

Using Zitadel v4.2.0 - we are trying to enable an external SAML IdP. We are encountering a number of issues and the documentation doesn't seem to be helping much. The metadata has been uploaded, and the SAML is activated at the instance level.

The two main issues:

Account auto-linking doesn't seem to work, or I don't know where to enable it. Either the account creation form is shown, or an error message is displayed if I disable manual account creation.
```
NameID Format
```
NameID Format
```
NameID Format
```
NameID Format
is set to
```
SAML_NAME_ID_FORMAT_EMAIL_ADDRESS
```
SAML_NAME_ID_FORMAT_EMAIL_ADDRESS
```
SAML_NAME_ID_FORMAT_EMAIL_ADDRESS
```
SAML_NAME_ID_FORMAT_EMAIL_ADDRESS
, but Zitadel doesn't appear to be making use of the
```
NameID
```
NameID
```
NameID
```
NameID
provided by the IdP. When looking at the request, the SAML subject is provided as shown below. I would assume Zitadel would be able to match it to the user with the same email address?

        <saml2:Subject>
            <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">MY_EMAIL_ADDRESS_CENSORED</saml2:NameID>
            <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml2:SubjectConfirmationData InResponseTo="id-9ffd9eb8d643d94c3d0437e5c2365b0ca998ca27"
                                               NotOnOrAfter="2025-10-27T17:02:53.241Z"
                                               Recipient="https://MY_ZITADEL_INSTANCE/ui/login/login/externalidp/saml/acs"
                                               />
            </saml2:SubjectConfirmation>
        </saml2:Subject>

        <saml2:Subject>
            <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">MY_EMAIL_ADDRESS_CENSORED</saml2:NameID>
            <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml2:SubjectConfirmationData InResponseTo="id-9ffd9eb8d643d94c3d0437e5c2365b0ca998ca27"
                                               NotOnOrAfter="2025-10-27T17:02:53.241Z"
                                               Recipient="https://MY_ZITADEL_INSTANCE/ui/login/login/externalidp/saml/acs"
                                               />
            </saml2:SubjectConfirmation>
        </saml2:Subject>

        <saml2:Subject>
            <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">MY_EMAIL_ADDRESS_CENSORED</saml2:NameID>
            <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml2:SubjectConfirmationData InResponseTo="id-9ffd9eb8d643d94c3d0437e5c2365b0ca998ca27"
                                               NotOnOrAfter="2025-10-27T17:02:53.241Z"
                                               Recipient="https://MY_ZITADEL_INSTANCE/ui/login/login/externalidp/saml/acs"
                                               />
            </saml2:SubjectConfirmation>
        </saml2:Subject>

        <saml2:Subject>
            <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">MY_EMAIL_ADDRESS_CENSORED</saml2:NameID>
            <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml2:SubjectConfirmationData InResponseTo="id-9ffd9eb8d643d94c3d0437e5c2365b0ca998ca27"
                                               NotOnOrAfter="2025-10-27T17:02:53.241Z"
                                               Recipient="https://MY_ZITADEL_INSTANCE/ui/login/login/externalidp/saml/acs"
                                               />
            </saml2:SubjectConfirmation>
        </saml2:Subject>

After adding and activating an IdP, would expect to be able to add external identities to users but in the console, there doesn't appear to be a way to do it. The External Identity Provider screen for all users just shows
```
No external IdP found
```
No external IdP found
```
No external IdP found
```
No external IdP found
. I thought this could help with the auto-linking.

Any help would be greatly appreciated, including steps to troubleshoot the auto-linking.

Thanks!

Nicolas

Ask Inkeep•10/27/25, 6:52 PM

Hi @nicjac, 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.

Ask Inkeep•10/27/25, 6:52 PM

Answer

I wasn't able to find a direct answer, here are some relevant sources:

Add SAML Identity Provider : This covers the providerOptionsproviderOptions configuration including autoLinkingautoLinking settings with values like AUTO_LINKING_OPTION_EMAILAUTO_LINKING_OPTION_EMAIL which enables prompting users to link existing ZITADEL accounts when the email attribute matches (1) .
Update SAML Identity Provider : Documents the nameIdFormatnameIdFormat field and transientMappingAttributeNametransientMappingAttributeName for handling different NameID formats, plus the autoLinkingautoLinking option within providerOptionsproviderOptions (2) .

The sources show that auto-linking is configured through the autoLinkingautoLinking field in providerOptionsproviderOptions, which can be set to AUTO_LINKING_OPTION_EMAILAUTO_LINKING_OPTION_EMAIL to match users by email (2) (1) . However, the sources don't explain troubleshooting steps for when auto-linking doesn't work as expected, or how to manually add external identities to existing users through the console.

For your specific v4.2.0 configuration issues and the console UI behavior you're experiencing, I'd suggest clicking the "Ask for help" button to have a team member review your setup directly.

Ask Inkeep•10/27/25, 6:52 PM

To learn more, see the sources I considered:

[1] Add SAML Identity Provider
[2] Update SAML Identity Provider

Ask Inkeep•10/27/25, 6:52 PM

Feel free to tag @Ask Inkeep with additional questions.

AAsk Inkeep To learn more, see the sources I considered: [[1] Add SAML Identity Provider]...

Ask InkeepAPP•10/27/25, 7:03 PM

Got it. Tagging @Rajat for additional help.

nicjacOP•10/27/25, 7:07 PM

Just to add, I tried setting auto_linkingauto_linking to 22 in the database but no luck

nicjacOP•10/27/25, 7:41 PM

Also weirdly enough, I get this error even though I allow auto linking?

            Neither creation of linking is allowed on this provider. Please contact your administrator. (LOGIN-3kl44)

            Neither creation of linking is allowed on this provider. Please contact your administrator. (LOGIN-3kl44)

nicjacOP•10/27/25, 9:29 PM

Been trying to troubleshoot this for a few days now and I am getting nowhere

Rajat•10/28/25, 1:38 AM

hey @nicjac I will look into it more tomorrow but a quick search in the discord, I see questions-help-bugsExternal User Not Found when trying to auto link SAML Users by Email maybe its related ?. You may need to use actions. Please let me know if that helped.

Rajat•10/28/25, 1:42 AM

also I am not sure how are you adding/linking IDP, but please try it with the API and update the IDP OR Add an IDP again

please let me know if this helps.
Thanks

nicjacOP•10/28/25, 4:38 PM

Hey, I managed to fix it with an action:

let logger = require("zitadel/log");

function setExternalUserInfo(ctx, api) {
  logger.info('hi there :)');
  try {
    const providerInfo = ctx.v1?.providerInfo;
    const attributes = providerInfo?.attributes || {};
    const nameID = providerInfo?.iD;
logger.info(nameID);
    api.setEmail(nameID);
  } catch (err) {
    logger.error("Script error:", err.message);
  }
}

let logger = require("zitadel/log");

function setExternalUserInfo(ctx, api) {
  logger.info('hi there :)');
  try {
    const providerInfo = ctx.v1?.providerInfo;
    const attributes = providerInfo?.attributes || {};
    const nameID = providerInfo?.iD;
logger.info(nameID);
    api.setEmail(nameID);
  } catch (err) {
    logger.error("Script error:", err.message);
  }
}

nicjacOP•10/28/25, 4:38 PM

Seems a bit odd for this to be required though? This is the mapping I set in the IDP configuration, it should automatically use it?