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.
Choices
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:
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.
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.
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.
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.
We can now start the server:
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:
- Comment out the JDBC User Store
- Change the <ISUserStoreManager>..</ISUserStoreManager> tags to <UserStoreManager> and uncomment it
Becomes
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">(&(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">(&(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"/>
</UserStoreManager>
Settings on the LDAP
Right-click on the connection and click Open Configuration. The default settings for LDAP are as follows:
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.
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.
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.
<Property name="ConnectionPassword">secret</Property>
Next, update the user search base property.
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.
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.
<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 the Quality setting and save the changes.
Open the user-mgt.xml file, edit the realm configuration as follows:
<UserManager>
<Realm>
<Configuration>
<AddAdmin>true</AddAdmin>
<AdminRole>admin</AdminRole>
<AdminUser>
<UserName>admin</UserName>
<Password>secret</Password>
</AdminUser>
<EveryOneRoleName>everyone</EveryOneRoleName> <!-- By default users in this role sees the registry root -->
<Property name="dataSource">jdbc/WSO2CarbonDB</Property>
</Configuration>
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’.
- Log in ESB with the LDAP username and password (i.e. admin/secret)
- Create a user in the ESB.
- View the user created and stored in ApacheDS using the Apache Directory Studio.
- 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.
