This page demonstrates the process of writing a simple custom user store manager for WSO2 products.
In enterprise systems, some key components are centralized for painless management. User management is one such component that is centralized and carefully monitored. There may be user management systems that use a database or LDAP as the datasources. Any WSO2 product based on WSO2 Carbon can be configured to use these existing centralized user management systems as the user store. This topic demonstrates how to integrate an existing JDBC user store with a WSO2 product.
The following sections provide information that you need to be aware of when writing a custom user store manager:
- AbstractUserStoreManager and implementations
- Implementing a custom JDBC user store manager
AbstractUserStoreManager and implementations
There are a set of methods available in the
AbstractUserStoreManager class. These methods are used when interacting with user stores. When we implement a custom user store manager, it is important to identify the methods that must be implemented or overridden.
Tip about overriding methods:
You must select the methods to override based on your requirement. For example, if you want to change the way you encrypt the password, you only need to implement the
preparePassword method. If you want to implement a completely new read/write user store manager, you must implement all the methods listed in the tables given below. If the user store is read-only, you can implement only the important methods and read methods (if you extend from
AbstractUserStoreManager you have to keep unrelated methods empty).
There are a few other methods used for internal purposes. You do not need to override those methods.
The following list briefly explains the use of the available methods in the
AbstractUserStoreManager class. Most of the methods provide a configuration option through properties. It is recommended to use these methods with the provided customization options.
|Available methods||Default behaviour||Reasons for overriding|
|This method returns details on whether the given username and password is matched or not. Credential is usually a String literal.|
If you want to change the authentication logic you can override this method and write your own implementation. The default task of this method is to compare the given password with the stored password. The given credentials are passed to the
|This returns the encrypted or plain-text password based on the configurations.|
You can override this method if you need to change the way you encrypt the password. If you want to change the algorithm that is used for encryption, you can configure it.
The default properties of the user store are returned using this method. These properties are used in user store related operations.
Be sure to manually add the following property when you implement the class:
This property is what controls whether the user store is enabled or disabled.
By overriding this method, you can programmatically change the configuration of the user store manager implementation.
Returns whether the given username is compatible with the defined criteria.
The criteria used for defining a valid username can be configured as a regex in user store configurations. If you want to change the way user name validation is done, override this method.
Returns whether the given password is compatible with the defined criteria. This is invoked when creating a user, updating a password and authorization.
Similar to the user name, you can configure the format of a valid password in configuration. If you want to change that behavior you can override this method.
|Available methods||Default behaviour|
This method is responsible to create a new user based on the given values. We can change the JDBC query or LDAP attribute name with the user store configuration.
This removes the user store record related to the given username.
Responsible to update the credential of the given username after authenticating with the existing password.
Admin users can use this method to update the credentials of a given user. This can be done without validating the existing password.
Creates a new user role with given roleName and maps the given users to newly created role. Shared parameter indicate whether this role is shared among tenant or not.
This method removes the given role and related mappings from the user store.
This method is used to update the name of the existing roles.
This is used to delete the existing mappings between the given user and the
Used to delete the existing mappings between the given role and the
This is responsible for creating a new claim for a given user and profile, with the given claim URI and value.
This is responsible for creating a new claim for a given user and profile, with the given list of claim URIs and values.
Remove the existing claim details mapped with the given user and profile.
Remove the given list of claims from a given user.
This method is used to persist tokens in the user store.
|Available methods||Default behaviour|
|Returns whether the provided |
|Returns whether the provided roleName already exists in the user store.|
|This method returns a list of usernames that match with the given filter string.|
|Returns a list of role names that match with the given filter string.|
|Returns a list of external role names of a given user that match with the given filter string.|
|This method returns a list of shared role names of a given user that match with the given filter string.|
|This method returns values for the given |
|This returns a list of usernames that match with the given value of the given property and |
|Returns names to display in the UI for given usernames.|
|Returns the password expiry date of a given user. The default value is null.|
|This method returns the identifier of a given user name. Default value is 0.|
|Returns a list of profile names mapped with a given user name.|
|This returns a list of role names that are associated with the given tenant domain and match with the filter.|
|This method returns a list of usernames that are mapped with the given rolename.|
|All the profile names are returned including the default profile.|
|This method is used to check if the given token exists for the given user.|
|Returns whether this user store is allowed to have multiple profiles per user. The default value is |
|This method returns whether this user store allows bulk transactions or not.|
In WSO2 Carbon-based products, there are four user store manager classes that implement the
AbstractUserStoreManager class. You can select one of those classes according to the user store that you have in your environment.
|User store manager class||When you would use it|
If your user details are stored in a database, you must use this user store manager implementation. With the abstraction provided in this implementation, most of the JDBC based scenarios can be handled without writing a custom user store manager.
You can use this class if you have an LDAP user store. This implementation does not allow you to insert or update users from the WSO2 product side. Instead you can only read and use them in the product.
If you want to allow the WSO2 product to manipulate user store data, you need to use this implementation.
Active Directory also can be used as the user store of a WSO2 product and you can configure it using this user store manager implementation.
Implementing a custom JDBC user store manager
The instructions in this section are focused on implementing a sample JDBC user store manager. For this sample, the following tools are used to implement the custom user store manager.
- Java 1.6.0
- IDE (Eclipse, InteliJ IDEA, etc.)
- Apache Maven
Setting up the implementation
To set up this implementation, do the following.
- Create a new Apache Maven project with the help of the IDE that you are using. The project should be a simple Apache Maven project and you can use any desired artifact and group ID.
Add the WSO2 user store management .jar file as a dependency of our project. Since this .jar file is stored in WSO2's Maven repository, you must add the WSO2 repository to your POM file. Please see the below sample POM file.
Note: Note that the version number of the carbon dependencies seen below have to be updated according to the carbon kernel version that the particular product version is compatible with. For example, WSO2 IS 5.3.0 is built on top of carbon kernel version 4.4.11 therefore, the version given in the sample pom file below is 4.4.11. Change this value accordingly based on the relevant carbon kernel version of the product you are using by reffering to this release matrix.
Now your basic implementation is ready.
Writing a custom user store manager for a sample scenario
As a sample of how this can be done, consider a scenario where you want to use a custom hashing method using a 3rd party library such as Jasypt. So, in order to do this, you must override the
preparePassword methods as an example.
Do the following steps to write the custom user store manager.
Include the required dependencies in your development environment. To do that, include the relevant Apache Maven dependency details or manually add the .jar files to your classpath. For example, add the following XML snippet under the dependencies tag in your pom.xml file to include the Jasypt dependency.
Create a new class by extending the existing
JDBCUserStoreManagerimplementation. The following code is an example of how this would look.
Note: The default constructor is not enough when you implement a custom user store manager, and you must implement a constructor with relevant arguments.
Deploying and configuring the custom user store manager
Do the following to deploy and configure the custom user store manager in your WSO2 product.
- Copy the artifact of your project (custom-userstore.jar, in this case) to the
<PRODUCT_HOME>/repository/components/dropinsdirectory. Also copy all OSGI bundles to this location. If you have any dependency .jar files, copy them to the
Change the configuration of the WSO2 product to use our custom implementation for user store management. To do this, open the
<PRODUCT_HOME>/repository/conf/user-mgt.xmlfile and change the
Tip: This step provides instructions on configuring your custom user store manager as a primary user store. Alternatively, you can configure this as a secondary user store if you already have a different primary user store configured. For more information configuring user stores in WSO2 products, see Configuring User Stores.
You do not need to change anything else since you extend the JDBCUserStoreManager class, so the configurations will remain the same.
You have now implemented a custom user store manager for a WSO2 product. Once you have done this, start the product and see the log messages that you have placed inside overridden methods when you create a new user or login. This ensures that all your configurations work as intended.