Versions Compared

Old Version 5

changes.mady.by.user Former user

Saved on

compared with

New Version 6

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The WSO2 User Manager authenticates users from different types of user stores and currently has the capability to easily plug-in to to LDAP, Active Directory and  and JDBC to  to perform authentication.

...

All WSO2 Carbon based products can read and write users and roles from external LDAP All WSO2 Carbon based products can read and write users and roles from external LDAP user stores. You can configure Carbon products to access LDAP in or JDBC using one of the following modes.

Read-Only

...

Mode 
Anchor
Read-Only Mode
Read-Only Mode

All WSO2 Carbon based products can read users and roles from external LDAP/Active Directory user stores. 

To configure an external LDAP user store/active directory user store: 

Anchor
LDABActive
LDABActive

You can configure Carbon products to read users/roles from your company LDAP. The "Read Only" mode does not write any data into the LDAP.

Note that LDAP is used going forward to refer to both LDAP and ActiveDirectory servers.

Step 1 : Backup <carbon-home>/repository/conf/user-mgt.xml.

  • A sample file for LDAP user store is given below:
Code Block
languagehtml/xml
<UserManager>
 <Realm>
   <Configuration>
      <AdminRole>admin</AdminRole>
      <AdminUser>
         <UserName>admin</UserName>
         <Password>XXXXXX</Password>
      </AdminUser>
      <EveryOneRoleName>everyone</EveryOneRoleName>
      <!-- By default users in thsi 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>

  

  • A sample file for Active Directory is given below:
Code Block
languagehtml/xml
<UserManager>
  <Realm>
   <Configuration>
      <AdminRole>admin</AdminRole>
      <AdminUser>
         <UserName>admin</UserName>
         <Password>XXXXXX</Password>
      </AdminUser>
      <EveryOneRoleName>everyone</EveryOneRoleName>
      <!-- By default users in thsi 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="ConnectionURL">ldap://10.100.1.211:389</Property>
       <Property name="ConnectionName">cn=Administrator,cn=users,dc=wso2,dc=lk</Property>
       <Property name="ConnectionPassword">admin123</Property>
       <Property name="UserSearchBase">cn=users,dc=wso2,dc=lk</Property>
       <Property name="UserNameListFilter">(objectClass=person)</Property>
       <Property name="UserNameAttribute">sAMAccountName</Property>
       <Property name="ReadLDAPGroups">true</Property>
       <Property name="GroupSearchBase">cn=users,dc=wso2,dc=lk</Property>
       <Property name="GroupNameSearchFilter">(objectcategory=group)</Property>
       <Property name="GroupNameAttribute">cn</Property>
       <Property name="MembershipAttribute">member</Property>
    </UserStoreManager>
 
  </Realm>
</UserManager>

Copy the user-mgt-ldap.xml file and save it as <carbon-home>/repository/conf/user-mgt.xml. When you are configuring for for ActiveDirectory, do the same to to user-mgt-actdir.xml.

Note the following in your file.  

Code Block
<UserStoreManager class="org.wso2.carbon.user.core.ldap.ReadOnlyLDAPUserStoreManager">

Step 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. You don't have to update the password element; leave it as it is.

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

Step 3 : Update the connection details to suit your Directory Server.

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

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

Code Block
<Property name="ConnectionName">uid=AdminLDAP,ou=system</Property>
<Property name="ConnectionPassword">2010#Avrudu</Property>

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

Code Block
Property name="UserSearchBase">ou=system</Property>

Step 5 : Set the attribute that you wish to be used 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
<Property name="UserNameAttribute">sAMAccountName</Property>

Step 6 : This is the most basic configuration. For more advanced options like "external roles", jump to step 7. 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, contact the WSO2 carbon user group according to the contact details given under "community and support" section on the welcome page.

Step 7 : The realm can read roles from the Directory Server. It can read user/role mapping based on a backlink attribute or membership (user list) attribute.

  • Step 7.1 : Reading roles based on a membership attribute. This is used by the ApacheDirectory server and OpenLDAP.
Code Block
<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>
  • Step 7.2 : Reading roles based on a backlink attribute. This is used by the Active Directory.

...

Property Name

Description

MaxUserNameListLength 

ConnectionURL

The connection URL to the database.

ConnectionName

The user name used to connect to the database.
This user must have permissions to read the user list and user's attributes.

ConnectionPassword

Password of the connection username.

UserSearchBase

Search base of users.
Note that different databases have different search bases.

UserNameListFilter

The LDAP query that should be used to search users.

UserNameAttribute

Users can be authenticated using their email address, uid and etc.
The name of the attribute considered as the username.

ReadLDAPGroups

Indicates whether to read groups from the LDAP.
If this is set off, none of the following attributes need to be set.

GroupSearchBase

Search base for groups.

GroupNameListFilter 

GroupSearchFilter

The LDAP query used to search for groups.

GroupNameAttribute

The attribute to be treated as the group name.

MembershipAttribute

Attribute that contains users.

UserRolesCacheEnabled 
ReplaceEscapeCharactersAtUserLogin 

Read/Write

...

Mode 
Anchor
Read/Write Users and Read-Only Groups
Read/Write Users and Read-Only Groups

If you wish 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 following:

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

Anchor
LDAP
LDAP

<CARBON_HOME>/repository/conf/user-mgt.xml file has a commented out configuration for external LDAP user stores.

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

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

Code Block
languagehtml/xml
linenumberstrue
<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>

Main elements of the configuration can be explained as follows. 

Property NameDescription
ConnectionURL

Connection URL to the ldap server. In the case of default LDAP in carbon, port is mentioned in carbon.xml and a reference to that port is mentioned in the above configuration.

ConnectionName

This should be the DN (Distinguish Name) of the admin user in LDAP.

ConnectionPasswordPassword of the admin user.
passwordHashMethodPassword Hash method when storing user entries in LDAP.
UserNameListFilterFiltering criteria for listing all the user entries in LDAP.
UserEntryObjectClassObject Class used to construct user entries. In the case of default LDAP in carbon, it is a custom object class defined with the name-'wso2Person'
UserSearchBaseDN of the context under which user entries are stored in LDAP.
UserNameSearchFilterFiltering criteria for searching a particular user entry.
UserNameAttributeAttribute used for uniquely identifying a user entry. Users can be authenticated using their email address, uid and etc.

PasswordJavaScriptRegEx

Policy that defines the password format.
UsernameJavaScriptRegExThe regular expression used by the font-end components for username validation.
UsernameJavaRegExA regular expression to validate usernames. By default, strings having length 5 to 30 non-empty characters are allowed.
RolenameJavaScriptRegExThe regular expression used by the font-end components for rolename validation.
RolenameJavaRegExA regular expression to validate rolenames. By default, strings having length 5 to 30 non-empty characters are allowed.
ReadLDAPGroupsSpecifies whether groups should be read from LDAP.
WriteLDAPGroupsSpecifies whether groups should be written to LDAP.
EmptyRolesAllowedSpecifies whether underlying LDAP user store allows empty groups to be created. In the case of ldap in carbon, the schema is modified such that empty groups are allowed to be created. Usually LDAP servers do not allow to create empty groups.
GroupSearchBaseDN of the context under which user entries are stored in LDAP.
GroupNameListFilterFiltering criteria for listing all the group entries in LDAP.
GroupEntryObjectClassObject Class used to construct user entries.
GroupNameSearchFilterFiltering criteria for searching a particular group entry.
GroupNameAttributeAttribute used for uniquely identifying a user entry.
MembershipAttributeAttribute used to define members of LDAP groups.
UserRolesCacheEnabledThis is to indicate whether to cache the role list of a user. By default it is 'true'. Set it to 'falese' if user-roles are changed by external means and those changes should be instantly reflected in the carbon instance.
UserDNPatternThe patten for user's DN. It can be defined to improve the LDAP search. When there are many user entries in the LADP, defining a "UserDNPattern" provides more impact on performances as the LDAP does not have to travel through the entire tree to find users.

How to Configure an External JDBC User Store 
Anchor
JDBC
JDBC

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, the user core connected to two databases.

...

So the user-mgt.xml file must contain details for two database connections. The connection details mentioned earlier 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. Step by step guidelines for connecting to an external JDBC user store in read-only mode is given below.

Step 1 : Back-up the <carbon-home>/repository/conf/user-mgt.xml file. A sample file for JDBC user store (user-mgt-jdbc.xml) is available in <carbon-home>/repository/conf directory directory. Download the relevant file and save it as as <IS_HOME>/repository/conf/user-mgt.xml. Uncomment the following section in your file if it is commented out.

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

Step 2 : Find a valid user that resides in the RDBMS. For example, say a valid username is is AdminSOA. Update the Admin user section of your ldap configuration as follows. You don't do not have to update the password element; leave it as it is.

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

Step 3 : In the user-mgt.xml file file, add add passwordHashMethod property  property within the the JDBCUserStoreManager. For example,:

Code Block
languagehtml/xml
<UserStoreManager class="org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager">
     <Property name="passwordHashMethod">SHA</Property>
     ...
</UserStoreManager>

The passwordHashMethod property specifies  property specifies how the password should be stored, and usually has the values:

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

Step 5 : In the user-mgt.xml file file, under realm configuration, set the value of of MultiTenantRealmConfigBuilder property to  property to org.wso2.carbon.user.core.config.multitenancy.SimpleRealmConfigBuilder. For  For example,

Code Block
languagehtml/xml
<Property name="MultiTenantRealmConfigBuilder">org.wso2.carbon.user.core.config.multitenancy.SimpleRealmConfigBuilder</Property>

Step 6 : Add the JDBC driver to the classpath by dropping the jar Jar to the <carbon-home>/repository/components/lib directory directory.

Step 7 : Edit the SQLs in the user-mgt.xml file according  file according to your requirements, and start the server.

Info
iconfalse

LDAP is one of many standards supported by the WSO2 Governance Registry. Read more on Supported APIs & Standards for a complete list of standards supported by WSO2 Governance Registry.

 

 

Excerpt
hiddentrue

Information on managing external user stores in WSO2 Carbon.