Sovrain
  1. Documentation
  2. Identity provider
  3. For admins

How-to guide

Map claims and attributes

Send a person's attributes to an application under the names it expects, as OpenID Connect claims, SAML attributes or the SAML NameID.

This guide sends extra information about a person to an application, for example their department or employee number, under the name the application reads. It also sets which value identifies the person in a SAML application.

You can map the built-in attributes (id, externalId, login, email, firstName, lastName) and any custom attribute. An email value is sent only when the address is verified. Empty values are not sent.

Add a claim to an OpenID Connect app

What every OpenID Connect app gets without mapping (sub, preferred_username, name, email and others) is listed in Claims. Add a mapping only for anything else.

  1. On your home page, under Administration, select Open admin, then select Applications and open the application.
  2. Open the Claims tab and select Add claim.
  3. Fill in New claim:
    • User attribute: the attribute to send, for example department;
    • Claim name: the name the application reads, for example department;
    • Sent with: the scope that releases it: profile, email or groups.
  4. Select Add.

The claim is sent as a text value in the ID token and from userinfo, but only when the application asked for the Sent with scope and that scope is ticked under Scopes & options. If the application asks the person for consent, the scope covers the claim too.

A claim name starts with a letter and holds only letters, digits, _, . and -, up to 64 bytes. Standard names that Sovrain fills in itself, such as sub, email, name, groups and role, cannot be used. Claims lists all 25 reserved names.

To stop sending a claim, select × on its row.

Choose how a SAML app identifies each person

  1. Open the SAML application and its Subject & attributes tab.
  2. Under Subject (NameID), set:
    • Source attribute: the value the application uses to recognize the person, usually email or login;
    • Format: what the application expects, usually emailAddress or unspecified.

Pick a value that does not change for a person. If the source is email and a person has no verified address, that person cannot sign in to the application. The formats persistent and transient send the same value as the source attribute; Sovrain does not generate a separate opaque identifier.

Add an attribute to a SAML app

  1. On the Subject & attributes tab, under Attribute mapping, select Add mapping.
  2. Choose the User attribute and type the SAML attribute name the application expects, for example firstName to givenName, or email to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.
  3. Select Add.

Each attribute is sent with one text value. The name actor is reserved for delegation. To remove a mapping, select the bin icon on its row.

Without mappings, the assertion carries only the NameID, plus role when group access gives roles, and actor on delegated sign-ins when the delegation policy sends it; see Send roles to apps.

Map attributes for SCIM provisioning

Provisioning has its own mapping, from Sovrain attributes to SCIM attributes of the application, on the Attribute mapping tab of the provisioning settings. See Provision accounts with SCIM.