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.
- Default internal user store is embedded-apacheds ldap.
- Ability to operate in readonly mode on your company's LDAP
and
Active Directory userstores.
- Ability to operate in read-write mode on internal and external user stores.
- Supports any custom realm
- Roles can contain users from external user stores
- Improved configurability for external user stores
- Capability to read/write roles from/to 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
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">(&(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">(&(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
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
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)
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.
- 1. Read Only mode
- 2. Read/Write users and Read only groups
- 3. Read/Write both users and groups
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.
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 available
here.
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>
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.
