User Core Admin Guide

[Download] | [Documentation Home] | [Release Note]

User Core Admin Guide

This document has the following sections.

1. Overview

User kernal of Carbon has the following new features.

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

<ReadOnly>false</ReadOnly>

<MaxUserNameListLength>500</MaxUserNameListLength>

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

<ReadOnly> Indicates whether the user store of this realm operates in the user read only mode or not

<MaxUserNameListLength> Maximum nuber of users retrieved at once by user realm



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 JDBC User Store Configuration

The default configuration is the internal JDBC user store. It read/write into the default database of the carbon server.



<UserManager>

<Realm>

.........................

<UserStoreManager

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

<Property name="..."> ... Reading SQLs ... </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="..."> ... Writing SQLs ... </Property>

<Property name="IsEmailUserName">false</Property>

</UserStoreManager>

<AuthorizationManager

class="org.wso2.carbon.user.core.authorization.JDBCAuthorizationManager">

</AuthorizationManager>

</Realm>

</UserManager>



Above configuration can be descrived as follows.



Property Name

Description

PasswordDigest Digesting method of the password

StoreSaltedPassword Indicates whether to salt the password

UserNameUniqueAcrossTenants An attribute used in for multitenancy.

driverName Driver name. The driver must be added to the classpath

PasswordJavaRegEx Maximum number of active connections in the pool

PasswordJavaScriptRegEx Max wait time of the connection

*SQL

SQLs used to write/read



4. 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 droping 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 relavent script in ${carbon-home}/dbscript/



Step 4 : Start the server as follows

sh wso2server.sh -Dsetup

5. How to Configure an External LDAP User Store / Active Directory User Store



All WSO2 Carbon based products can read users and roles from external LDAP/ActiveDirectory user stores. You can configure Carbon products to read users/roles from your company LDAP. It does not write any data into the LDAP. From now on this document will use the word LDAP to refer to both LDAP and ActiveDirectory servers.



Step 1 : Backup the ${carbon-home}/repository/conf/user-mgt.xml. A sample file for LDAP user store is available here. A sample file for Active Directory is available here. Download the relavent file and save it as ${carbon-home}/repository/conf/user-mgt.xml.Please observer 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 : This is a read only user store, so make sure the the value of the <ReadOnly> element is set to be true as follows.

<ReadOnly>true</ReadOnly>



Step 4 : Update the connection details to suit 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 priviledged 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 5 : Update the <Property name="UserSearchBase"> by giving the directory where the users are store. LDAP searches for users will start from this location.

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



Step 6 : 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 please ask your LDAP administrator.

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



For Active Directory this is different.

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



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



8.1 Reading roles based on a membership attribute. This is used by the ApacheDirectory server and OpenLDAP.

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




8.2 Reading roles based on a backlink attribute. This is used by the Active Directory.



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




The following table cotains detail descriptions of each property.



Property Name

Description

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. Please note 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 that should be considered as the username.

ReadLDAPGroups Indicates whether to read groups from the LDAP. If this is off then none of the following attributes needs to be set.

GroupSearchBase Search base for groups.

GroupSearchFilter The LDAP query that should be used to search for groups

GroupNameAttribute The attribute to be treated as the group name

MembershipAttribute Attribute that contains users

MemberOfAttribute The backlink attribute



Table 4.1



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.

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 : Edit the SQLs as you desire and start the server.