Page Comparison

Every WSO2 product comes with an embedded, internal user store, which is configured in <PRODUCT_HOME>/repository/conf/user-mgt.xml file. In WSO2 Identity Server, the embedded user store is LDAP, and in other products it is JDBC. Because the domain name (unique identifier) of this default user store is set to PRIMARY by default, it is called the primary user store.

...

Anchor

	LDABActive
	LDABActive

Configuring an external LDAP user store/active directory

All WSO2 products can read and write users and roles from external Active Directory/LDAP user stores. You can configure WSO2 products to access the Active Directory/LDAP user stores using one of the following modes.

Read-only mode

When you configure a product to read users/roles from your company LDAP in the 'Read Only' mode, it does not write any data into the LDAP.

Given below are samples for LDAP and Active Directory user stores in the <PRODUCT_HOME> /repository/conf/user-mgt.xml file.

Localtabgroup

Localtab

active	true
title	LDAP User Store

LDAP user store sample:

Code Block

language	html/xml

<UserManager>
 <Realm>
   <Configuration>
      <AdminRole>admin</AdminRole>
      <AdminUser>
         <UserName>admin</UserName>
         <Password>XXXXXX</Password>
      </AdminUser>
      <EveryOneRoleName>everyone</EveryOneRoleName>
      <!-- By default users in this role sees the registry root -->
      <Property name="dataSource">jdbc/WSO2CarbonDB</Property>
      <Property name="MultiTenantRealmConfigBuilder">org.wso2.carbon.user.core.config.multitenancy.SimpleRealmConfigBuilder</Property>
   </Configuration>
 
   <UserStoreManager class="org.wso2.carbon.user.core.ldap.ReadOnlyLDAPUserStoreManager"> 
      <Property name="TenantManager">org.wso2.carbon.user.core.tenant.CommonHybridLDAPTenantManager</Property>
	  <Property name="ConnectionURL">ldap://localhost:10389</Property>
      <Property name="ConnectionName">uid=admin,ou=system</Property>
      <Property name="ConnectionPassword">admin123</Property>
      <Property name="UserSearchBase">ou=system</Property>
      <Property name="UserNameListFilter">(objectClass=person)</Property>
      <Property name="UserNameAttribute">uid</Property>
      <Property name="ReadLDAPGroups">false</Property>
      <Property name="GroupSearchBase">ou=system</Property>
      <Property name="GroupNameSearchFilter">(objectClass=groupOfNames)</Property>
      <Property name="GroupNameAttribute">cn</Property>
      <Property name="MembershipAttribute">member</Property>
   </UserStoreManager>
 
 </Realm>
</UserManager>

Localtab

title	Active Directory User Store

Active directory user store sample:

Code Block

language	html/xml

<UserManager>
  <Realm>
   <Configuration>
      <AdminRole>admin</AdminRole>
      <AdminUser>
         <UserName>admin</UserName>
         <Password>XXXXXX</Password>
      </AdminUser>
      <EveryOneRoleName>everyone</EveryOneRoleName>
      <!-- By default users in this role sees the registry root -->
      <Property name="dataSource">jdbc/WSO2CarbonDB</Property>
      <Property name="MultiTenantRealmConfigBuilder">org.wso2.carbon.user.core.config.multitenancy.SimpleRealmConfigBuilder</Property>
   </Configuration>
 
    <!-- Active directory configuration follows -->
    <UserStoreManager class="org.wso2.carbon.user.core.ldap.ActiveDirectoryUserStoreManager">
            <Property name="TenantManager">org.wso2.carbon.user.core.tenant.CommonHybridLDAPTenantManager</Property>
            <Property name="defaultRealmName">WSO2.ORG</Property>
            <Property name="Disabled">false</Property>                                   
            <Property name="kdcEnabled">false</Property>
            <Property name="ConnectionURL">ldaps://10.100.1.100:636</Property> 
            <Property name="ConnectionName">CN=admin,CN=Users,DC=WSO2,DC=Com</Property>
            <Property name="ConnectionPassword">A1b2c3d4</Property>
	    	<Property name="passwordHashMethod">PLAIN_TEXT</Property>
            <Property name="UserSearchBase">CN=Users,DC=WSO2,DC=Com</Property>
            <Property name="UserEntryObjectClass">user</Property>
            <Property name="UserNameAttribute">cn</Property>
            <Property name="isADLDSRole">false</Property>
	    	<Property name="userAccountControl">512</Property>
            <Property name="UserNameListFilter">(objectClass=user)</Property>
	    	<Property name="UserNameSearchFilter">(&amp;(objectClass=user)(cn=?))</Property>
            <Property name="UsernameJavaRegEx">[a-zA-Z0-9._-|//]{3,30}$</Property>
            <Property name="UsernameJavaScriptRegEx">^[\S]{3,30}$</Property>
            <Property name="PasswordJavaScriptRegEx">^[\S]{5,30}$</Property>
	    	<Property name="RolenameJavaScriptRegEx">^[\S]{3,30}$</Property>
            <Property name="RolenameJavaRegEx">[a-zA-Z0-9._-|//]{3,30}$</Property>
	    	<Property name="ReadGroups">true</Property>
	    	<Property name="WriteGroups">false</Property>
	    	<Property name="EmptyRolesAllowed">true</Property>
            <Property name="GroupSearchBase">CN=Users,DC=WSO2,DC=Com</Property>
	    	<Property name="GroupEntryObjectClass">group</Property>
            <Property name="GroupNameAttribute">cn</Property>
            <Property name="SharedGroupNameAttribute">cn</Property>
            <Property name="SharedGroupSearchBase">ou=SharedGroups,dc=wso2,dc=org</Property>
            <Property name="SharedGroupEntryObjectClass">groups</Property>
            <Property name="SharedTenantNameListFilter">(object=organizationalUnit)</Property>
            <Property name="SharedTenantNameAttribute">ou</Property>
            <Property name="SharedTenantObjectClass">organizationalUnit</Property>
            <Property name="MembershipAttribute">member</Property>
            <Property name="GroupNameListFilter">(objectcategory=group)</Property>
	    	<Property name="GroupNameSearchFilter">(&amp;(objectClass=group)(cn=?))</Property>
            <Property name="UserRolesCacheEnabled">true</Property>
            <Property name="Referral">follow</Property>
	    	<Property name="BackLinksEnabled">true</Property>
            <Property name="MaxRoleNameListLength">100</Property>
            <Property name="MaxUserNameListLength">100</Property>
            <Property name="SCIMEnabled">false</Property>
	</UserStoreManager>
 
  </Realm>
</UserManager>

The following tags in your file indicate whether it is an Active Directory or LDAP:

Active Directory: <UserStoreManager class="org.wso2.carbon.user.core.ldap.ActiveDirectoryUserStoreManager">
LDAP: <UserStoreManager class="org.wso2.carbon.user.core.ldap.ReadOnlyLDAPUserStoreManager">

Info
If you create the `user-mgt.xml` file yourself, be sure to save it in the `<PRODUCT_HOME>/repository/conf` directory.

Find a valid user that resides in the directory server. For example, if the valid username is AdminSOA, update the Admin user section of your LDAP configuration as follows. You do not have to update the password element; leave it as is.

Code Block

language	html/xml

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

Note the following regarding the configuration above:

Element Description

<AdminRole>wso2admin</AdminRole> This is the role that has all administrative privileges of the WSO2 product, so all users having this role are admins of the product. You can provide any meaningful name for this role. This role is created in the internal H2 database when the product starts.

<AdminUser>

Configure the default administrator for the WSO2 product. If the external user store is read-only, you must select a user already existing in the external user store and add it as the admin user within the <AdminUser> element. If the external user store is in read/write mode, even if the user you specify within the <AdminUser> element does not exist in the external user store, it will be automatically created.

Note

If you are connecting WSO2 BAM with an external LDAP user store, be sure to change the <BAM_HOME>/repository/conf/etc/cassandra-auth.xml file with the credentials you give in the <AdminUser> element of the user-mgt.xml file. If not, you get an error when trying to access Cassandra Keyspaces using the BAM management console. For example, if we use AdminSOA as the admin user, the cassandra-auth.xml file must be changed as follows:

Code Block

language	html/xml

<Cassandra>
    <!--  local transport -->
    <EPR>local://services/CassandraSharedKeyPublisher</EPR>
    <!-- HTTP transport -->
    <!--  <EPR>https://localhost:9443/services/CassandraSharedKeyPublisher</EPR> -->
    <User>AdminSOA</User>
    <Password>xxxxx</Password>
</Cassandra>

<UserName> Username of the default administrator. This user MUST exist in the external LDAP. If the user store is read-only, the admin user must exist in the user store for the process to work.

<Password> Do NOT put the password here. Just leave it empty or place some stars (*) there. If the user store is read-only, this element and its value are ignored.

Update the connection details to suit your Directory Server. For example:
Code Block
language html/xml
<Property name="ConnectionURL">ldap://localhost:10389</Property>
Obtain a user who has permission to read all users/attributes and perform searches on the Directory Server from your LDAP administrator. For example, if the privileged user is "AdminLDAP" and the password is "2010#Avrudu", update the following sections of the realm configuration as follows:
Code Block
language html/xml
<Property name="ConnectionName">uid=AdminLDAP,ou=system</Property> <Property name="ConnectionPassword">2010#Avrudu</Property>
Update <Property name="UserSearchBase"> by providing the directory name where the users are stored. When LDAP searches for users, it will start from this location of the directory.
Code Block
language html/xml
<Property name="UserSearchBase">ou=system</Property>
Set the attribute 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, check with your LDAP administrator.
Code Block
language html/xml
<Property name="UserNameAttribute">uid</Property>
For Active Directory this will differ as follows:
Code Block
language html/xml
<Property name="UserNameAttribute">sAMAccountName</Property>
Info
Ideally, <Property name="UserNameAttribute"> and <Property name="UserNameSearchFilter"> should refer to the same attribute.

Optionally, configure the realm to read roles from the Directory Server by reading the user/role mapping based on a membership (user list) or backlink attribute, as follows:

The following code snippet represents reading roles based on a membership attribute. This is used by the ApacheDirectory server and OpenLDAP.

Code Block

language	html/xml

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

The following code snippet represents reading roles based on a backlink attribute. This is used by the Active Directory.

Code Block

language	html/xml

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

Start your server and try to log in as "AdminSOA". The password is the AdminSOA's password in the LDAP server.

Read/write mode

If you want to connect to an external LDAP user store, such that only the user entries are written to the external LDAP and roles are not written to the external LDAP, the only difference from the steps in section 2Configuring Primary User Stores (Carbon 4.2.0 v2)Read-only mode is the following:

Code Block

language	html/xml

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

...

Enable the <ReadWriteLDAPUserStoreManager> element in the user-mgt.xml file by uncommenting the code. When it is enabled, the user manager reads/writes into the LDAP user store.

The default configuration for the external read/write LDAP user store in the user-mgt.xml file is as follows. Change the values according to your requirements.

Localtabgroup

Localtab

active	true
title	LDAP User Store

LDAP user store sample:

Code Block

language	html/xml

<UserStoreManager class="org.wso2.carbon.user.core.ldap.ReadWriteLDAPUserStoreManager">
   <Property name="TenantManager">org.wso2.carbon.user.core.tenant.CommonHybridLDAPTenantManager</Property>
   <Property name="ConnectionURL">ldap://localhost:${Ports.EmbeddedLDAP.LDAPServerPort}</Property>
   <Property name="ConnectionName">uid=admin,ou=system</Property>
   <Property name="ConnectionPassword">admin</Property>
   <Property name="passwordHashMethod">SHA</Property>
   <Property name="UserNameListFilter">(objectClass=person)</Property>
   <Property name="UserEntryObjectClass">wso2Person</Property>
   <Property name="UserSearchBase">ou=Users,dc=wso2,dc=org</Property>
   <Property name="UserNameSearchFilter">(&amp;(objectClass=person)(uid=?))</Property>
   <Property name="UserNameAttribute">uid</Property>
   <Property name="PasswordJavaScriptRegEx">[\\S]{5,30}</Property>
   <Property name="UsernameJavaScriptRegEx">[\\S]{3,30}</Property>
   <Property name="UsernameJavaRegEx">^[^~!@#$;%^*+={}\\|\\\\&lt;&gt;,\'\"]{3,30}$</Property>
   <Property name="RolenameJavaScriptRegEx">[\\S]{3,30}</Property>
   <Property name="RolenameJavaRegEx">^[^~!@#$;%^*+={}\\|\\\\&lt;&gt;,\'\"]{3,30}$</Property>
   <Property name="ReadLDAPGroups">true</Property>
   <Property name="WriteLDAPGroups">true</Property>
   <Property name="EmptyRolesAllowed">true</Property>
   <Property name="GroupSearchBase">ou=Groups,dc=wso2,dc=org</Property>
   <Property name="GroupNameListFilter">(objectClass=groupOfNames)</Property>
   <Property name="GroupEntryObjectClass">groupOfNames</Property>
   <Property name="GroupNameSearchFilter">(&amp;(objectClass=groupOfNames)(cn=?))</Property>
   <Property name="GroupNameAttribute">cn</Property>
   <Property name="MembershipAttribute">member</Property>
   <Property name="UserRolesCacheEnabled">true</Property>
   <Property name="UserDNPattern">uid={0},ou=Users,dc=wso2,dc=org</Property>
</UserStoreManager>

Localtab

title	Active Directory User Store

Active directory user store sample:

Code Block

language	html/xml

<UserStoreManager class="org.wso2.carbon.user.core.ldap.ActiveDirectoryUserStoreManager">
            <Property name="TenantManager">org.wso2.carbon.user.core.tenant.CommonHybridLDAPTenantManager</Property>
            <Property name="defaultRealmName">WSO2.ORG</Property>
            <Property name="Disabled">false</Property>                                   
            <Property name="kdcEnabled">false</Property>
            <Property name="ConnectionURL">ldaps://10.100.1.100:636</Property> 
            <Property name="ConnectionName">CN=admin,CN=Users,DC=WSO2,DC=Com</Property>
            <Property name="ConnectionPassword">A1b2c3d4</Property>
	    	<Property name="passwordHashMethod">PLAIN_TEXT</Property>
            <Property name="UserSearchBase">CN=Users,DC=WSO2,DC=Com</Property>
            <Property name="UserEntryObjectClass">user</Property>
            <Property name="UserNameAttribute">cn</Property>
            <Property name="isADLDSRole">false</Property>
	    	<Property name="userAccountControl">512</Property>
            <Property name="UserNameListFilter">(objectClass=user)</Property>
	    	<Property name="UserNameSearchFilter">(&amp;(objectClass=user)(cn=?))</Property>
            <Property name="UsernameJavaRegEx">[a-zA-Z0-9._-|//]{3,30}$</Property>
            <Property name="UsernameJavaScriptRegEx">^[\S]{3,30}$</Property>
            <Property name="PasswordJavaScriptRegEx">^[\S]{5,30}$</Property>
	    	<Property name="RolenameJavaScriptRegEx">^[\S]{3,30}$</Property>
            <Property name="RolenameJavaRegEx">[a-zA-Z0-9._-|//]{3,30}$</Property>
	    	<Property name="ReadGroups">true</Property>
	    	<Property name="WriteGroups">true</Property>
	    	<Property name="EmptyRolesAllowed">true</Property>
            <Property name="GroupSearchBase">CN=Users,DC=WSO2,DC=Com</Property>
	    	<Property name="GroupEntryObjectClass">group</Property>
            <Property name="GroupNameAttribute">cn</Property>
            <Property name="SharedGroupNameAttribute">cn</Property>
            <Property name="SharedGroupSearchBase">ou=SharedGroups,dc=wso2,dc=org</Property>
            <Property name="SharedGroupEntryObjectClass">groups</Property>
            <Property name="SharedTenantNameListFilter">(object=organizationalUnit)</Property>
            <Property name="SharedTenantNameAttribute">ou</Property>
            <Property name="SharedTenantObjectClass">organizationalUnit</Property>
            <Property name="MembershipAttribute">member</Property>
            <Property name="GroupNameListFilter">(objectcategory=group)</Property>
	    	<Property name="GroupNameSearchFilter">(&amp;(objectClass=group)(cn=?))</Property>
            <Property name="UserRolesCacheEnabled">true</Property>
            <Property name="Referral">follow</Property>
	    	<Property name="BackLinksEnabled">true</Property>
            <Property name="MaxRoleNameListLength">100</Property>
            <Property name="MaxUserNameListLength">100</Property>
            <Property name="SCIMEnabled">false</Property>
</UserStoreManager>

Info
For active directory configurations, the `WriteGroups` property is set to true for read/write mode and false for read-only mode.

Anchor

	JDBC
	JDBC

Configuring an internal/external JDBC user store

The default internal JDBC user store reads/writes into the internal database of the Carbon server. JDBC user stores can be configured using the <PRODUCT_HOME>/repository/conf/user-mgt.xml file's JDBCUserStoreManager configuration section. In addition to this, all Carbon-based products can work with external RDBMSs. You can configure Carbon to read users/roles from your company RDBMS and even write to it. Therefore, in this scenario, the user core connects to two databases:

...

Versions Compared

Old Version 2

New Version 3

Key

Configuring an external LDAP user store/active directory

Read-only mode

Read/write mode

Configuring an internal/external JDBC user store