User Core Admin Guide

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

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

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.

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.