Claim management with WSO2 Identity Server

What is a Claim?

A claim is a piece of information (or statement) about a subject (or user). It can be a anything that subject owned by or associated with it, such as name, group, preferences and etc. Claim provides a single and general notion to define the identity information related the subject. Claims-based identity is a common way for any applications to acquire those identity information. It provides a consistent approach for all applications by hiding the lower level implementation. Also Claims are used in identity propagation, by packaging the claims into one or more tokens (such as SAML). And those are then issued by an issuer; commonly known as a security token service (STS).

Claim Management

The Claim Management component of the WSO2 Identity Server enables you to define set of claims for users. Claim management provides to map a set of attributes from the underlying user store to a set of defined claims. Each claim can be uniquely identified by the Claim Uri. Claim Uris are independent from the user store and each claim uri can be mapped into any desired attribute in the user store. The underlying user store can be either JDBC , LDAP or AD that can be configured using user-mgt.xml file.  Therefore application level would know about the claims, not the attribute of the user store. One advantage of this,  we do not want to worry about the user store level, when we are developing an applications as it is hidden by the claim management.


Claim Dialect

A set of claims are identified as a dialect. Different dialects represents the same piece of information with different claim URIs. Following dialects are defined by-default with WSO2 Claim Management Component. Those are populated when the server is started at first time; by reading the claim-mgt.xml file which can be found at /repository/conf

  • :Default dialect for WSO2 Carbon (Claim set of this dialect is used for default user profile)
  • : Default dialect for Information Cards
  • : Default dialect for OpenID Attribute EXchange
  • : Default dialect for OpenID Simple Registration

Defining Claim Dialect

You can define a new Claim Dialect by clicking on the link ‘Add New Claim Dialect’ in Claim management UI.
Dialect Uri : URI which uniquely identifies the Dialect. Eg :-

Each dialect should have at least one claim. Therefore you need to define the claim configuration as defined in next heading


Defining Claim

You can extend a defined dialect by adding new claim mappings. Click ‘Add New Claim Mapping’ link to add a new claim mapping.

  • Display Name : Name of the claim displayed on the UI (displayed name in the user profile)
  • Description : Describe the functionality of the claim
  • Claim Uri : URI defined under the dialect, specific to the claim (Unique identifier for claim)
  • Mapped Attribute : Corresponding attribute name from the underlying user store
  • Regular Expression : Regular expression to validate inputs (which are entered, when configuring user profiles)
  • Display Order : Display order of the claim among all the other claims defined under the same dialect
  • Supported by Default : If unchecked won’t be prompted in user profile and in user self registration
  • Required : Required  claim for user profile and user self registration
  • Read-only : Claim can not modified. Can only be read


Lets assume that there is an attribute called “policyId” in the under line user store (say openldap). And Lets make it as a required claim value in the user’s identity using claim management.

Note: Please note that there are some pre defined attributes for user object class in the LDAP..  Therefore you want to do the claim mapping for correct attribute in the LDAP.  Mostly user object class in the LDAP is created with inetOrgPerson  object..   Therefore you  need to map with the attribute that is supported with inetOrgPerson object class.  You can find the attributes that are supported by this from here.

Step 1. Login to Identity Server management console as admin user

Step 2. Go to Configure -> Claim Management UI

Step 3. Locate WSO2 Carbon claim dialect (

Step 4. Create new claim under the

WSO2 Carbon claim dialect and map it for for the policyId attribute

Lets define claim as follows;

Claim Uri as -> (unique id to identify the claim)

Display Name → Policy Id (Displayed name in user profile UI and Claim management UI)

Description — > Policy Id of the User (Description about claim)

Mapped Attribute → policyId (Attribute id of the user store)

Regular Expression → ^[0-9] (regular expression to configure only the numerical values)

Display Order → 3 (Display order in user profile)

Supported by Default → true (This claim is in user profile and user self registration by default)

Required → true (This claim is a required claim in user profile and user self registration)

Read-only  → false

Step 5. Go to My Identity -> My Profiles and View default profile

Step 6. Policy Id can be seen as required attribute where you can configure only numerical values [0-9]

Step7. Log out from the admin console and go to self registration page. Identity -> Sign-up -> User name/password

Step 8. Policy Id can be seen as required attribute when user registration and you can register with only numerical values