How to Map SAML Attributes when Auth0 is the SP in the SAML Enterprise Connection

ConnectionsSingle Sign-On
Oct 17, 2025
Overview

This article discusses SAML Mapping misconfiguration in the SAML Enterprise Connection. Attribute misconfiguration can result in a number of unexpected behaviors. The following is not an exhaustive list:

  • Auth0 user profile is missing information, or information is in the wrong profile fields.
  • Application fails to sign in the user (returns error)
  • Application signs in the user but doesn’t have user profile information (name, email, etc.)
  • A new user is created in Auth0 every time the user signs in
Applies To
  • Enterprise Connections
Cause
  • The Identity Provider (IdP) does not send the attributes to Auth0
  • SAML attributes are incorrectly mapped to the Auth0 user profile
  • Auth0 is not configured to send the information to the application (e.g. information is missing from id_token or SAML response sent from the Auth0 tenant to the application)
  • SAML IdP is not sending a unique identifier or the wrong attribute is specified for “User ID Attribute” in the Auth0 SAML connection.
Solution

The solution is to map the SAML attributes to the correct property when Auth0 is the Service Provider (SP).

When Auth0 is the SP, the attributes need to be customized in the SAML response from the IdP that are mapped to the user’s Auth0 Profile.

To do so, attributes can be mapped through the SAML Enterprise Connection Settings.

SAML Enterprise Connection:
Configure the mappings by navigating to the Auth0 Dashboard and through the following path:

  1. Authentication
  2. Enterprise
  3. SAML
  4. Custom SAML Connection
  5. Mappings

IMPORTANT:

Note that the mappings defined here will be first in the pipeline to map the attributes. Any attributes not defined in the mappings will then map to the profile as a root-level profile attribute of the same name.

By default, user profile attributes provided by the IdP are updated from the IdP every time the user logs in. This feature can be disabled by toggling OFF “Sync user profile attributes at each login”.

Troubleshooting

If mapping issues are encountered or errors are vague, proceed by using Debug Mode to troubleshoot.

Use Debug Mode:

  1. First begin by Enabling the Debug Mode setting in the SAML Connection.

 

Debug mode 
 

  1. Attempt to sign in to the application using the SAML Connection. Note that a useful log entry may be produced even if the application rejects the sign-in attempt.

  2. On the Auth0 Dashboard, go to Monitoring > Logs. Use the following search string:

  3. Relevant logs will have the description:

    • “Potential private information exposed. Consider disabling Debug Mode for connection as soon as possible”.

    • Open a log entry with the appropriate timestamp from the sign-in attempt.

  4. Look for the details.original_profile property. It will be a JSON object with some escaped characters and should be something like the following:

    {\"sessionIndex\":\"_rjlrdjCyoabjG5UlAWB1O8a-ZEdIAVvt\",
\"attribute1\":\"somedata\",
\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn\":\"ac122436f210d\",
\"authenticationmethod\":\"urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified\",
\"nameIdAttributes\":{\"value\":\"somevalue",
\"Format\":\"urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified\"},
\"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier\":\"some_user_id\",
\"issuer\":\"https://example.com/mysamlidp\"}

    • Readability is unfortunately poor, but it will be clear from this data what attributes Auth0 is receiving from the SAML IDP.

     

  5. If there are no "w" type logs, then Auth0 is not receiving the SAML response. In the diagram below, Auth0 receives the SAML response in step (5). If Auth0 does not receive the SAML response, it is recommended to review the configuration of the SAML IdP, and in particular to confirm the correct ACS URL is configured. This document does not apply to situations where Auth0 is not receiving a response from the SAML IDP.

 

IdP Initiated SAML Flow

 

Example Cases:

Case 1: Default Mappings

When creating the Auth0 SAML Connection, there are default mappings configured by default. In that case, attributes in the SAML Response like http://schemas.auth0.com/locale translate to root-level profile attributes with the same name (locale).

Default Mappings:

{
"user_id": [
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
],
"email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
"name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
"given_name": [
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
],
"family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
"groups": "http://schemas.xmlsoap.org/claims/Group"
}

SAML Response from the IdP:Resulting SP user profile:

{
"authenticationmethod": "urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified",
"created_at": "2022-01-12T22:13:56.227Z",
"email": "testuser@example.com",
...
"locale": "en",
...
}

 

Case 2: Default Mappings for attributes with a period(.) in the name

When using the default mappings, there are also scenarios where the default mapping behavior for attributes includes a period(.) in the name. When this happens, the period(.) gets translated to a semicolon(:).

SAML Response from IdP:

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="_e93803ae0441e500e90a" InResponseTo="_0366a56d97925acac670362d9d5f75ce" Version="2.0" IssueInstant="2022-02-01T21:28:08.409Z" Destination="https://example-dev-tenant.us.auth0.com/login/callback">
...
<saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<saml:Attribute Name="http://schemas.auth0.com/dinner.tonight" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<saml:AttributeValue xsi:type="xs:string">
hamburgers
</saml:AttributeValue>
</saml:Attribute>
...
</saml:AttributeStatement>
</saml:Assertion>
</samlp:Response>

Resulting SP user profile:

{
...
"name": "testuser@example.com",
...
"dinner:tonight": "hamburgers",
...
}

 

Case 3: Standard Mapping Example

The most common scenario is to use the Mappings object defined in the Auth0 Enterprise Connection Mappings to customize how the attributes in the SAML response are mapped to the Auth0 user profile.

In the example below, notice that adding the mappings in the connection changed the name of the root-level profile attribute from the default locale to my_custom_locale_key when the http://schemas.auth0.com/locale attribute from the SAML Response was mapped to the user profile.

Configure the SAML Enterprise mappings object:

{
"my_custom_locale_key": "http://schemas.auth0.com/locale"
}

SAML Response from the IdP:

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="_82faf7a5ddb6dd5ba81e" InResponseTo="_d35a5b19f6576dc554cbb053a7bcdd53" Version="2.0" IssueInstant="2022-01-12T22:13:55.455Z" Destination="https://example-dev-tenant.us.auth0.com/login/callback">
...
<saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
...
<saml:Attribute Name="http://schemas.auth0.com/locale" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<saml:AttributeValue xsi:type="xs:string">
en
</saml:AttributeValue>
</saml:Attribute>
...
</saml:AttributeStatement>
</saml:Assertion>
</samlp:Response>

Resulting SP user profile:

{
"authenticationmethod": "urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified",
"created_at": "2022-01-12T22:13:56.227Z",
"email": "testuser@example.com",
...
"my_custom_locale_key": "en",
...
}

 

Case 4: Mapping attribute values into user_metadata/app_metadata

Actions will be needed to map SAML attributes that Auth0 receives from the IdP into user_metadata or app_metadata.

 

Related References

Recommended content

No recommended content found...
Need more help? Visit the Community
Visit the Auth0 Community