This documentation is for WSO2 Identity Server 5.0.0. View documentation for the latest release.
Page Comparison - Working with User Stores (v.6 vs v.21) - Identity Server 5.0.0 - WSO2 Documentation

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

user store is the database where information about the users and user roles is stored, including log-in name, password, first name, last name, and e-mail address. The user stores of all WSO2 Carbon-based products are embedded H2 databases except for WSO2 Identity Server, which has an embedded LDAP as its user store. In Carbon, permissions are stored in a separate database called the User Management database. The default User Management database is H2, but you can connect to external user stores as well. 

titleRecommendations regarding user stores

For enterprise production environments, we do not recommend the embedded H2 database for use as a user store.

Also, WSO2 Identity Server is shipped with a default embedded ApacheDS. However, in a production environment, it is recommended to use an LDAP like OpenLDAP, due to scalability issues that exist with Apache DS.

The user stores of Carbon products can be configured to operate in read/write mode, in which it reads data and also writes data to the user store, and read-only mode, in which it does not modify any data. Carbon maintains roles and permissions in the Carbon database, but it can read users and roles from the configured user store.

titleAbout read/write and read only mode

If the user store is operating in "Read/Write" mode, the user can:

  • Add, modify, or remove user accounts
  • Reset user passwords
  • Manage user roles
  • Build "import users" from other User Stores

If the user store is operating in "Read Only" mode, the user can:

  • View user accounts

In addition to the primary user store, you can configure additional, secondary user stores.

WSO2 Identity Server allows you to manage users and their roles with the single-user-store and multiple-user-store options. Single-user-store option allows you to manage users and their roles in a single centralized data store whereas in the multiple-user-store option, the user and their roles are stored in more than one data store. In other words, one specific user can be attached to multiple user-stores.

In order to be available, the multiple-user-store option's domain name property must be attached to each user-store section in the user-mgt.xml file. e.g., <Property name="DomainName">WSO2.COM</Property>.


The following subtopics provide more information on the content in this section.

Children Display

The following provides a brief overview of what you can expect to find regarding user stores in this section. 

User management in WSO2 products


User management is available by default in all WSO2 Carbon-based products. It includes the following functionality. 

  • A primary user store, either the embedded (internal) user store or an external store (JDBC, LDAP, or Active Directory).
  • Ability to configure additional user stores as secondary user stores.
  • Ability to operate in read-only or read-write mode on your company's LDAP user stores.
  • Ability to work with Active Directory Domain Services (AD DS) and Active Directory Lightweight Directory Services (AD LDS) in read/write mode. 
  • Ability to read roles from external user stores.

For complete information, see About User Management. 

Configuring user management


The complete configuration for user management (referred to as the realm) is in the user-mgt.xml file in the <PRODUCT_HOME>/repository/conf/ directory. You can also configure users and roles through the management console, as described in the next topics in this section. User Management topic. 

Customizing user management


You can create a custom implementation of the user management functionality and use it in WSO2 products. For complete information, see Customizing User Management




One of the powerful features of the WSO2 Identity Server is the user management functionality. The Identity Server can be connected with any type of user store and then user store functions can be exposed as a Web Service APIs. The XACML implementation of WSO2 Identity Server uses these user management APIs for various purposes. All these user management functionalities are inherited from WSO2 Carbon platform.

Configurations are information stored in text-based files and database management systems used by the WSO2 Identity Server to serve the client in a specific manner.

  1. Administrator Credentials - Administrator credentials are stored in the user-mgt.xml file in the repository/conf directory in the distribution pack. This information is used to log into the server in administrator mode.
  2. User-store information - The user-store information is stored in the user-mgt.xml file in the repository/conf directory and master-datasources.xml in the repository/conf/datasources in the distribution pack. The information specifies the user-stores used by the server to store the client-specific identity data with the following types of user-stores.
    1. ldap
    2. Directory server user-store (e.g., Microsoft active directory)
    3. Database management system (e.g., MySQL, informix, cassandra)
    4. Text-based user-store
    5. Internal user-store information

This section explores different options available to customize the product according to user-specific needs.

Table of Contents


The following image can help you understand the concept called “Realm”.

Image Removed

User Realm

A realm is generally a collection of users with attributes, which may or may not be assigned to roles or groups. Basically we can say that the realm represents a user store. However the WSO2 user realm consists of following four aspects,

  • Use store management
  • Authorization Management
  • Claim management
  • Profile configuration management

The WSO2 user kernel contains a Java interface called “UserRealm” which is the realm of WSO2 Carbon servers. It is a collection of interfaces of the above mentioned aspects. There is a default implementation of this called “DefaultRealm“.

Realm Service

This provides methods to manipulate realms. It exposes realms as an OSGI service in Carbon servers. Therefore other bundles (or classes) in same OSGI environment, can use and manipulate them. The Carbon user kernel contains a Java interface called “RealmService” to expose it.

Realm Repository

This is the repository for realm and the repository can basically be any source. It would depend on how you are implementing the interfaces associated with the user realm. By default, the repository is a JDBC database or LDAP based user store added with the JDBC database. 


The default authorization manager and default claim managers depend on the JDBC database.

Realm Configuration

This is all done in an XML file which is called “user-mgt.xml”. Typically this can be found in the <PRODUCT_HOME>/repository/conf directory. This defines all configurations that are related to the user realm and that are used to initialize it.

Aspects of the User Realm

We now have an idea about the user realm, so lets go through each aspect of user realm to attain a more indepth understanding.

User Store Manager

This is component that manages underlying user store. The user store can contain users, user attributes and roles (or groups). It can be a JDBC (table or set of tables), LDAP or AD. ”UserStoreManager” is the Java interface which represents the user store manager. There can be different user store manager implementations to connect with different user stores. The user realm can be configured to have multiple user store managers as secondary user store managers. The user store manager can be operated in both read/write mode and read only mode. If it is read-only mode, you can only connect with an existing user store. WSO2 Identity Server comes with the following default user store manager implementations:

  • JDBCUserStoreManager (both read/write)
  • LDAPUserStoreManager (read only)
  • ApacheDSUserStoreManager (both read/write)

Any user store manager implementation can be written by implementing “UserStoreManager” or extending “AbstractUserStoreManager” or extending any default implementation that is mentioned above.

Image Removed


This uses a schema which is specific to WSO2 Carbon. Four tables which are associated with JDBCUserStoreManager, are mentioned below. You can find the full schema of these four tables from the db scripts file which can be found at <PRODUCT_HOME>/dbscripts directory. 


This db script file contains some other table schemas that are used for user management and registry functions

  • UM_USER: Where user names, passwords, etc. are stored
  • UM_ROLE: Where role names are stored
  • UM_USER_ROLE: Where user role mappings are stored
  • UM_USER_ATTRIBUTE: Where user attributes are stored. There can be any attribute id and a value for that attribute id which is associated with a user’s profile.

If your organization contains an existing JDBC user store and you want to plug it with WSO2 Identity Server, we can not assume that existing user store also has a schema which is compatible with WSO2 Identity Server schema. Therefore you need to extend the “JDBCUserStoreManager” and write a new implementation for your user store according to the your schema.

If you like to use any other schema, rather than the default WSO2 Identity Server user store schema, you can do it as well. However, you need to do the same thing as above; writing a new implementation using “JDBCUserStoreManager”.

You can connect to multiple LDAPs or different user stores with WSO2 Identity Server. You need to implement a new user store manager for this.

Authorization Manager

Any resources related with WSO2 Carbon platform can be protected with role based access control (RBAC).

JDBCAuthorizationManager” is the default implementation which comes with the WSO2 Identity Server. This uses a WSO2 Carbon specific permission model which uses the authorization data that is stored in tables in the JDBC database.

You can write any implementation and plug it with WSO2 Carbon (XACML based authorization manager would be a good option).

Claim Manager

This is responsible for adding/deleting claims and mapping claims from one namespace to another.

DefaultClaimManager” is the default implementation which is used to store claim data in tables of the JDBC database.

Visit the following pages to learn more information about the user core kernel usage:

Children Display

 See Writing a Custom User Store Manager for more information on how to do this.


General information about user store management.