Creating a custom user registry as a Liberty user feature

How to create a Liberty user feature for a Custom User Registry implementation and configure it in a Liberty profile as a user registry for authentication.

A custom registry is a registry that you implement using the Java interface, as provided by the product. A custom registry can support virtually any type of account repository from a relational database, flat file, and so on. For this sample, a file-based user registry is implemented by the file and users and groups are defined in the users.props and groups.props files (see the Custom User Registry sample to download the files).

In this sample, WebSphere Application Server Developer Tools are used to create a Liberty feature for the custom user registry implementation. An OSGi bundle is created with bundle activation and file is imported. The Activation class is modified to register it as an OSGi service and to receive configuration data. The Liberty feature is created with the OSGi bundle which can be installed into an existing Liberty profile server and used to configure a custom user registry for user applications.

Attention: The sample provided is intended to familiarize you with this feature. Do not use this sample in an actual production environment.


  1. Implement the custom user registry ( file). For more information, see Developing the UserRegistry interface for using custom registries.
  2. Creating an OSGi bundle with Bundle Activation. This can be achieved by using Eclipse and the WDT tool. For more information, see Developing an OSGi bundle with simple activation
    1. Create an OSGi Bundle Project and choose to create an Activator class
    2. Import the file
    3. Change the Activator class to extend the FileRegistrySample class and implement BundleActivator, ManagedService
    4. Register the services. Add processing so that user and groups files defined in the server.xml file are passed to the file. The Liberty profile configuration is managed by the OSGi Configuration Admin service and can be accessed according to the OSGi Configuration Admin service specification.
    5. Make sure that correct import statements are added for the bundle.
  3. Create the Liberty Feature using the tool:
    1. Click on New -> OSGi -> Liberty Feature
    2. Add the OSGi bundle which was created in the above step
    3. It will create a file which is later renamed as the file
    4. This feature can be installed into the runtime by right clicking the feature name in the tool and choosing "Install Feature"
    5. For more information, see Liberty profile: Product extension
  4. Export the Liberty feature: Right-click on the feature name and export the feature as an .esa file
  5. Install the feature: Install the exported .esa file by running the command below from the bin directory in the Liberty profile installation:
        featureManager install sampleCustomUserRegistry-1.0.esa

    This will put the feature bundle in the ${wlp.user.dir}/extension/lib directory and the .mf file in the ${wlp.user.lib}/extension/lib/features directory.

  6. Configure the server.xml file:
    1. After the feature is installed into the user product extension location, configure the server.xml file with the feature name. For example:
    2. Add the configuration information:
      <customUserRegistry usersFile="${server.config.dir}/resources/security/users.props" groupsFile="${server.config.dir}/resources/security/groups.props" />
    3. Add an application which will use this custom user registry for authentication. For example,
      <application type="ear" id="SecureEJBSample" name="SecureEJBSample" location="${server.config.dir}/apps/SecureEJBSample.ear">
              <security-role name="servletRole">
                <special-subject type="ALL_AUTHENTICATED_USERS" />
              <security-role name="ejbRole">
                <user name="user1" />
  7. Execute the application:
    1. Access the protected resource. For example:
    2. At the prompt, enter the valid user from custom user registry which is also mapped to a role in the application binding for authorization:
      • user: user1
      • password: user1pwd
    3. Confirm that the servlet output is as follows:
      In SecureEJBServlet, Hello Secure EJB World.

Files needed for the sample:

The following files are included in the CustomUserRegistrySample.jar file:

  1. The sampleCustomUserRegistry-1.0_1.0.0.201306201237.esa file contains the sample custom user registry source and binaries
  2. The users.props file contains sample users and it is in the CustomUserRegistrySample server’s resources/security directory
  3. The groups.props file contains sample groups and it is in the CustomUserRegistrySample server’s resources/security directory
  4. The SecureEJBSample.ear file contains sample application and source and it is in the CustomUserRegistrySample server’s apps directory