Skip to main content
Version: 2024.12.12

Map User Data

Your identity provider shares information about your users with Digital.ai in the form of key/value pairs (known as claims or assertions, depending on the IdP), and the Platform uses this data to create users in our system.

Platform administrators can use attribute mappers to ensure that user data from your IdP is properly understood by the Digital.ai Platform.

note

The Platform requires first name, last name, email address, and username to create a user. You don't need mappers for any other data.

tip

Mappers are also used when transmitting data from the Platform to other Digital.ai applications, but those mappers are configured automatically while connecting an application.

When to Use Mappers​

OIDC​

Mappers may be optional for OIDC connections.

Whether or not you need to use mappers to handle this data is entirely dependent on your organization's unique situation, and in general the Digital.ai Platform expects to receive user attributes based on the set of standard claims as defined by OpenID. You can view the list of standard claims here: https://openid.net/specs/openid-connect-core-1_0.html#StandardClaim.

If your data is stored as the claims identified in this list (i.e. given_name, family_name, email, etc.), then you typically would not need to bother creating any attribute mappers.

For example, if your IdP uses the standard claim "email": john@example.com, the Platform will automatically map that to the Platform's email user attribute.

However, if your IdP uses a claim called "email_address": john@example.com, then you would need to create a mapper to correctly get that data into the Platform's email user attribute.

SAML​

Mappers are required for SAML connections.

Unlike OIDC, the SAML protocol has no standard naming conventions for the attributes it stores (which SAML tokens refer to as assertions). That is why we require mappers for SAML connections, because each IdP's assertions may be named differently. So in order for the Platform to understand the data correctly, you must provide the assertion values as they are named in your IdP.

When creating mappers for SAML connections, you must add mappers for the following user data: first name, last name, email.

Username data is automatically pulled from the NameID attribute (based on the NameID Policy Format / Principal Type fields defined in the SAML IdP). You do not need to create a mapper for username if you need to override the default assertion.

Azure AD Assertion Names​

If you are using Azure AD the default assertion names are as follows:

  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

User Group Mappers​

You can also use mappers if you want users to inherit group assignments from your IdP in the Platform or Digital.ai applications. To learn more about mapping group data, see Map User Group Assignments.

Add or Edit Mappers​

You can add mappers during the initial IdP configuration process, or at any time after you've already established the connection by returning to edit the identity provider.

  1. Log in to the Platform as an administrator.
  2. In the left navigation, under SSO, click Identity providers.
  3. Find the SSO connection you want to modify and click the Edit icon under Actions.
  4. Click Next until you get to the Mappers page.
  5. Click the Add drop-down arrow, and select Mapper.
  6. In the Add mapper window, set the following fields:
    1. Name is merely a way to identify the mapper. Enter something like First Name Mapper.
    2. Sync Mode controls whether an update to a user attribute in your IdP will cause an update in the platform. We suggest using INHERIT.
      • FORCE always updates the Platform user when there is a change in your IdP.
      • IMPORT never updates the Platform user after they are created the first time, regardless of changes in your IdP.
      • INHERIT uses the value that has been configured on the Advanced config page of this IdP connection.
    3. Mapper Type should be set to Attribute Importer. 4.(For OIDC providers only) Claim is the name of the claim as specified by your IdP.
    4. User Attribute Name is the Platform user attribute that the data will be mapped to. This should be set to username, email, firstName, or lastName depending on the data you're mapping.
    5. (For SAML providers only) Attribute name is the name of the assertion as specified in your IdP's SAML token. You can add the name in either Attribute Name or Friendly Name (you must complete at least one of the fields, but you do not need to complete both).
  7. Click Add Mapper.
  8. Repeat step 7 for any additional mappers.
Last updated on