Claims mapping

In Sitecore Cloud Portal, claims mapping lets you add a custom claim for XM Cloud to the Sitecore ID token and Sitecore access token. You can configure claims mapping when setting up an SSO connection or updating an existing connection.

You need to configure claims mapping if you want to automatically assign SitecoreAI roles to team members that log in to your organization using SSO.

Note

Because claims mapping is only supported for SitecoreAI roles, the mapping interface only appears if there is at least one SitecoreAI tenant in the current organization.

If a team member has a mapped claim, it works in all organizations where a team member logs in using SSO. However, claims mapping can only be configured from the organization that owns the SSO connection.

Note

This topic covers claims mapping in the Cloud Portal. For specific instructions on automatically assigning SitecoreAI roles to SSO users, see Assign SitecoreAI roles with claims mapping.

The claims mapping element

To set up claims mapping for an SSO connection, you add at least one claims mapping element to the connection.

A claims mapping adds claims returned by your external identity provider's (IdP) ID token or SAML response to the Sitecore ID token and Sitecore access token.

When a user logs in to a Sitecore Cloud Portal organization, the claims in their external IdP ID token or SAML response are evaluated against the configured claims mappings. If a match is found, the corresponding mapped target claim is added to their Sitecore ID token and Sitecore access token.

You can have up to 20 claims mappings per SSO connection, but a user can only have one mapped claim in their Sitecore ID token and Sitecore access token.

A claims mapping consists of zero or more source claims and one or more corresponding target claims.

Source claim

A source claim is a claim from your identity provider that you want to map to the Sitecore ID token and Sitecore access token.

Shows a claims mapping with a red box around the source claims section.
Note

In your identity provider, you must identify and add the claims you want to use to map to the Sitecore ID token and Sitecore access token. The claim values returned by your IdP must be strings or arrays of strings, otherwise, you get a warning message at login and claims mapping fails.

If using OpenID Connect, you might need to add the required scopes to the Scopes field so that the configured claims are returned by your IdP.

To add a source claim to a claims mapping:

  • In the Name field, enter the name of the claim from your external IdP that you want to map.

  • In the Value field, either enter a regex pattern (ECMAScript syntax) that matches the value returned by the IdP claim or leave the field empty.

    If the returned value matches the pattern, the target claims are added to the Sitecore ID token and Sitecore access token. If you leave the Value field empty, then the target claims are added for all users that have the source claim, regardless of its value.

    Note

    Literal notation for regex is not supported.

    If you need case-insensitive regex, use the i modifier.

When a user logs in to their organization and their external IdP's access token contains a claim that matches the name and value of a source claim, the corresponding target claims are added to the user's Sitecore ID token and Sitecore access token.

When you add multiple source claims to a mapping, the target claim is added to the Sitecore ID token and Sitecore access token if any matching source claim is present in the IdP's ID token or SAML response. If a claims mapping does not include any source claims, the target claims are always added to the Sitecore ID token and Sitecore access token for all users.

You can have up to 20 source claims per claims mapping.

Target claim

A target claim is a claim that will be added to the Sitecore ID token and Sitecore access token when a matching source claim is present.

Shows a claims mapping with a red box around the target claims section.

To add a target claim to a claims mapping:

  • Enter a name for the claim you want to add to the Sitecore ID token and Sitecore access token when a matching source claim is present in the IdP's ID token or SAML response.

    Note

    You can name your target claims whatever you like. The target claim name is used when mapping Sitecore ID token claims to SitecoreAI roles.

  • Specify the values you want to assign to the claim.

    If you add multiple target claims to a mapping, all of them will be added as a single claim in the Sitecore ID token and Sitecore access token.

When a mapped claim is added to a Sitecore ID token and Sitecore access token, it is automatically prefixed with the ID of the SSO connection. For example, if your target claim name is xmc_role, and the SSO connection ID is con_Veryg0od1D123456, then the claim name in the Sitecore ID token and Sitecore access token will be con_Veryg0od1D123456.xmc_role.

A user can only map one claim per token exchange, but can have multiple target claim values from different mappings if the target claim name is the same, (see User E in the following claims mapping example). If multiple claims are mapped, a warning message will appear at login, and claims mapping will fail, (see User D in the following claims mapping example).

You can have up 20 values per mapping.

Claims mapping example

The following screenshot shows claims mappings that add target claims to SSO users if they have matching source claims in their IdP ID token or SAML response.

Claims mapping example showing several claims mapped.

In this example, we have six users with different configured claims in their external IdP ID token: User A, User B, User C, User D, User E, and User F. The rest of this section describes the claims in each user's external IdP ID token and explains what happens when they try to log in to the organization:

User A has the permission claim with a value that includes developer (case insensitive), and the devGroup claim with any value:

  • Their Sitecore ID token and Sitecore access token will have the following claim added: "yourSSOConnectionId.xmc_role": ["sitecore\Developer", "sitecore\Custom Role"]

User B has the group claim with the value developer:

  • Their Sitecore ID token and Sitecore access token will have the following claim added: "yourSSOConnectionId.xmc_role": ["sitecore\Developer", "sitecore\Secret Role"]

User C has the group claim with a value that contains Designer (case sensitive):

  • Their Sitecore ID token and Sitecore access token will have the following claim added: "yourSSOConnectionId.default_role": "sitecore\Designer"

User D has the devGroup claim with any value, and the group claim with a value that contains Designer (case sensitive):

  • Because only one target claim can be added to the Sitecore ID token and Sitecore access token, claims mapping will not work for the user and they will see a warning message when they log in. This setup adds two claims (xmc_role and default_role) to the Sitecore ID token and Sitecore access token.

User E has the devGroup claim with any value, and the group claim with the value developer:

  • Their Sitecore ID token and Sitecore access token will have the following claim added: "yourSSOConnectionId.xmc_role": ["sitecore\Developer", "sitecore\Custom Role","sitecore\Secret Role"]

    This works because the combination results in only one claim being added to the Sitecore ID token and Sitecore access token.

User F has the group claim with the value ["developer", "administrator", "puppyPetter"]:

  • Their Sitecore ID token and Sitecore access token will have the following claim added: "yourSSOConnectionId.xmc_role": ["sitecore\Developer", "sitecore\Secret Role"]

    When the external IdP returns a string array as a claim value, target claims are added if any string matches the regex pattern. So User F's claim matches the group claim with the value developer. However, when the group claim value is administrator or puppyPetter, there are no matching source claims.

Claim size limit

The maximum supported size for a claims mapping is 700 characters, calculated using the following formula:

RequestResponse
Claim size = (length of connection ID + length of target claim name + 1) × (Number of mapped target claims) + SUM(Length of each target claim value)

For example, if you have mapped target claims:

  • Name: xmc_role Value: Sitecore\Developer

  • Name: xmc_role Value: Sitecore\PuppyPetter

RequestResponse
Size = con_Veryg0od1D123456.xmc_role * 2 + (Sitecore\Developer + Sitecore\PuppyPetter)
Size = 29 * 2 + (18 + 20)
Size = 96

The size of this claims mapping is 96 characters.

Do you have some feedback for us?

If you have suggestions for improving this article,