Add info on how it works when multiple user stores are configured

en/docs/deploy/configure-user-store-preference-order.md

@@ -0,0 +1,41 @@
+# Configure the user store preference order
+
+From WSO2 Identity server 5.9.0 onwards, admins can configure the user store preference order for a service provider during the authentication.
+
+This guide helps you to configure the user store preference order for a service provider.
+
+## Initial set up
+
+To set up the WSO2 identity Server to configure the user store preference order:
+
+1. Implement the `UserStorePreferenceOrderSupplier` interface with your own logic to retrieve the user store order.
+
+    Use the provided template to implement the [UserStorePreferenceOrderSupplier interface](https://github.com/wso2/carbon-kernel/blob/feeae3e4668b805c8d6d5e8c115897fa93b8a856/core/org.wso2.carbon.user.core/src/main/java/org/wso2/carbon/user/core/config/UserStorePreferenceOrderSupplier.java?source=post_page-----cdadf43f9366--------------------------------).
+
+2. Extend ​the `CallBackHandlerFactory` ​interface and create an object of your custom `UserStorePreferenceOrderSupplier`.
+
+    Use the provided template to extend the [CallBackHandlerFactory interface](https://github.com/wso2/carbon-identity-framework/blob/master/components/authentication-framework/org.wso2.carbon.identity.application.authentication.framework/src/main/java/org/wso2/carbon/identity/application/authentication/framework/handler/request/CallBackHandlerFactory.java?source=post_page-----cdadf43f9366--------------------------------).
+
+3. Add the following configuration to the `<IS-HOME>/repository/conf/deployment.toml` file to configure the `CallBackHandlerFactory` ​interface.
+
+    ```
+    [authentication.framework.extensions]
+    callback_factory = "org.wso2.carbon.identity.custom.callback.userstore.CustomUserStoreOrderCallbackFactory"
+    ```
+
+4. Restart the WSO2 Identity Server if it's already running.
+
+## Update the preference order
+
+To update the preference order:
+
+1. On the WSO2 Identity Server Management Console, go to **Main** > **Registry** > **Browse**
+2. Navigate to **_system** > **config** and click on `userstore-metadata.xml` file.
+3. Go to **Properties** and click `+`. The table shows the values obtained from the Following are the details represented in the table.
+
+    | Parameter | Description   |
+    |-----------|---------------|
+    | Name      | Name of the service provider to which the user store preference order is applied.    |
+    | Value     | The user store preference order in which the WSO2 Identity Server will authenticate the users logging into the specified service provider.   |
+
+4. Click **Edit** to modify the values.

en/docs/deploy/configure-user-stores.md

@@ -1,57 +1,71 @@
-# Configure Userstores
+# Configure User stores
 
-WSO2 Identity Server allows configuring multiple userstores to your system that
-are used to store users and their roles (Groups). Out of the box, WSO2
-Identity Server supports JDBC, LDAP, and Active Directory userstores with the
-capability of configuring custom userstores. There are different userstore adapters called *Userstore managers*, which are used to connect
-with these userstore types.
+WSO2 Identity Server allows configuring multiple user stores to your system that are used to store users and their roles (Groups). Out of the box, the WSO2 Identity Server supports JDBC, LDAP, and Active Directory user stores with the capability of configuring custom user stores. Different user store adapters called **Userstore managers** are used to connect with these user store types.
 
-There are two types of userstores - Primary Userstore (Mandatory) and
-Secondary userstores (Optional). All the supported userstores can be
-configured under these two types.
+There are two types of user stores:
 
-![user-store-types]({{base_path}}/assets/img/deploy/user-store-types.png) 
+- [Primary user store (Mandatory)](#primary-user-store)
+- [Secondary user stores (Optional)](#secondary-user-store)
+
+All the supported user stores can be configured under these two types.
+
+![user-store-types]({{base_path}}/assets/img/deploy/user-store-types.png){ width:"350"}
 
 ---
 
-## Primary userstore (Mandatory)
+## Primary user store
 
-This is the main user store that is shared among all the
-[tenants]({{base_path}}/references/concepts/introduction-to-multitenancy/)
-in the system. Only one userstore should be configured as the primary
-userstore and it is configured in the
-`         <IS_HOME>/repository/conf/deployment.toml       ` file. By default,
-WSO2 Identity Server uses the embedded H2 database as the primary user store.
-It is recommended to change this default configuration in the production
-system.
+This is the main user store that is shared among all the [tenants]({{base_path}}/references/concepts/introduction-to-multitenancy/) in the system. Only one user store should be configured as the primary
+user store, and it is configured in the `<IS_HOME>/repository/conf/deployment.toml` file. The WSO2 Identity Server uses the embedded H2 database as the primary user store by default. It is recommended to change this default configuration in the production system.
 
-see, [Configure the Primary Userstore]({{base_path}}/deploy/configure-the-primary-user-store)
+Learn more on how to [configure the primary serstore]({{base_path}}/deploy/configure-the-primary-user-store).
 
 ---
 
-## Secondary userstore(s) (Optional)
+## Secondary user store
 
-Any number of secondary userstores can be easily set up for your system.
-These userstores are specific to the created tenant, and they are
-not shared among multiple tenants.  
-You can use the management console to create secondary userstores or
-you can create them manually. These will be stored in an xml file with the
-configurations corresponding to the secondary userstore.
+You can easily set up any number of secondary user stores for your system. These user stores are specific to the created tenant and are not shared among multiple tenants. You can use the management console to create secondary user stores or manually create them. These will be stored in an XML file with the configurations corresponding to the secondary store.
 
-see, [Configure a Secondary Userstore]({{base_path}}/deploy/configure-secondary-user-stores)
+Learn more on how to [configure a secondary userstore]({{base_path}}/deploy/configure-secondary-user-stores)
 
 ---
 
 ## Userstore manager
 
-Adapters used to connect with different userstores are called *Userstore Managers*. By default, there are userstore managers for JDBC,
-LDAP and Active Directory userstores. If you need to add a new userstore implementation, see [Write a Custom Userstore
-Manager]({{base_path}}/references/extend/write-a-custom-user-store-manager). When you configure the
-userstore, you have to set the userstore manager class name.
-
-!!! info 
-    The permissions attached to roles are always stored in an RDBMS. With
-    the default configurations, permissions are stored in the embedded H2
-    database. For information on how to set up a RDBMS repository for
-    storing permission, see [Configure the Authorization
-    Manager]({{base_path}}/deploy/configure-the-authorization-manager)
+Userstore Managers are adapters used to connect with different user stores. By default, there are user store managers for JDBC, LDAP, and Active Directory user stores.
+
+If you need to add a new user store implementation, see [write a custom userstore manager]({{base_path}}/references/extend/write-a-custom-user-store-manager) for more information. When configuring the userstore, you must set the userstore manager class name.
+
+!!! info
+    The permissions attached to roles are always stored in an RDBMS. With the default configurations, permissions are stored in the embedded H2 database. For information on how to set up an RDBMS repository for storing permission, see [configure the authorization manager]({{base_path}}/deploy/configure-the-authorization-manager)
+
+## How it works
+
+When users try to log in to an application with multiple user stores integrated, the following flows happen depending on the method the user provides the username.
+
+- **If the user specifies the user store domain**:
+
+    1. The user tries to log into the application by providing credentials with the user store name.
+
+        Example: Username: `PRIMARY/johnd`
+
+    2. WSO2 Identity Server checks the specified user stores for the availability of the user and authenticates the user.
+
+    Once the user credentials are validated, the user will be able to access the application.
+
+- **If the user doesn't specify the user store domain**:
+
+    1. The user tries to log into the application by providing credentials without the user store name.
+
+        Example: Username: `johnd`
+
+    2. WSO2 Identity Server checks the user stores for the availability of the user and authenticates the user.
+
+        1. Initially, the identity server checks the user's credentials against the PRIMARY user store, which is the first verification line.
+
+        2. If the credentials are not validated in the PRIMARY user store, the identity server proceeds to verify the credentials against the configured secondary user stores.
+
+    Once the user credentials are validated, the user will be able to access the application.
+
+    !!! note
+        Refer to [configure user store preference order]({{base_path}}/deploy/configure-user-store-preference-order.md) if you need to configure a preference order for the user stores when authenticating the users.

en/mkdocs.yml

@@ -382,6 +382,7 @@ nav:
               - Configure a Read-write LDAP User store: deploy/configure-a-read-write-ldap-user-store.md
             - Add High Availability for LDAP: deploy/add-high-availability-for-ldap.md
             - Configure Secondary User stores: deploy/configure-secondary-user-stores.md
+            - Configure user store preference order: deploy/configure-user-store-preference-order.md
             #- Carbon Remote User Store Manager: deploy/carbon-remote-user-store-manager.md
             - Work with Properties of User stores: deploy/work-with-properties-of-user-stores.md
             #- Write a Custom User store Manager: deploy/write-a-custom-user-store-manager.md