Versions Compared

Old Version 32

changes.mady.by.user Former user

Saved on

compared with

New Version Current

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: https://wso2.org/jira/browse/DOCUMENTATION-4431
Excerpt
hiddentrue

Note to writers- The following should be copied to the product pages before pulling the page content:

"User management functionality is provided by default in all WSO2 Carbon-based products and is configured in the user-mgt.xml file found in the <PRODUCT_HOME>/repository/conf/ directory.

...

This documentation explains

...

how to set up

...

a repository for storing authorization information (role-based permissions) and how to change the relevant configurations."

The complete functionality and contents of the User Management module is called a user realm. The realm includes the user management classes, configurations and repositories that store information. Therefore, configuring the User Management functionality in a WSO2 product involves setting up the relevant repositories and updating the relevant configuration files.

...

See the following topics for more details:

Configuring the system administrator

...

Note the following regarding the configuration above.

ElementDescription
<AddAdmin>When true, this element creates the admin user based on the AdminUser element. It also indicates whether to create the specified admin user if it doesn't already exist. When connecting to an external read-only LDAP or Active Directory user store, this property needs to be false if an admin user and admin role exist within the user store. If the admin user and admin role do not exist in the user store, this value should be true, so that the role is added to the user management database. However, if the admin user is not there in the user store, we must add that user to the user store manually. If the AddAdmin value is set to true in this case, it will generate an exception.
<AdminRole>wso2admin</AdminRole>This is the role that has all administrative privileges of the WSO2 product, so all users having this role are admins of the product. You can provide any meaningful name for this role. This role is created in the internal H2 database when the product starts. This role has permission to carry out any actions related to the Management Console. If the user store is read-only, this role is added to the system as a special internal role where users are from an external user store.
<AdminUser>

Configures the default administrator for the WSO2 product. If the user store is read-only, the admin user must exist in the user store or the system will not start. If the external user store is read-only, you must select a user already existing in the external user store and add it as the admin user that is defined in the <AdminUser> element. If the external user store is in read/write mode, and you set <AddAdmin> to true, the user you specify will be automatically created.

<UserName>This is the username of the default administrator or super tenant of the user store. If the user store is read-only, the admin user MUST exist in the user store for the process to work.
<Password>
Do NOT put the password here but leave the default value.

If the user store is read-only, this element and its value are ignored after the server starts for the first time. Therefore we can reset this password back to the original value/variable after server starts for the first time. This password is used only if the user store is read-write and the AddAdmin value is set to true.

Note

Note that the password in the user-mgt.xml file is written to the primary user store when the server starts for the first time. Thereafter, the password will be validated from the primary user store and not from the user-mgt.xml file. Therefore, if you need to change the admin password stored in the user store, you cannot simply change the value in the user-mgt.xml file. To change the admin password, you must use the Change Password option from the management console.

<EveryOneRoleName>The name of the "everyone" role. All users in the system belong to this role.

Configuring the authorization manager

...

Follow the steps given below to set up and configure the Authorization Manager.

Anchor
#Step 1 Setting up the repo
#Step 1 Setting up the repo
Step 1: Setting up the repository

By default, the embedded H2 database is used for storing permissions. You can change this as follows:

  1. Change the default H2 database or set up another RDBMS for storing permissions. See the documentation on setting up databases for instructions. 
  2. When you set up an RDBMS for your system, it is necessary to create a corresponding datasource, which allows the system to connect to the database. 
    • If you are replacing the default H2 database with a new RDBMS, update the master-datasource.xml file (stored in the <PRODUCT_HOME>/repository/conf/datasources/ directory) with the relevant information. 
    • Alternatively, create a new XML file with the datasource information of your new RDBMS and store it in the same <PRODUCT_HOME>/repository/conf/datasources/ directory.
    See the documentation on managing datasources for

Refer the related topics for detailed information on setting up databases and configuring datasources.

Step 2: Updating the user realm configurations 

Once you have set up a new RDBMS and configured the datasource, the user-mgt.xml file (user realm configuration) should be updated as explained below.

  1. Set up the database connection by update the datasource information using the <Property> element under <Configuration>. The jndi name of the datasource should be used to refer to the datasource. In the following example, the jndi name of the default datasource defined in the <PRODUCT_HOME>/repository/conf/datasources/master-datasources.xml file is linked from the user-mgt.xml file.

    Code Block
    languagehtml/xml
    linenumberstrue
    <Realm>
  <Configuration>
   ..........
   <Property name="dataSource">jdbc/WSO2CarbonDB</Property>
  </Configuration>
...
</Realm>

    You can add more configurations using the <Property> element:

    Property Name

    Description

    		Mandatory/Optional
    testOnBorrow

    It is recommended to set this property to 'true' so that object connections will be validated before being borrowed from the JDBC pool. For this property to be effective, the validationQuery parameter in the <PRODUCT_HOME>/repository/conf/datasources/master-datasources.xml file should be a non-string value. This setting will avoid connection failures. See the section on performance tuning of WSO2 products for more information.

    		Optional

  2. The default Authorization Manager section in the user-mgt.xml file is shown below. This can be updated accordingly.

    Code Block
    <AuthorizationManager class="org.wso2.carbon.user.core.authorization.JDBCAuthorizationManager">
        <Property name="AdminRoleManagementPermissions">/permission</Property>
	    <Property name="AuthorizationCacheEnabled">true</Property>
</AuthorizationManager>
    • The org.wso2.carbon.user.core.authorization.JDBCAuthorizationManager class enables the Authorization Manager for your product.
    • The AdminRoleManagementPermissions property sets the registry path where the authorization information (role-based permissions) are stored. Note that this links to the repository that you defined in Step 1.

    • It is recommended to enable the GetAllRolesOfUserEnabled property in the AuthorizationManager as follows:

      Code Block
      <Property name="GetAllRolesOfUserEnabled">true</Property>

      Although using the user store manager does not depend on this property, you must consider enabling this if there are any performance issues in your production environment. Enabling this property affects the performance when the user logs in. This depends on the users, roles and permission stats.

    • By default, the rules linked to a permission (role name, action, resource) are not case sensitive. If you want to make them case sensitive, enable the following property:

      Code Block
      <Property name="CaseSensitiveAuthorizationRules">true</Property>
Excerpt
hiddentrue

NOTE to WRITERS: The 'Related topics' heading is bookmarked in this page. Add the relevant links in your respective spaces under related topics. See example:

  • Setting up Databases: This topic provides the instructions for setting up a new RDBMS for you system