Claim Management with WSO2 Identity Server

Sadil Chamishka
3 min readOct 12, 2022

What are Claims ?

A claim is a piece of information about a particular subject. It can be anything that the subject is owned by or associated with, such as name, group, preferences, etc. Claim-based identity is a common way for any application to acquire identity information. It provides a consistent approach for all applications by hiding the lower level implementation.

The user claims are the attributes related to user such as first name, email, country etc. Also the identity claims specify information about the user account or the state of a user account such as the lastLoginTime, accountDisabled, and accountLocked claims.

Claim URIs are independent of the userstore and each claim URI can be mapped into any desired attribute in the userstore. Therefore, at the application level we would know about the claims, but not the attribute of the userstore. An advantage of this is that we do not need to be concerned about the userstore level when we develop an application as it is hidden by the claim management.

Let’s try out the claim managment features in WSO2 Identity Server which is the market’s leading open-source CIAM solution. You can download the product from the above link and setup the identity server.

Claim Dialects

A set of claims are identified as a dialect and same claim can be included in multiple claim dialects. When you list claims from the management console of the WSO2 IS, the available claim dialects will list down as shown in Fig 1. The default local claims managed by WSO2 Identity Server resides under the dialect.

Fig 1 — WSO2 Identity Server Claim list view

Each local claim under the WSO2 default claim dialect are mapped to an attribute of the underlying user store as shown in Fig 2. A local claim has a claim URI in the form claim dialect URL. These claims can be configured as necessary via the edit section of each claim and additionally custom regular expressions can be configured to validate user inputs on these claims.

Fig 2 — Local claim mappings to user store attribute

When considering other external claim dialects listed in Fig 1 consists of set of claims mapped to a local claim as shown in Fig 3.

Fig 3 — Local claim mappings for claims under OIDC claim dialect.

The WSO2 Identity server provides the flexibility to add new local claims, new claim dialects and add new claims to existing claim dialects also.

Now you have a good understanding on the WSO2 local claims, the local claim mapping for user store attributes and how the external claims are being mapped for the local claims. These claims are consumed by various applications like service provider apps which are registered in the WSO2 IS and when the Identity Server is configured as external identity provider etc. In such use cases, the requesting party who are interested in user’s claims (attributes) does not request the claims individually. For an example, an OIDC scope represents set of claims. The OIDC scopes passed when an OIDC flow results in adding the requested claims in the ID token itself to be consumed by the requesting party.

Let’s configure a custom OIDC scope and fetch an ID token with the expected information. The Fig 4. simplify the flow of resolving the claims in the authentication flow. The service provider application initiate the OIDC request with required scopes, the WSO2 IS validate the scopes, resolve claim mappings for the allowed scopes and retrieve the relevant user attributes from the user store.