Configure claims returned by the UserInfo endpoint

We can configure a Liberty profile OpenID Connect Provider to customize the claims that are returned by the UserInfo endpoint.

We can configure the claims that are returned from a Liberty profile server OpenID Connect Provider using the scopeToClaimMap and claimToUserRegistryMap subelements of the openidConnectProvider element in server.xml.

The OpenID Connect UserInfo endpoint accepts an access token as input and returns a set of claims about the user for whom the access token was created. The claims that are returned are determined by:

1. The scopes in the access token

   An access token can have multiple scopes. The scopes in an access token are the scopes that are supplied on the authorization endpoint invocation that created the access token.

2. The claims that are associated with the scopes

   Each scope can have multiple claims that are associated with it.

3. The federated repository properties that are associated with the claims

   A claim can have only one federated repository property that is associated with it.

4. The user registry attributes that are associated with the federated repository properties

   A federated repository property can have only one user registry attribute that is associated with it.

The only user registry type that supports the retrieval of UserInfo claims is LDAP.

Liberty defines default scopes, claims, federated registry properties, and default mappings.

Scope	Claims	Federated registry property
profile	name, given_name, picture	displayName, givenName, photoURL
email	email	mail
address	address	postalAddress
phone	phone_number	telephoneNumber

Each of the following steps is optional. The Liberty profile server defines default scopes, claims, federated registry properties, and default mappings. The only time needed to perform any of the following steps is to change a default mapping or define a custom scope or claim.

1. Configure the claims that are associated with scopes. A scope can be mapped to multiple claims, and multiple claims must be comma-separated.

   In the following example, the scope CUSTOM_SCOPE1 is associated with two claims, CUSTOM_CLAIM1 and language, and the scope CUSTOM_SCOPE2 is associated with the claim CUSTOM_CLAIM2.

   <scopeToClaimMap CUSTOM_SCOPE1="CUSTOM_CLAIM1, language"
                    CUSTOM_SCOPE2="CUSTOM_CLAIM2" />

   Claim and scope names are case-sensitive, CUSTOM_SCOPE1, and custom_scope1 are different scopes.

   1. To define scopes with the same spelling but different case, use the property subelement. In the following example, the scopes CUSTOM_SCOPE1 and custom_scope1 are defined.

      <scopeToClaimMap CUSTOM_SCOPE1="CUSTOM_CLAIM1, language" > 
          <property name="custom_scope1" value="custom_claim1,mobile"/> 
      </scopeToClaimMap>

2. Configure the federated repository properties that are associated with claims. A claim can be mapped to only one federated repository property.

   In the following example, the claim CUSTOM_CLAIM1 is associated with the federated repository property departmentNumber. The claim language is associated with the federated repository property preferredLanguage, and the claim CUSTOM_CLAIM2 is associated with the federated repository property mail.

   <claimToUserRegistryMap CUSTOM_CLAIM1="departmentNumber"
                           language="preferredLanguage" 
                           CUSTOM_CLAIM2="mail" />

   1. To define claims with the same spelling but different case, use the property subelement. In the following example, the claims CUSTOM_CLAIM1 and custom_claim1 are defined.

      <claimToUserRegistryMap CUSTOM_CLAIM1="departmentNumber" >
          <property name="custom_claim1" value="employeeType" />
      </claimToUserRegistryMap>

3. Configure the user registry attributes that are associated with federated repository properties.

   In the following example, the federated repository property photoURL is associated with the LDAP registry attribute ldapPersonPicture

   <ldapRegistry...>
     ...
       <attributeConfiguration>
           <attribute name="ldapPersonPicture" 
                      propertyName="photoURL" 
                      entityType="PersonAccount" />
       </attributeConfiguration>
      …
   </ldapRegistry>

   The LDAP attribute must be defined in the schema of the LDAP registry.

Results

We have now completed the configuration that is required to customize the claims that are returned by the UserInfo endpoint.

Parent topic:

Configure an OpenID Connect Provider