WSO2 Enterprise Integrator 9 min

WSO2TORIAL Configure WSO2 ESB to use an LDAP Server

Rob Blaauboer
Rob Blaauboer
Integration Consultant & WSO2 Trainer
Apache Directory

WSO2 products can use several types of databases as their primary user store. In most products the embedded database H2 is included. This database needs to be exchanged for a ‘real’ database whenever you move beyond downloading and testing a WSO2 product on your own computer.


You have the choice of database when you want to exchange H2 with basically the option to use any database with a JDBC connector. The DBSCRIPT directory has a number of scripts for well known databases like MySQL, MSSQL and others like Oracle.

But you can also use an LDAP or Active Directory database as a user store. In this WSO2TORIAL we will use an LDAP in read/write mode as a userstore.

We will use Apache Directory Studio since this is also used by WSO2 Identity Server for it’s embedded LDAP. IS is the only product that has an embedded LDAP as a primary user store. However, it also includes H2 since not all user and role data is stored in the LDAP.

Apache Directory Studio

First of all we need to download Apache DS. This is a so called fat client, meaning that you need to select the OS that you use when downloading:

Apache Directory.png

You can find the Apache Directory Studio at http://directory.apache.org/studio/

After selecting your OS and subsequent version (32 bit or 64 bit) you can unpack and start Apache Directory Studio by clicking on the icon.

Apache Directory Studio Icon.png

Configure ApacheDS

ApacheDS is an Eclipse based product and for users of WSO2 Developer Studio as well as more generally Eclipse as and IDE a well know product.

We will start by creating an LDAP server on the LDAP tab. Please change the view (Windows/Show view/Other/LDAP Servers) if the LDAP Servers window is not visible.

Change view new LDAP server.png

We select LDAP server ApacheDS 2.0.0 and click Finish.

We will leave the LDAP server ports as they are since there is no need  to change it (no other Apache DS products are running). We access the overview by right-clicking on the server and opening the configuration.

Access overview LDAPLDAPS servers.png

Create a connection

Right-click on the server that has been created and click Create a Connection. A connection with the default settings will be created.

Create a connection LDAP Server.png

Connection created Copy of ApacheDS 2.0.0.png

We can now start the server:

Start the LDAP server.png

Either Right-click on the server and run or use the green button with the right arrow in the top bas of the LDAP Window.

Setting up the ESB 5.0.0

You need to create a fresh copy of the WSO2 ESB 5.0.0. Please see here if you have questions on how to do that.

We will describe a situation where there is no other WSO2 product running locally (so no needed portOffset) and will refer to the location where you installed the product as [ESB-HOME].

Open the [ESB-HOME]/repository/conf/user-mgt.xml.  We need to do four things:

  1. Comment out the JDBC User StoreComment out the JDBC User Store.pngJDB User Store 2.png
  2.  Change the <ISUserStoreManager>..</ISUserStoreManager> tags to <UserStoreManager> and uncomment it

Change the IS User Store Manager.png


UserStoreManager - Tenant Manager.png

All other user store managers in user-mgt.xml must be commented out at this point.

In order to connect to an external ldap a new user store manager needs to be defined in the user-mgt.xml file. For simplicity, the (IS) user store for the embedded ldap server can be reused and modified to connect to the external LDAP server.

The tags in BOLD need to be changed. We will not discuss any specific settings in the UserStoreManager, please check the WSO2 online documentation for more information.

<!--Using an External LDAP server as the primary user store -->
<UserStoreManager class="org.wso2.carbon.user.core.ldap.ReadWriteLDAPUserStoreManager">
 <Property name="TenantManager">org.wso2.carbon.user.core.tenant.CommonHybridLDAPTenantManager</Property>
 <Property name="ConnectionURL">???</Property>
 <Property name="ConnectionName">???</Property>
 <Property name="ConnectionPassword">???</Property>
 <Property name="UserSearchBase">???</Property>
 <Property name="UserEntryObjectClass">???</Property>
 <Property name="UserNameAttribute">uid</Property>
 <Property name="UserNameSearchFilter">(&amp;(objectClass=person)(uid=?))</Property>
 <Property name="UserNameListFilter">(objectClass=person)</Property>
 <Property name="DisplayNameAttribute"/>
 <Property name="ReadGroups">true</Property>
 <Property name="WriteGroups">true</Property>
 <Property name="GroupSearchBase">???</Property>
 <Property name="GroupEntryObjectClass">groupOfNames</Property>
 <Property name="GroupNameAttribute">cn</Property>
 <Property name="GroupNameSearchFilter">(&amp;(objectClass=groupOfNames)(cn=?))</Property>
 <Property name="GroupNameListFilter">(objectClass=groupOfNames)</Property>
 <Property name="MembershipAttribute">member</Property>
 <Property name="BackLinksEnabled">false</Property>
 <Property name="UsernameJavaRegEx">[a-zA-Z0-9._-|//]{3,30}$</Property>
 <Property name="UsernameJavaScriptRegEx">^[S]{3,30}$</Property>
 <Property name="UsernameJavaRegExViolationErrorMsg">Username pattern policy violated</Property>
 <Property name="PasswordJavaRegEx">^[S]{5,30}$</Property>
 <Property name="PasswordJavaScriptRegEx">^[S]{5,30}$</Property>
 <Property name="PasswordJavaRegExViolationErrorMsg">Password length should be within 5 to 30 characters</Property>
 <Property name="RolenameJavaRegEx">[a-zA-Z0-9._-|//]{3,30}$</Property>
 <Property name="RolenameJavaScriptRegEx">^[S]{3,30}$</Property>
 <Property name="SCIMEnabled">false</Property>
 <Property name="IsBulkImportSupported">false</Property>
 <Property name="EmptyRolesAllowed">true</Property>
 <Property name="PasswordHashMethod">PLAIN_TEXT</Property>
 <Property name="MultiAttributeSeparator">,</Property>
 <Property name="MaxUserNameListLength">100</Property>
 <Property name="MaxRoleNameListLength">100</Property>
 <Property name="kdcEnabled">false</Property>
 <Property name="defaultRealmName">EXPERIA.COM</Property>
 <Property name="UserRolesCacheEnabled">true</Property>
 <Property name="ConnectionPoolingEnabled">false</Property>
 <Property name="LDAPConnectionTimeout">5000</Property>
 <Property name="ReadTimeout"/>
 <Property name="RetryAttempts"/>

Settings on the LDAP

Right-click on the connection and click Open Configuration. The default settings for LDAP are as follows:

Setting on the LDAP.png

Next, update the following properties for the external Read-Write user store in the user-mgt.xml, as required. The steps are given below.

  • ConnectionURL
  • ConnectionName
  • ConnectionPassword
  • UserSearchBase
  • UserEntryObjectClass
  • GroupSearchBase

For the ConnectionURL, begin by updating the connection URL to the user store server (see the screenshot :

 <Property name="ConnectionURL">ldap://localhost:10389</Property>

For the ConnectionName right-click on the connection, click Properties and then click Authentication and modify the <Property name=”ConnectionName”> according to the Authentication Parameter.

Properties for APacheDS 2.0.0.png

The connection name is the username given as the Bind DN or user in the Authentication properties of the connection. The user is used to connect to the database and perform various operations. This user does not have to be an administrator in the user store or have an administrator role in the WSO2 product that you are using, but this user MUST have permissions to read the user list and users’ attributes and to perform search operations on the user store. This value is the DN (Distinguish Name) attribute of the user.

You copy the Bind DN or user to the connection name property:

<Property name="ConnectionName">uid=admin,ou=system</Property>

Next, add the connection password. This is the password for the user entered in the ConnectionName property. Click on the admin user that is created by default to open up the related details.

add connection password.png

Double-click on the user password and click the Show Current Password Details check box. The current password is displayed. Modify the property name accordingly.

Show Current Password Details.png

<Property name="ConnectionPassword">secret</Property>

Next, update the user search base property.

Update user search base property.png

This is the DN of the context or object under which the user entries are stored in the user store. i.e. the “users” container.

Users Container.png

To find a suitable UserEntryObjectClass, refer to the documentation on the directory service. For ApaceDS, refer to https://directory.apache.org/apacheds/basic-ug/2.3.1-adding-schema-elements.html. The most common value for the UserEntryObjectClass is inetOrgPerson. The entry should look as follows:

<Property name="UserEntryObjectClass">inetOrgPerson</Property>

Enter the group search base. This is the DN of the context under which the user entries are stored in the user store.

LDAP Browser.png

DN of the context LDAP browser.png

<Property name="GroupSearchBase">ou=groups,ou=system</Property>

In order to reduce the complexity constraints of adding a username  and password, go to Password Policies tab of the configuration window. Change the Check Quality option under the Quality section to Disabled.

Change Quality Section to Disabled - LDAP server.png

Change the Quality setting and save the changes.

Password Policies Details ApacheDS 2.0.0.png

Open the user-mgt.xml file, edit the realm configuration as follows:

           <EveryOneRoleName>everyone</EveryOneRoleName> <!-- By default users in this role sees the registry root -->
           <Property name="dataSource">jdbc/WSO2CarbonDB</Property>


Starting the Apache DS and ESB

In order to test our new setup, start the Apache DS as well as the LDAP within it (if not aalready running) and start the ESB in the regular way ([ESB-HOME]/bin/wso2server.sh (or .bat).

You can now create a new user that will be stored in the LDAP. Please remember that the admin password is now ‘secret’ rather than ‘admin’.

  1. Log in ESB with the LDAP username and password (i.e. admin/secret)
  2. Create a user in the ESB.
  3. View the user created and stored in ApacheDS using the Apache Directory Studio.
  4. The user has now been stored in the ApacheDS that we installed externally to the IS.

Thanks to Chinmaya Tripathy

Also read our other WSO2 tutorials and blogs, written by our WSO2 Gurus. In case you need WSO2 support, contact the Yenlo WSO2 Guru team to get WSO2 Development Support or WSO2 Operational Support. Of course we do deliver excellent WSO2 training services as well, based on reallife WSO2 tutorials.

ESB Selection Guide

esb frontback
Get it now
We appreciate it
Care to share

Please select one of the social media platforms below to share this pages content with the world