User Core Admin Guide
[Download]
| [Documentation Home] | [Release Note]
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 -->
<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
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
|
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
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
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.1 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 : Edit the SQLs as you desire and start the server.