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


Discuss this article on Stack Overflow


  1. Added a new custom attribute named policyid in claim management as per the post, Now i want to add the profile details via SCIM endpoint.I tried with the following curl command..

    curl -v -k –user admin:admin –data “{“schemas”:[],”name”:{“familyName”:”gunasinghe”,”givenName”:”hasinitg”},”userName”:’jouhar’,”password”:”password”,”policyid”:”123″,”emails”:[{“primary”:true,”value”:””,”type”:”home”},{“value”:””,”type”:”work”}]}” –header “Content-Type:application/json”

    But its not working…pls help..

    **My primary storage changed to JDBC User store.

  2. Could you please add steps on how I can add attribute to user store? When I followed these steps, I got an error on user profile page while setting policy id field “One or more attributes you are trying to add/update are not supported by underlying LDAP”

    1. Hi Sachin, According to the error, It seems that the value that you have mentioned as “Mapped Attribute” is not a support attribute in the LDAP.. You need to use some attribute support with your LDAP. What is value that you have used for as “Mapped Attribute”…?

      1. I’m using policyId value for Mapped Attribute. Do i need to manually create policyId attribute in LDAP user store?

      1. So as per your suggestion, i mapped policy Id claim to title (user attribute) and i was able to save value for policy id on user profile screen. Is there a way to add attributes to inetorgperson? How can i customize user store?

  3. Asela, would i be able to extend inetorgperson class? If yes, how? This is critical for the phase of project. your help is greatly apprecited

  4. Yes.. You can extend the any LDAP object class and create a new class… Please search for extending LDAP object class.. you would find some useful things…

  5. Hi Asela, this is question about JDBCUserStoreManager. If I implement “doAddUser” method, will it be available to user admin API? My goal is use userAdmin API to add users by supplying claim information. Any suggestions would be appreciated.

      1. Thanks, Asel for your quick response. Would you be able to provide sample soap request for “addUser” api that includes claim information? I will greatly Appreciate it !

  6. Hi Sachin

    please find sample request that is generated from SOAPUI for UserAdmin service. You can use the java client that can be found at the link that i have shared previously

       <soapenv:Envelope xmlns:soapenv="" xmlns:xsd="http://org.apache.axis2/xsd" xmlns:xsd1="">
      1. Asel, one last question. What is the difference between UserAdmin and RemoteUserStoreManagerService. I tried using RemoteUserStoreManagerService to add user using your soap and get HTTP 500 – Internal server error. I’m able to add user using UserAdmin API. When would I use UserAdmin versus RemoteUserStoreManagerService? Thanks!

  7. “UserAdmin” web service is an API, that has been written for WSO2 Identity Server’s user management UI. Some methods in this service pass and return complex objects values that are used to populate the user management UI. Basically web service API is little bit couple with the UI. Therefore it is not much good to use this web service API for basic user management operations that is called by external applications. The Best way is to use “RemoteUserStoreManagerService” administration web service API. It has a simple input parameters and return types that you can easily integrated in to an application that you are implementing. BTW, you can tryout with the client that is available here. It would work.

    1. Hi Asela,

      I override doAddUser method of CustomUserStoreManager which is extending JDBCUserStoreManager. Here is my implementation

      public void doAddUser(String userName, Object credential, String[] roleList,
      Map claims, String profileName,
      boolean requirePasswordChange) throws UserStoreException {
      //throw new UserStoreException(
      // “User store is operating in read only mode. Cannot write into the user store.”);

      System.out.println(“Begin doAddUser ..”);

      Connection dbConnection = null;
      String password = (String) credential;
      CallableStatement stmt = null;

      try {
      dbConnection = getDBConnection();
      stmt = dbConnection.prepareCall(“{call sp_um_user_INSERT(?,?)}”);
      stmt.setString(1, userName);
      stmt.setString(2, password);

      if (log.isDebugEnabled()) {


      System.out.println(“End doAddUser ..”);
      } catch (SQLException e) {
      } finally {
      try {
      if(stmt != null)
      if(dbConnection != null)
      } catch (SQLException e) {

      After compiling, I copy to WSO2 repositorycomponentsdropins folder.

      Started WSO2

      Ran Sample user management client to add user using client link you have provided in above reply. This client is using RemoteUserStoreManagerServiceStub to get list of users and add user. Client works perfect and gets users from my custom user store (mysql) and adds user to custom user store.

      When add user api was called, i was expecting RemoteUserStoreManagerService to invoke ‘doAddUser’ method i have override. I do not see system.out.println statements in WSO2 console.

      Please confirm that ‘doAddUser’ of my customUserStore will be invoked when I call addUser method of RemoteUserStoreManagerService.


  8. Single custom JDBC user store manager issues:
    When we use only one Custom user store manager in WSO2 , we are facing below issues :
    1.User with Login permission is not able to login to the identity server.
    2. If we change the password from admin to something else apart from admin , even this doesn’t work
    However with primary and secondary JDBC store, these issues does not occur.

    Can you please let me know why these issues occur in only single custom JDBC user store ?

  9. Hi Asela,

    I was able to resolve my issue. In user-mgt.xml, I replaced UserStoreManager with my custom manager as shown below

    But this made my user store read only. When I run the client to add user using RemoteUserStoreManagerSErvice, I get following error.

    User creation is failed
    org.apache.axis2.AxisFault: Invalid operation. User store is read only
    at org.apache.axis2.util.Utils.getInboundFaultFromMessageContext(
    at org.apache.axis2.description.RobustOutOnlyAxisOperation$RobustOutOnlyOperationClient.handleResponse(
    at org.apache.axis2.description.OutInAxisOperationClient.send(
    at org.apache.axis2.description.OutInAxisOperationClient.executeImpl(
    at org.apache.axis2.client.OperationClient.execute(
    at org.soasecurity.sample.user.mgt.SampleUserRoleMgtClient.main(
    User is authentication failed
    Role creation is failed
    org.apache.axis2.AxisFault: Cannot add role to Read Only user store unless it is primary
    at org.apache.axis2.util.Utils.getInboundFaultFromMessageContext(
    at org.apache.axis2.description.RobustOutOnlyAxisOperation$RobustOutOnlyOperationClient.handleResponse(
    at org.apache.axis2.description.OutInAxisOperationClient.send(
    at org.apache.axis2.description.OutInAxisOperationClient.executeImpl(
    at org.apache.axis2.client.OperationClient.execute(
    at org.soasecurity.sample.user.mgt.SampleUserRoleMgtClient.main(

    Any suggestions?


  10. I have a similar issue, which I am not sure which can be resolved using wso2 IS. I need to embark on using wso2 IS but first I need to make sure whether IS suits my requirement.

    1/ I have two applications currently lets say App A and App B.
    2/ Both applications have independant user stores.
    3/ The requirement is to provide SSO and other Identify server functions to these two applications.
    4/ A single user currently has two accounts in the two independant stores if registered in both App A and App B.
    5/ Is it possible to join these two accounts via IS (user store in IS) and then authenticate the user, and then create SSO login for the user?
    6/ In the future I want the ability to provision users via IS as well.

    I know the questions above are vague. Let me know if u need more information.

  11. Hi, Asela. One question about the claim, if two different user store return an attribute with the same name, and i map that attribute to a claim uri, what will it return when i use the claim uri as attributeId in XACML Policy.

  12. Hi Asela,
    How can I Publish my own claim dialect in user profile.
    (I have changed the dialect uri in the XML file. But when I in the user profile, It does not shot
    the required dialect’s claims. instead it show )
    I will great appreciate if u can answer me. Thanks.

Leave a Reply

Your email address will not be published. Required fields are marked *