User Core Admin Guide

This document has the following sections.

1. Overview

User kernal of Carbon has the following new features.
  • The concept of single user store. The user store can be either external or internal.
  • Default internal user store is embedded-apacheds ldap.
  • Ability to operate in readonly mode on your company's LDAP and Active Directory userstores.
  • Ability to operate in read-write mode on internal and external user stores.
  • Supports any custom realm
  • Roles can contain users from external user stores
  • Improved configurability for external user stores
  • Capability to read/write roles from/to LDAP/Active Direcotry user stores
  • Implements management permission of the carbon console
The user core is driven by the user-mgt.xml found in the following location.
${carbon-home}/repository/conf/user-mgt.xml

2. Realm Configuration


The user-mgt.xml main configuration section indicates the following information.

<Configuration>
<AdminRole>admin</AdminRole>
<AdminUser>
<UserName>admin</UserName>
<Password>admin</Password>
</AdminUser>
<EveryOneRoleName>everyone</EveryOneRoleName> <!-- By default users in thsi role sees the registry root -->
<Property name="url">jdbc:h2:repository/database/WSO2CARBON_DB</Property>
<Property name="userName">wso2carbon</Property>
<Property name="password">wso2carbon</Property>
<Property name="driverName">org.h2.Driver</Property>
<Property name="maxActive">50</Property>
<Property name="maxWait">60000</Property>
<Property name="minIdle">5</Property>
</Configuration>

The main elemenents of the Realm Configuration can be explained as follows.

Element Name
Description
<AdminRole> Admin's role name. This role has permission to carry out any action related to Management Console. If the user store is read only then the this role is added to the system as a special internal role, where users are from the external user store.
<AdminUser>\ <UserName> Admin user's username. If the user store is read only then the admin user must be present. Otherwise the system won't startup.
<AdminUser> \ <Password> Admin user's password. If the user store is read only then the admin is ignored.
<EveryOneRoleName> Everyone role name. All the users in the system will belong to this role.

Table 2.1

The main properties of the user Realm Configuration can be explained as follows. It mainly contains details for the database connection.

Property Name
Description
url URL of the dartabase
userName User name of the database
password Password of the database
driverName Driver name. The driver must be added to the classpath
maxActive Maximum number of active connections in the pool
maxWait Max wait time of the connection
minIdle Min idle time of the connection

Table 2.2

3. Default LDAP User Store Configuration

Following is the default configuration for the internal LDAP user store which is embedded ApacheDS LDAP. If ApacheDSUserStoreManager is enabled in user-mgt.xml with following configuration, user manager reads/writes into the default LDAP user store of carbon.

<UserStoreManager class="org.wso2.carbon.user.core.ldap.ApacheDSUserStoreManager">
<Property name="ReadOnly">false</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="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>
</UserStoreManager>

Above configuration can be descrived as follows.

Property Name
Description
ReadOnly Indicates whether the user store of this realm operates in the user read only mode or not
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.
ConnectionPassword Password of the admin user.
passwordHashMethod Password Hash method when storing user entries in LDAP.
UserNameListFilter Filtering criteria for listing all the user entries in LDAP.
UserEntryObjectClass Object 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'
UserSearchBase DN of the context under which user entries are stored in LDAP.
UserNameSearchFilter Filtering criteria for searching a particular user entry.
UserNameAttribute Attribute 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.
ReadLDAPGroups Specifies whether groups should be read from LDAP.
WriteLDAPGroups Specifies whether groups should be written to LDAP.
EmptyRolesAllowed Specifies 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.
GroupSearchBase DN of the context under which user entries are stored in LDAP.
GroupNameListFilter Filtering criteria for listing all the group entries in LDAP.
GroupEntryObjectClass Object Class used to construct user entries.
GroupNameSearchFilter Filtering criteria for searching a particular group entry.
GroupNameAttribute Attribute used for uniquely identifying a user entry.
MembershipAttribute Attribute used to define members of LDAP groups.

Table 3.1

4. Internal JDBC User Store Configuration

Following is the configuration for the internal JDBC user store. It reads/writes into the default database of the carbon server if JDBCUserStoreManager is enabled in the user-mgt.xml.

<UserManager>
<Realm>
.........................
<UserStoreManager
class="org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager">
<Property name="ReadOnly">false</Property>
<Property name="MaxUserNameListLength">100</Property>
<Property name="IsEmailUserName">false</Property>
<Property name="DomainCalculation">default</Property>
<Property name="PasswordDigest">SHA-256</Property>
<Property name="StoreSaltedPassword">true</Property>
<Property name="UserNameUniqueAcrossTenants">false</Property>
<Property name="PasswordJavaRegEx">[\S]{5,30}$</Property>
<Property name="PasswordJavaScriptRegEx">[\\S]{5,30}</Property>
<Property name="UsernameJavaRegEx">^[^~!@#$;%^*+={}\\|\\\\<>]{3,30}$</Property>
<Property name="UsernameJavaScriptRegEx">[\\S]{3,30}</Property>
<Property name="RolenameJavaRegEx">^[^~!@#$;%^*+={}\\|\\\\<>]{3,30}$</Property>
<Property name="RolenameJavaScriptRegEx">[\\S]{3,30}</Property>
</UserStoreManager>
<AuthorizationManager
class="org.wso2.carbon.user.core.authorization.JDBCAuthorizationManager">
</AuthorizationManager>
</Realm>
</UserManager>

Above configuration can be described as follows.

Property Name
Description
ReadOnly Indicates whether the user store of this realm operates in the user read only mode or not
MaxUserNameListLength Maximum number of users retrieved at once by user realm
IsEmailUserName Indicates whether Email is used as user name (apply when realm operates in read only mode)
DomainCalculation Can be either default or custom (apply when realm operates in read only mode)
PasswordDigest Digesting method of the password
StoreSaltedPassword Indicates whether to salt the password
UserNameUniqueAcrossTenants An attribute used in for multitenancy.
PasswordJavaRegEx Policy defines password format
PasswordJavaScriptRegEx Policy defines password format
UsernameJavaRegEx Policy defines user name format
UsernameJavaScriptRegEx Policy defines user name format
RolenameJavaRegEx Policy defines role name format
RolenameJavaScriptRegEx Policy defines role name format

Table 4.1

5. How to Change the RDBMS

The default database of user manager is the H2 database shipped by the WSO2 Carbon based products. You can configure it to point to databases by different vendors.

Step 1 : Add the JDBC driver to the classpath by dropping the jar into ${carbon-home}/ repository/components/lib

Step 2 : Change values of properties given in Table 2.2 appropriately.

Step 3 : Create the database by running the relevant script in ${carbon-home}/ dbscript/ and Start the server as sh wso2server.sh (wso2server.bat)
Or Start the server as sh wso2server.sh -Dsetup (wso2server.bat -Dsetup)

6. How to Configure 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.
  • 1. Read Only mode
  • 2. Read/Write users and Read only groups
  • 3. Read/Write both users and groups

6.1. Read Only mode

Following steps describe how to configure an external LDAP in read only mode.

Step 1 : Backup the${carbon-home}/repository/conf/user-mgt.xml. A sample file for LDAP user store is available here. Download the relevant file and save it as${carbon-home}/repository/conf/user-mgt.xml.Please observe the following in your file.

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

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 - just leave it as it is.

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


Step 3 : If you wish to connect the user store in read only mode, make sure the value of the<ReadOnly> element is set to be true as follows.

<ReadOnly>true</ReadOnly>

Step 4 : Update the connection details to suite your Directory Server.
<Property name="ConnectionURL">ldap://localhost:10389</Property>

Step 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". Now 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>

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

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

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

Step 9 : The realm can read roles from the Directory Server. It can read user/role mapping based on membership attribute 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>


The table 3.1 contains detail descriptions of each of the above mentioned properties.

6.2. 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 6.1 is:

In step 3: set the ReadOnly property to false.

6.3. 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 section 6.1 above:

Step 1: Use the sample user-mgt.xml configuration file for LDAP user store that is available here

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

7. How to 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 6.1 above.

Step 1: A sample user-mgt.xml configuration file for Active Directory is availablehere.

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>


6. How to 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.
  • So the user-mgt.xml MUST contain details for two database connections. The connection details mentioned in 2.2 is used by the Authorization manager. If we specifiy 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 can be given below.

Step 1 : Backup the${carbon-home}/repository/conf/user-mgt.xml. A sample file for JDBC user store is available here. Download the relavent file and save it as${carbon-home}/repository/conf/user-mgt.xml. Please observe the following in your file.

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


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

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


Step 3 : Add the JDBC driver to the classpath by droping the jar into ${carbon-home}/ repository/components/lib

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

Step 5 : Start the server.