Custom User Store Manager For WSO2 Identity Server 5.11.0

WSO2 Identity Server is shipped with a default H2 database. Even though this database contains the schema of all the information related to the WSO2 Identity Server, user-related information will not be stored in the schema of the H2 database.

Refer this doc to connect to the H2 database and browse through it to check about the WSO2 default database.

So the question is, where should the user-related information be stored?

By default, the user-related information was stored in a separate embedded LDAP database. The special name given to this database is the user store. This is the primary user store of WSO2 Identity Server.

As a definition, a user store is a database where information about the users and user roles is stored, including log-in name, password, first name, last name, and e-mail address etc.

The reason for maintaining a separate database for user-related information is, you can configure secondary and custom user stores according to your requirements. That means you can maintain separate user stores for different requirements.

Refer this doc to understand further about user stores.

Let’s dive into the custom user store section. The custom user store manager is almost the same as a secondary user store manager, but here you can customize the user store manager according to your requirements.

In the secondary user store, there will be a default schema which you want to create using the queries in the following file.

<IS_HOME>/dbscripts/mysql.sql

But in the Custom user store, you can have any type of schema according to your wish. Suppose you have a company which already has a user database and need to authenticate the user through our WSO2 Identity server. In that case, you don’t have to convert the whole database of yours to the WSO2 Identity Server standard schema. You can have your own schema but you have to configure your custom user store manager by overriding methods of `AbstractUserStoreManager` class according to your requirements.

Refer to this doc for the understanding of methods and their behaviors.

Note:- WSO2 IS 5.11 allows only UniqueID user store managers such as

1. UniqueIDReadOnlyLDAPUserStoreManager
2. UniqueIDActiveDirectoryUserStoreManager
3. UniqueIDReadWriteLDAPUserStoreManager
4. UniqueIDJDBCUserStoreManager

Since I am going to configure the custom user store manager for JDBC user stores, I am extending the class `UniqueIDJDBCUserStoreManager` class which is responsible for secondary JDBC user stores.

Finally, let us move on to the implementation of `Custom user store manager`,

1. Create a sample schema for managing user-related data,

SQL query for custom user store

This sample schema can be created as you wish. But make sure you wrote the correct SQL queries in the overriding methods according to the schema you have.

2. 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 ID and group ID.

3. Write the following code into the pom file.

Note :- Note that the version number of the carbon dependencies seen above have to be updated according to the carbon kernel version that the particular product version is compatible with. For example, WSO2 IS 5.11.0 is built on top of carbon kernel version 4.6.1 therefore, the version given in the sample pom file below is 4.6.1. Change this value accordingly based on the relevant carbon kernel version of the product you are using by referring the pom file of your WSO2 IS version you are using.

Refer to OSGi service if you want to understand about the pom file configs and OSGi bundle features more deeply.

4. Create a new class by extending the existing `UniqueIDJDBCUserStoreManager` implementation. The following code is an example of how this would look. (Core implementation)

Here, I have overridden methods for about 2 use cases.

1. Authenticating the user
2. Listing the user of custom user store in WSO2 IS mgt console

doListUsersWithID -> This method is responsible for listing out the users of your custom user store in the management console of WSO2 Identity Server.

doAuthenticateWithUsername -> This method is responsible for Authenticating the user with username and password.

Other methods are responsible for some other sub-use cases which are residing in the above two methods.

Note:- Generally preparePassword is the method which is used in hashing the passwords. But here I have implemented new methods for SHA-256 password hashing such as getSHA and toHexString. You can override the prepare method also to implement your hashing algorithms. It is up to you.

SQL queries will be the main difference between the parent class and child class. Since you are using your custom schema, you should have to focus mainly on SQL queries in your overriding child class methods.

5. Create a class called CustomUserStoreConstants which is responsible for maintaining User store properties.

(Have a look at my GitHub project mentioned at the end of this article.)

6. Then finally, create a CustomUserStoreMgtDSComponent class which is responsible for registering OSGi service which is needed for the creation of OSGi bundle (.jar file).

(Have a look at my GitHub project mentioned at the end of this article.)

Note:- To understand how OSGi service works, refer to this doc.

If you just want to create a custom user store, don't worry about how OSGi works. Just copy-paste the code from my GitHub Project.

7. After all this, build your CustomUserStoreManager bundle.

mvn clean install -e

8. Copy the built jar file from the target folder and paste it in the dropins folder of your Identity Server folder.

<IS_HOME>/repository/components/dropins

9. Copy your MySQL JDBC connector to your lib folder of Identity Server folder.

<IS_HOME>/repository/components/lib

If you have any other external dependencies which are not in your Identity Server Pack, paste those dependencies (.jar files) in the above said lib folder.

10. Configure your deployment.toml file with the following configurations.

If you are using IS 5.11.0,

Here, you need to configure the custom user store manager including the existing user store managers.

[user_store_mgt]
allowed_user_stores=["org.wso2.carbon.user.core.jdbc.UniqueIDJDBCUserStoreManager", "org.wso2.carbon.user.core.ldap.UniqueIDActiveDirectoryUserStoreManager","org.wso2.carbon.user.core.ldap.UniqueIDReadOnlyLDAPUserStoreManager","org.wso2.carbon.user.core.ldap.UniqueIDReadWriteLDAPUserStoreManager","org.wso2.sample.user.store.manager.CustomUserStoreManager""]

If you are using IS 5.12.0,

Here, configuring only the custom user store manager is enough.

[user_store_mgt]
custom_userstores=["org.wso2.sample.user.store.manager.CustomUserStoreManager"]

For further details, check here.

11. Start your Identity Server.

sh wso2server.sh

While the server startup, you can check the identity.xml file in which the allowed user stores will be overridden including your custom user store manager.

Now, navigate to the management console and check the drop-down list in the add user store tab. You could able to see your custom user store manager in the drop-down list.

Great! Now you have successfully implemented your custom user store manager.

12. Configure a custom user store using your custom user store manager.

Custom User Store Specifications

Display Name:- A name you like to give for your custom user store.

Driver Name:- Usually driver name for MySQL database was com.mysql.jdbc.Driver. But if you are using MySQL 8 or above, try with com.mysql.cj.jdbc.Driver in case the above driver name causing ERRORS.

Connection URL:- Connection URL should include your database name and localhost and port number. To suppress SSL errors, it’s better to add useSSL=false at the end of the connection URL.

User Name:- MySQL username which you are using. Generally, it will be root. If you have changed the username. Then use that username instead.

Password:- Password for the above MySQL user. If you have not set a password in the installation process. Then try this doc to set or change the password.

13. Check the use cases of your custom user store working properly or not (overridden methods)

In my custom user store manager I have configured two use cases as I said earlier. So check out your management console as it is listing the users properly and check out myAccount of Identity Server to authenticate users. (you can check authentication with any Service providers like PickupDispatch or Travelocity)

Note:- Even though all the use cases work fine, you could able to see some ERROR exception logs in your command line/terminal while authenticating a custom user. Don’t worry, that is because you did not override other sub-methods which needed. Here we are checking whether our Custom user store is working fine or not with our mentioned use cases. Extending other methods is up to you according to your requirements.

Here is the GitHub repository for the custom user store manager.

nisho06/CustomUserStoreManager

Great! That’s all for this article on Implementing Custom User Store Manager.

Happy Coding !!! Stay Safe! ❤❤❤