Supported and required Claims

Use the contents of the SAML token sent by your identity provider (IdP) to the Service Provider (SP) (that is, to Tridion Sites) to set values for a number of Claims.

Tridion Sites supports and stores the following claims:
UniqueName
Use this Claim for the user name. This Claim is used in the following situations:
  • To look up the user in the system and retrieve its authorization rules.
  • When creating a new user using the group mappings functionality, to give the new user a name.

By default, Tridion Sites uses the contents of the NameID element in the SAML token as the value for the UniqueName Claim.

However, sometimes, NameID does not contain a usable value. NameID may contain, for example, a long string of hexadecimal characters, used for reasons of anonymization. Such a string is not very suitable as a username.

That is why you can select an attribute in the returned SAML token to serve as the source for UniqueName instead. You configure the name of this attribute as the value of an optional property called uniqueNameClaimType in the application.properties file. The value of that SAML token attribute is then used as the value for the UniqueName Claim.

In short, Tridion Sites follows the following algorithm:
  1. Check if the uniqueNameClaimType property is set in application.properties.
  2. If so (for example, let's say the property has the value mail), check the SAML token for an attribute by that name (that is, an attribute called mail).
  3. If so, set the UniqueName Claim to the value of that attribute (for example, name@example.com).
  4. If the uniqueNameClaimType property is not set, or if the attribute (mail) is not in the SAML token, set UniqueName to the value of NameID instead.
DisplayName

This Claim is used in user provisioning. When a new user is created, it gets a display name equal to this Claim.

By default, the DisplayName Claim gets the same value as the UniqueName Claim.

However, the value of the UniqueName Claim is not always the best string to use. Your SAML token may contain an attribute whose value is better suited to use as display name. For example, UniqueName may resolve to the e-mail address of the user, but an attribute called FullName might contain the user's given name and surname.

In this situation, you can instruct Tridion Sites to use the value of the attribute instead. You do this by configuring the attribute name (FullName in our example) in your application.properties file, as the value of an optional property called displayNameClaimType. The value of the attribute is then used as a value for the DisplayName Claim.

In short, Tridion Sites follows the following algorithm:
  1. Check if the displayNameClaimType property is set in application.properties.
  2. If so (for example, let's say the property has the value FullName), check the SAML token for an attribute by that name (that is, an attribute called FullName).
  3. If so, set the DisplayName Claim to the value of that attribute (for example, Frank Drebin).
  4. If the displayNameClaimType property is not set, or if the attribute (FullName) is not in the SAML token, set DisplayName to the value of the UniqueName Claim instead.
GroupID

This Claim is used when you use the group mapping functionality. In application.properties, set the groupClaimType property to the name of a SAML token attribute (for example, groupname) that identifies the user's IdP group. Tridion Sites checks the incoming SAML token for an attribute by that name (groupname), and uses the value (or values) found as the name(s) of the IdP group(s) to which the user belongs, (say, editor and author).

Tridion Sites further requires mappings between those IdP groups on the one hand, and Tridion Sites Groups in Content Manager on the other hand. You create such mappings in Content Manager Explorer.

If the SAML token does not contain an attribute whose name matches the value of groupClaimType, or if the value(s) of that attribute cannot be mapped to Groups in Tridion Sites, access is denied for that user.

In all three cases, if you set a Claim type property, you must ensure that the SAML token returned by your IdP actually contains the attribute identified by that Claim type property. If that attribute is not already included in the token, consult your IdP's documentation to learn how to add it to the SAML token.