XUser Management in WSO2 Carbon

User management comes bundled with the WSO2 Carbon platform and facilitates the management and control of user accounts and roles at different levels. Since it is integrated into the core Carbon platform, user management capability is available by default in all WSO2 Carbon-based products.

The user store of Carbon products can be configured to operate in either one of the following modes.

User store operates in read/write mode - In Read/Write mode, WSO2 Carbon reads/writes into the user store.
User store operates in read only mode - In Read Only mode, WSO2 Carbon guarantees that it does not modify any data in the user store. Carbon maintains roles and permissions in the Carbon database but it can read users/roles from the configured user store.

The user kernal of WSO2 Carbon has the following features:

The concept of single user store which is either external or internal.
Ability to operate in read-only/read-write mode on your company's LDAP user stores.
Ability to work with Active Directory Directory Services (AD DS) and Active Directory Lightweight Directory Services (AD LDS) in read write mode.
Supports any custom realm.
Roles can contain users from external user stores.
Improved configuration capability for external user stores.
Capability to read roles from LDAP/Active Directory user stores.
Implements management permission of the carbon console.

The user core is driven by the user-mgt.xml file found in: <PRODUCT_HOME>/repository/conf folder.

Realm Configuration

The user-mgt.xml file's main configuration section has the following information:

<Configuration>
     <AdminRole>admin</AdminRole>
     <AdminUser>
          <UserName>admin</UserName>
          <Password>admin</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>

The main elements 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 the Management Console. If the user store is read-only, then this role is added to the system as a special internal role where users are from an external user store.
<AdminUser>\<UserName>	Admin user's username. If the user store is read-only, the admin user must exist in the user store. Otherwise the system won't start.
<AdminUser>\<Password>	Admin user's password. If the user store is read-only, this element and its value are ignored.
<EveryOneRoleName>	Everyone role name. All users in the system belong to this role.

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

Property Name	Description
dataSource	Data sources are configured in the <PRODUCT_HOME>/repository/conf/datasources/master-datasources.xml file. This property indicates the relevant data source configuration for the User Management Database.
MultiTenantRealmConfigBuilder	Tenant Manager specific realm config parameter. Can be used to build different types of realms for the tenant.

Internal JDBC User Store Configuration

The internal JDBC user store reads/writes into the default database of the carbon server.

<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">^[^~!#$;%^*+={}\\|\\\\&lt;&gt;,\'\"]{3,30}$</Property>
	 <Property name="UsernameJavaScriptRegEx">[\\S]{3,30}</Property>
	 <Property name="RolenameJavaRegEx">^[^~!@#$;%^*+={}\\|\\\\&lt;&gt;,\'\"]{3,30}$</Property>
	 <Property name="RolenameJavaScriptRegEx">[\\S]{3,30}</Property>
	 <Property name="UserRolesCacheEnabled">true</Property>
</UserStoreManager>

The configuration given above 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 real.
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 algorithm of the password. Has values such as PLAIN_TEXT, SHA etc.
StoreSaltedPassword	Indicates whether to salt the password.
UserNameUniqueAcrossTenants	An attribute used for multi-tenancy.
PasswordJavaRegEx	A regular expression to validate passwords. By default, strings having length 5 to 30 non-empty characters are allowed.
PasswordJavaScriptRegEx	The regular expression used by the font-end components for password validation.
UsernameJavaRegEx	A regular expression to validate usernames. By default, strings having length 5 to 30 non-empty characters are allowed.
UsernameJavaScriptRegEx	The regular expression used by the font-end components for username validation.
RolenameJavaRegEx	A regular expression to validate rolenames. By default, strings having length 5 to 30 non-empty characters are allowed.
RolenameJavaScriptRegEx	The regular expression used by the font-end components for rolename validation.
UserRolesCacheEnabled	This 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.

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 as explained in the following steps:

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

Step 3 : Create the database by running the relevant script in <product_home>/dbscript

Step 4 : Start the serve as follows: sh wso2server.sh -Dsetup

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

The code block can be described as follows:

Property Name	Description
`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.
UsernameJavaScriptRegEx	The regular expression used by the font-end components for username validation.
UsernameJavaRegEx	A regular expression to validate usernames. By default, strings having length 5 to 30 non-empty characters are allowed.
RolenameJavaScriptRegEx	The regular expression used by the font-end components for rolename validation.
RolenameJavaRegEx	A regular expression to validate rolenames. By default, strings having length 5 to 30 non-empty characters are allowed.
`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.
UserRolesCacheEnabled	This 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.
UserDNPattern	The 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.