Enable user attributes for OpenID Connect apps

User attributes are pieces of information about the identity of a user such as an email address, birth date or the user's country etc.. Applications may request user attributes from the identity provider to personalize the experience of the logged in user.

The following guides explain how you can configure OpenID Connect applications to request attributes from WSO2 Identity Server.

Configure user attributes

Follow the steps given below to configure the user attributes from the WSO2 Identity Server Console and share them with the application.

Select user attributes

You can specify the necessary user attributes for an application. This ensures that when a user logs in, the application is only granted access to the user information associated with these attributes.

The user attributes are grouped by their specific scopes to ease the user attribute configuration process. You can add user attributes individually or all the attributes in the scope at once.

To add user attributes to the app:

1. On the WSO2 Identity Server console, go to Applications.

2. Select your application and go to its User Attributes tab. The most common user attributes are listed according to the relevant scope.

   

3. You can select user attributes using the following methods:

   • Add all user attributes for a given scope by selecting the checkbox in front of that scope.

     

   • Add user attributes by expanding a scope and selecting only the necessary user attributes.

     

4. Click Update once you are done.

Select an alternate subject attribute

The subject attribute is used for exchanging information about the user. The subject is represented by the subject attribute in the ID token.

By default, Asgardeo shares User ID as the subject. You can define any user attribute as the subject.

To define a different attribute as the subject:

1. In the Subject section of the User Attributes tab, enable Assign alternate subject identifier.

   Note

   According to the OIDC specification, is not recommended to change the default subject identifier.

   

2. Select an attribute as the subject from the Subject attribute list.

3. Click Update.

Define mandatory user attributes

If your application needs certain attributes for the successful function of the application, you can make them mandatory attributes. Users logging into the application should then have the mandatory attributes either pre-filled in their profiles or provide the required information when prompted during the login flow.

To make an attribute mandatory:

1. On the WSO2 Identity Server console, go to Applications.

2. Select the application and go to its User attributes tab.

3. Expand the relevant scope and out of the selected attributes for the application, select the mandatory attributes by selecting the Mandatory checkbox next to them.

   

Configure the subject identifier

WSO2 Identity Server uses a subject attribute to uniquely identify users logging into OIDC applications. This is set to be the user ID of the user which can be found in the user's profile in User Management > Users.

However, having a single subject identifier for multiple applications may enable external entities to track the activity of a user across applications based on a single attribute.

You can opt for a pairwise subject identifier to mitigate this issue. With a pairwise subject identifier, WSO2 Identity Server generates a unique pseudonymous ID for each user-application pair protecting the user's identity when accessing multiple applications.

Follow the steps below to configure the subject identifier type:

1. On the WSO2 Identity Server Console, go to Applications.

2. Select the application and go to its User Attributes tab.

3. Under Subject type, select Pairwise.

4. Enter a Sector Identifier URI.

   Info

   The sector identifier URI is used to group clients belonging to the same security domain so that the same pairwise identifier is used for a given user accessing these clients.

   

5. Click Update to save the changes.

How it works

The following diagram depicts the process WSO2 Identity Server implements when a user tries to log in to an application.

Application requests attributes

When the user logs in to the app, a request is sent to WSO2 Identity Server with the relevant scopes.

Applications can use scopes to request access to a group of user attributes.

Note

Learn more about managing scopes in WSO2 Identity Server.

WSO2 Identity Server checks for mandatory attributes

WSO2 Identity Server verifies whether the user's profile has values for all the mandatory attributes that are requested by the application. If there are missing values, WSO2 Identity Server will prompt the user to enter the missing values.

Requests user consent

By default, WSO2 Identity Server requests the user's consent to share the user attributes with the application.

Note

Learn more about managing user consent.

Shares attributes with the app

If the user consents to share attributes with the application, WSO2 Identity Server returns the requested user attributes as well as the subject attribute to the application in the ID token.

Subject Attribute

The subject attribute is the unique identifier for a user. The application receives this value via the subject attribute parameter in the ID token. In WSO2 Identity Server, the user ID is used as the subject attribute.

ID token

Once the application calls the token endpoint, WSO2 Identity Server sends the ID token in the response.

All the user attributes that are requested by scopes are returned as claims in the ID token. The application can decode the ID token to view the claims.

A sample ID token is given below:

{
  "isk": "69b37037a2349763dc48e2a30a62c3feebf0b5823cf869e149352737ddc0ca63",
  "at_hash": "7qgloEmkz3kGBTtH7RI4qw",
  "sub": "e46ffa67-100d-4329-9460-b8251d446518",
  "amr": [
    "BasicAuthenticator"
  ],
  "iss": "https://localhost:9443/oauth2/token",
  "given_name": "alice",
  "sid": "5580be2b-a12d-43a4-823a-9d1352b88269",
  "aud": "UEP40cZTZfxJfGdDWFmTrwqluxoa",
  "c_hash": "VlKxb3UhuYtFEG_VftAa0g",
  "nbf": 1625557031,
  "azp": "UEP40cZTZfxJfGdDWFmTrwqluxoa",
  "nickname": "nick",
  "exp": 1625560631,
  "iat": 1625557031,
  "family_name": "john"
}

Userinfo response

In addition to getting attributes from the ID token, the application can invoke the userinfo endpoint and get user attributes along with the subject attribute.

A sample userinfo response is given below:

{
"sub": "e46ffa67-100d-4329-9460-b8251d446518",
"nickname": "nick",
"given_name": "alice",
"family_name": "john"
}

Prioritize local account attributes

WSO2 Identity Server offers the capability to share attributes of a local account during federated aWSO2 Identity Serveruthentication, provided that there exists a local account linked with the federated identity. To prioritize the sharing of attributes from linked local accounts, follow the steps given below:

1. On the WSO2 Identity Server Console, go to Applications.
2. Select your application and go to its User Attributes tab.

3. Scroll down and under Linked Accounts, select Prioritize local account attributes.

   

Once enabled, the tokens issued from this application during federated authentication with an external identity provider will contain the attributes of the local account which is linked with the entity identified by the subject claim of the token issued by the external identity provider.

If there is no such linked local account, WSO2 Identity Server will return the user attributes retrieved from the external identity provider.

Note

When JIT provisioning is enabled for the external identity provider, WSO2 Identity Server ensures that the attributes of the associated local account synchronize with the external identity provider upon each federated login.

If you want to preserve attribute values set in the local user account, you need to disable JIT provisioning