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

Knowledge Articles
, , , ,
1

Problem Statement

There is a SAML Mappings misconfiguration in your SAML Enterprise Connection.

Symptoms

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

Troubleshooting

If you encounter mapping issues or errors that 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.

984×192 15.1 KB

  1. Attempt to sign in to your 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 your 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 is 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.

1506×1140 116 KB

Relevant Docs:

Cause

  • The IdP doesn’t send the attributes to Auth0
  • SAML attributes are incorrectly mapped to the Auth0 user profile
  • Auth0 isn’t 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, you may need to customize how the attributes in the SAML response from the IdP are mapped to the user’s Auth0 Profile.

To do so, you can map the attributes through the SAML Enterprise Connection Settings.

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”.

    1502×234 14.1 KB

SAML Enterprise Connection:
You can configure the mappings by navigating to your Auth0 Dashboard > Authentication > Enterprise > SAML > Your SAML Connection > Mappings.

Please review the relevant solution for your use-case:

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:

<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",

...

"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 your 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

To map SAML attributes that Auth0 receives from the IdP into user_metadata or app_metadata, you will need to use either a Rule or an Action.

5 Likes