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.
- On your home page, under Administration, select Open admin, then select Applications and open the application.
- Open the Claims tab and select Add claim.
- 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,emailorgroups.
- User attribute: the attribute to send, for example
- 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
- Open the SAML application and its Subject & attributes tab.
- Under Subject (NameID), set:
- Source attribute: the value the application uses to recognize the person, usually
emailorlogin; - Format: what the application expects, usually
emailAddressorunspecified.
- Source attribute: the value the application uses to recognize the person, usually
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
- On the Subject & attributes tab, under Attribute mapping, select Add mapping.
- Choose the User attribute and type the SAML attribute name the application expects, for example
firstNametogivenName, oremailtohttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress. - 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.
Related
- Claims, SAML and SCIM.
- Application settings.