Configuring claims returned by the UserInfo endpoint

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

About this task

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

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:

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.
The claims that are associated with the scopes
Each scope can have multiple claims that are associated with it.
The federated repository properties that are associated with the claims
A claim can have only one federated repository property that is associated with it.
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.

Note: 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.

Table 1. Default mappings for scopes, claims, and federated registry properties
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 server defines default scopes, claims, federated registry properties, and default mappings. The only time that you need to perform any of the following steps is if you want to change a default mapping or define a custom scope or claim.

Procedure

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" />
```
Note: 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, you must 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>
```
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, you must 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>
```
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>
```
Note: The LDAP attribute must be defined in the schema of the LDAP registry.

Results

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