This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Configuring an External LDAP User Store

All WSO2 Carbon based products can read and write users and roles from external LDAP user stores. You can configure Carbon products to with your company LDAP in one of the following modes.

  • Read Only mode
  • Read/Write users and Read only groups
  • Read/Write both users and groups


Read Only mode

Follow the instructions below to configure an external LDAP in read only mode.

1. Backup the $GREG_HOME/repository/conf/user-mgt.xml. Download the sample file for LDAP user store and save it as $GREG_HOME/repository/conf/user-mgt.xml. Please, observe the following in your file.

<UserStoreManager class="org.wso2.carbon.user.core.ldap.LDAPUserStoreManager">

2. Find a valid user that resides in the Directory Server. For example, let's say a valid user name is "AdminSOA." Update the Admin user section of your LDAP configuration as follows.

Tip

You do not have to update the password element.

<AdminUser>
<UserName>AdminSOA</UserName>
<Password>XXXXXX</Password>
</AdminUser>

3. To connect the user store in read only mode, make sure the value of the <ReadOnly> element is set to true as follows.

<ReadOnly>true</ReadOnly>

4. Update the connection details to suite your Directory Server.

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

5. Obtain a user who has permission to read all users/attributes and to perform searches on the Directory Server from your LDAP administrator. For example, let's say your privileged user is AdminLDAP and password is 2010#Avrudu. Update the following sections of the realm configuration.

<Property name="ConnectionName">uid=AdminLDAP,ou=system,dc=ABCompany,dc=lk</Property>
<Property name="ConnectionPassword">2010#Avrudu </Property>

6. Update the <Property name="UserSearchBase"> by giving the directory where the users are stored. LDAP searches for users will start from this location.

Property name="UserSearchBase">ou=system,dc=ABCompany,dc=lk</Property>

7. Set the attribute that you wish to use as the username. The most common case is to use either cn or uid as the username. If you are not sure what attribute is available in your LDAP, please, ask your LDAP administrator.

<Property name="UserNameAttribute">uid</Property>

8. This is the most basic configuration. For more advanced options like "external roles," please, jump to next step. Otherwise you are done now start your server and try to login as "AdminSOA." The password is the AdminSOA's password in the LDAP server. If you are unable to login, please, send a mail to carbon user group.

9. The realm can read roles from the Directory Server. It can read user/role mapping based on MembershipAttribute in ApacheDirectory server and OpenLDAP. Following are the properties in user-mgt.xml that are related with LDAP groups.

ReadLDAPGroups property indicates whether to read groups from external LDAP. If this is false then none of the attributes following it, needs to be set and carbon roles will be written and read from internal JDBC database only. If this is true, then carbon roles will be written to internal JDBC database and will be read from both internal JDBC database and external LDAP user store.

<Property name="ReadLDAPGroups">false</Property>
<Property name="GroupSearchBase">ou=system</Property>
<Property name="GroupSearchFilter">(objectClass=groupOfNames)</Property>
<Property name="GroupNameAttribute">cn</Property>
<Property name="MembershipAttribute">member</Property>

Each of the above mentioned properties are described in the Default LDAP User Store Configuration.

Read/Write Users and Read-only Groups

To connect to external LDAP user store such that only the user entries are written to external LDAP and roles are not written to external LDAP, the only difference from the steps in section "Read Only mode" is:

In step 3, set the ReadOnly property to false.

Read/Write Both Users and Groups

From this release onwards, you can configure Carbon products to read and write both users and roles in your company LDAP. Following are the steps that are different from the steps in the section "Read Only mode" above:

9. You may notice the following two additional properties in configuration than those mentioned in the step 9 of the section 6.1 above:

<Property name="WriteLDAPGroups">true</Property>
<Property name="EmptyRolesAllowed">false</Property>

Usually LDAP servers do not allow to create empty groups. Hence the property value EmptyRolesAllowed is by default set to false. When it is set to false, you have to assign at least one user to a role that you are creating through carbon admin console.

Tip

Default value of EmptyRolesAllowed is set to true in latest releases.

Configure an External Active Directory User Store

All WSO2 Carbon based products can read users and roles from external ActiveDirectory user stores. You can configure Carbon products to read users/roles from your company Active Directory. It does not write any data into the Active Directory.

Following are the steps that are different from the steps mentioned in the section "Read Only mode" above.

Step 6. UserNameAttribute for Active Directory is different.

<Property name="UserNameAttribute">sAMAccountName</Property>

Step 8. The realm can read roles from the Active Directory. It can read user/role mapping based on a backlink attribute.

Following are the properties related to reading roles based on a backlink attribute.

<Property name="ReadLDAPGroups">true</Property>
<Property name="GroupSearchBase">cn=users,dc=wso2,dc=lk</Property>
<Property name="GroupSearchFilter">(objectcategory=group)</Property>
<Property name="GroupNameAttribute">cn</Property>
<Property name="MemberOfAttribute">memberOf</Property>

Configure an External JDBC User Store

All Carbon based products can work with external RDBMSes. You can configure Carbon to read users/roles from your company RDBMSes, and if you go one extra mile ever write to it. So the user core will connect to two databases.

  • Carbon database where authorization information is stored in the internal Carbon database.
  • Your company database where users/roles resides.

Note

The user-mgt.xml must contain details for two database connections.

The connection details mentioned in Realm Configuration is used by the Authorization manager. If we specify another set of database connection details inside UserStoreManager, it will read/write users to that database.

1. Backup the $GREG_HOME/repository/conf/user-mgt.xml. Download a sample file for JDBC user store file and save it as $GREG_HOME/repository/conf/user-mgt.xml. Please, observe the following in your file.

<UserStoreManager
class="org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager">

2. Find a valid user that resides in the RDBMS. For example, let's say a valid user name is "AdminSOA." Update the Admin user section of your LDAP configuration as follows.

Tip

You do not have to update the password element.

<AdminUser>
<UserName>AdminSOA</UserName>
<Password>XXXXXX</Password>
</AdminUser>

3. Add the JDBC driver to the classpath by dropping the JAR into $GREG_HOME/repository/components/lib.

4. Update the connection details inside the <UserStoreManager> class.

5. Start the server.