Writing a Custom User Store Manager

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

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. 

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.

Important methods

setOptionalProperty("Disabled", "false", "Whether user store is disabled");

Read-write methods

Read methods

Implementations

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.

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.

1. 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. 

2. 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.

   <?xml version="1.0" encoding="UTF-8"?>
   <project xmlns="http://maven.apache.org/POM/4.0.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
       <modelVersion>4.0.0</modelVersion>
       <groupId>org.wso2.sample</groupId>
       <artifactId>CustomReadOnlyJDBCUserStoreManager</artifactId>
       <version>1.0.0</version>
       <packaging>bundle</packaging>
       <repositories>
           <repository>
               <id>wso2-nexus</id>
               <name>WSO2 internal Repository</name>
               <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
               <releases>
                   <enabled>true</enabled>
                   <updatePolicy>daily</updatePolicy>
                   <checksumPolicy>ignore</checksumPolicy>
               </releases>
           </repository>
       </repositories>
       <dependencies>
           <dependency>
               <groupId>org.wso2.carbon</groupId>
               <artifactId>org.wso2.carbon.user.core</artifactId>
               <version>4.4.11</version>
           </dependency>
           <dependency>
               <groupId>org.wso2.carbon</groupId>
               <artifactId>org.wso2.carbon.utils</artifactId>
               <version>4.4.11</version>
           </dependency>
           <dependency>
               <groupId>org.wso2.carbon</groupId>
               <artifactId>org.wso2.carbon.user.api</artifactId>
               <version>4.4.11</version>
           </dependency>
       </dependencies>
   
       <build>
           <plugins>
               <plugin>
                   <artifactId>maven-compiler-plugin</artifactId>
                   <version>2.3.1</version>
                   <inherited>true</inherited>
                   <configuration>
                       <encoding>UTF-8</encoding>
                       <source>1.7</source>
                       <target>1.7</target>
                   </configuration>
               </plugin>
               <plugin>
                   <groupId>org.apache.felix</groupId>
                   <artifactId>maven-scr-plugin</artifactId>
                   <version>1.7.2</version>
                   <executions>
                       <execution>
                           <id>generate-scr-scrdescriptor</id>
                           <goals>
                               <goal>scr</goal>
                           </goals>
                       </execution>
                   </executions>
               </plugin>
               <plugin>
                   <groupId>org.apache.felix</groupId>
                   <artifactId>maven-bundle-plugin</artifactId>
                   <version>2.3.5</version>
                   <extensions>true</extensions>
                   <configuration>
                       <instructions>
                           <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
                           <Bundle-Name>${project.artifactId}</Bundle-Name>
                           <Private-Package>
                               org.wso2.sample.user.store.manager.internal
                           </Private-Package>
                           <Export-Package>
                               !org.wso2.sample.user.store.manager.internal,
                               org.wso2.sample.user.store.manager.*,
                           </Export-Package>
                           <Import-Package>
                               org.wso2.carbon.*,
                               org.apache.commons.logging.*,
                               org.osgi.framework.*,
                               org.osgi.service.component.*
                           </Import-Package>
                       </instructions>
                   </configuration>
               </plugin>
           </plugins>
       </build>
   </project>

   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 doAuthentication and preparePassword methods as an example.

Do the following steps to write the custom user store manager.

1. 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.

   <dependency>
       <groupId>org.jasypt</groupId>
       <artifactId>jasypt</artifactId>
       <version>1.9.2</version>
   </dependency>

2. Create a new class by extending the existing JDBCUserStoreManager implementation. The following code is an example of how this would look.

   package com.wso2.custom.usermgt;
   
   import org.apache.commons.logging.Log;
   import org.apache.commons.logging.LogFactory;
   import org.jasypt.util.password.StrongPasswordEncryptor;
   import org.wso2.carbon.user.api.RealmConfiguration;
   import org.wso2.carbon.user.core.UserRealm;
   import org.wso2.carbon.user.core.UserStoreException;
   import org.wso2.carbon.user.core.claim.ClaimManager;
   import org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager;
   import org.wso2.carbon.user.core.profile.ProfileConfigurationManager;
   
   import java.sql.Connection;
   import java.sql.PreparedStatement;
   import java.sql.ResultSet;
   import java.sql.SQLException;
   import java.sql.Timestamp;
   import java.util.Date;
   import java.util.GregorianCalendar;
   import java.util.Map;
   
   public class CustomUserStoreManager extends JDBCUserStoreManager {
      private static Log log = LogFactory.getLog(StarkUserStoreManager.class);
      // This instance is used to generate the hash values
      private static StrongPasswordEncryptor passwordEncryptor = new StrongPasswordEncryptor();
   
      // You must implement at least one constructor
      public CustomUserStoreManager(RealmConfiguration realmConfig, Map<String, Object> properties, ClaimManager
              claimManager, ProfileConfigurationManager profileManager, UserRealm realm, Integer tenantId)
              throws UserStoreException {
          super(realmConfig, properties, claimManager, profileManager, realm, tenantId);
          log.info("CustomUserStoreManager initialized...");
      }
   
      @Override
      public boolean doAuthenticate(String userName, Object credential) throws UserStoreException {
          boolean isAuthenticated = false;
          if (userName != null && credential != null) {
              try {
                  String candidatePassword = String.copyValueOf(((Secret) credential).getChars());
   
                  Connection dbConnection = null;
                  ResultSet rs = null;
                  PreparedStatement prepStmt = null;
                  String sql = null;
                  dbConnection = this.getDBConnection();
                  dbConnection.setAutoCommit(false);
                  // get the SQL statement used to select user details
                  sql = this.realmConfig.getUserStoreProperty("SelectUserSQL");
                  if (log.isDebugEnabled()) {
                      log.debug(sql);
                  }
   
                  prepStmt = dbConnection.prepareStatement(sql);
                  prepStmt.setString(1, userName);
                  // check whether tenant id is used
                  if (sql.contains("UM_TENANT_ID")) {
                      prepStmt.setInt(2, this.tenantId);
                  }
   
                  rs = prepStmt.executeQuery();
                  if (rs.next()) {
                      String storedPassword = rs.getString(3);
   
                      // check whether password is expired or not
                      boolean requireChange = rs.getBoolean(5);
                      Timestamp changedTime = rs.getTimestamp(6);
                      GregorianCalendar gc = new GregorianCalendar();
                      gc.add(GregorianCalendar.HOUR, -24);
                      Date date = gc.getTime();
                      if (!(requireChange && changedTime.before(date))) {
                          // compare the given password with stored password using jasypt
                          isAuthenticated = passwordEncryptor.checkPassword(candidatePassword, storedPassword);
                      }
                  }
                  log.info(userName + " is authenticated? " + isAuthenticated);
              } catch (SQLException exp) {
                  log.error("Error occurred while retrieving user authentication info.", exp);
                  throw new UserStoreException("Authentication Failure");
              }
          }
          return isAuthenticated;
      }
   
      @Override
      protected String preparePassword(Object password, String saltValue) throws UserStoreException {
          if (password != null) {
              String candidatePassword = String.copyValueOf(((Secret) password).getChars());
   			// ignore saltValue for the time being
              log.info("Generating hash value using jasypt...");
              return passwordEncryptor.encryptPassword(password);
          } else {
              log.error("Password cannot be null");
              throw new UserStoreException("Authentication Failure");
          }
      }
   }

   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.

1. Copy the artifact of your project (custom-userstore.jar, in this case) to the <PRODUCT_HOME>/repository/components/dropins directory. Also copy all OSGI bundles to this location. If you have any dependency .jar files, copy them to the <PRODUCT_HOME>/repository/components/lib directory.

2. 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.xml file and change the UserStoreManager class.

   <UserStoreManager class="com.wso2.custom.usermgt.CustomUserStoreManager">

   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.