User Core Admin Guide
User Core Admin Guide
This document has the following sections.
User kernal of Carbon has the following new features.
- The concept of single user store. The user store can be
either
external or internal.
- Ability to operate in readonly mode on your company's LDAP
and
Active Directory userstores.
- Supports any custom realm
- Roles can contain users from external user stores
- Improved configurability for external user stores
- Capablility to read roles from 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
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
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="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 descrived 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 nuber 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 3.1
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/
and Start the server as
sh wso2server.sh (wso2server.bat)
Or Start the server as
sh wso2server.sh -Dsetup (wso2server.bat -Dsetup)
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
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 : 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 stored. 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
|
ReadOnly
|
Indicates whether
the user store
of this realm operates in the user read only mode or not
|
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
Also You can configure Carbon products to write and read users/roles
with your company LDAP. A sample file for LDAP user store is available
here The following table cotains detail descriptions of additional properties which are not
listed in Table 4.1.
Property Name
|
Description
|
passwordHashMethod
|
Digesting method of the password
|
PasswordJavaScriptRegEx
|
Policy defines password format
|
Table 4.2
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.