How to configure your preferred user stores to authenticate users

WSO2 Identity server allows keeping multiple user stores for your system to store users and their roles. There should be one primary user store (mandatory) and any number of secondary user stores(optional). When creating a secondary user store we can provide a user store domain name for the secondary user stores. “PRIMARY” is the user store domain of the primary user store.

Now think about a service provider who uses WSO2 Identity Server to authenticate users who log into the application and it maintains multiple user stores in IS.

Now we are going to look at two different ways that users can provide their usernames during the login process:

  1. The user provides the user name with the user store domain (eg: PRIMARY/peter). Then WSO2 IS validate username and password against the values stored in the PRIMARY user store.

You can understand the second point from the highlighted lines in the codebase.

Let’s say the service provider now wants to narrow down the number of user stores that will be searched to authenticate a user when he/she doesn’t provide user store domain-specific username. How can we do this ??

NOTE: This feature is available in IS-5.7.0 WUM updated version and IS-5.9.0 onwards

Let’s head-on with the following example to understand this process more clearly.

Identity Server — Product-IS 5.9.0 (download here)

Service provider — (deploy it according to the given instructions here)

Three Secondary JDBC user stores Named: “DRIVER”, “MANAGER”, “CUSTOMER” (instructions: here)

Add users according to the following table: (instructions: here)

Authenticating condition: Only the users in PRIMARY, DRIVER and MANAGER user store can access services. Users in the CUSTOMER user store can’t use services in

Moreover, users don’t know their user store domain. Thus, they input username without the user store domain. (i.e username is just ‘peter’ not like ‘MANAGER/peter’).

Without any further configurations, try to login to app and using four different username-password combinations in the table. You will be succeeded.

Let’s narrow down the number of user stores allowed for login.

You need to do two things:

  1. Implement ​ UserStorePreferenceOrderSupplier ​ interface with your own logic to retrieve the allowed user stores.

2. Then extend ​ CallBackHandlerFactory ​ and create an object of your custom UserStorePreferenceOrderSupplier.

This is the logic implemented according to the above requirement.

  1. CustomUserStoreOrderCallbackFactory class extends CallBackHandlerFactory.

NOTE: in the pom.xml file, you need to update the org.wso2.carbon.identity.framework dependency version according to the IS pack you are using.


Also, Make sure the carbon-kernal which is used in the IS pack lies in the defined range.

<carbon.kernel.package.import.version.range>[4.4.0, 5.0.0)</carbon.kernel.package.import.version.range>

NOW what should we do ??

  1. Build the repo which contains the login using mvn clean install command.
<ApplicationAuthentication xmlns=”​​ “>



NOTE: From IS-5.10.0 onwards this modification should be done through <IS-HOME>/repository/conf/deployment.toml file. Add the following lines to deployment.toml.

callback_factory = “org.wso2.carbon.identity.custom.callback.userstore.CustomUserStoreOrderCallbackFactory”

5. Start the server by issuing ./ (Linux)/ ./wso2server.bat (Windows) on terminal navigating to <IS-HOME>/bin

6. Navigate ​ Main -> Registry -> Browse ​ and ​ click on Browse.

7. Navigate to _system -> config. You will find a file named userstore-metadata.xml(This file is defined in the CustomCallbackUserstoreServiceComponent class as REG_PATH) Click on userstore-metadata.xml.

8. Click + button in Properties tab. It will appear as follows. These values will be used when authenticating users.

Now try to log into the using the username-password pairs we introduced at the beginning.

The result:

Users in PRIMARY/ MANAGER/ DRIVER user stores will log into the system.

Users in the CUSTOMER user store will fail to login.

We are done!! Don’t forget to applause if you get something by this blog.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Anuradha Karunarathna

Senior Software Engineer@ WSO2 | Computer Science and Engineering graduate@ University of Moratuwa, SriLanka