Map Email Address's Value in the SAML NameID Field in Auth0

Last Updated: Sep 30, 2026

Overview

When using Auth0 as the identity provider (IdP) for a Service Provider (SP) such as a Learning Management System (LMS), the Security Assertion Markup Language (SAML) assertion defaults to mapping the user ID in the Subject's NameID field. This occurs because Auth0 processes the default nameIdentifierProbes array in a specific order, prioritizing the user ID. Configure the nameIdentifierProbes array in the SAML2 Web App settings to map the user email address to the NameID field instead.

The goal is to output the following email address format:

<saml:Subject>
<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">test@test.com</saml:NameID>
...redacted
</saml:Subject>

Instead of the default user ID format:

<saml:Subject>
<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">auth0|636172fecba08c63c2XXXXXX</saml:NameID>
...redacted
</saml:Subject>

Applies To

Auth0
Learning Management System (LMS)
Auth0 as IdP
SAML2 Web App Addon
NameID Mapping

Cause

By default, Auth0 evaluates the attributes of the nameIdentifierProbes array in a specific order when the array is not explicitly declared in the SAML2 Web App settings. Auth0 uses the first attribute with a value for the Subject/NameID.

The default evaluation order is:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier (mapped from user_id).
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress (mapped from email).
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name (mapped from name).

Solution

How is the email mapped to the NameID field?

In the default mappings object, Auth0 maps the user ID to the NameIdentifier claim type and uses it first for the Subject's NameID attribute. Override this behavior by configuring the nameIdentifierProbes array in the SAML add-on settings to prioritize the email address.

Update the SAML2 Web App settings with the following JSON configuration to map the email address to the NameID field.
```
  "nameIdentifierProbes": [
         "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    ]
```

Configure fallback claim types in the array to ensure the NameID claim uses the next available value if the user lacks an email address.

"nameIdentifierProbes": [
         "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
         "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
         "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
    ]

Review the following example of the configured nameIdentifierProbes array in the SAML2 Web App settings dashboard.

saml2-web-app-settings