h1. Overview {anchor:id=KSref.RolesPluginConfiguration.Overview}

The roles plug-in component defines roles in Forum of eXo Platform 3. This convenient application defines access to a set of functions within the application.
Currently, it only defines the person who has the _administrator_ role. Administrators can get access to administration functions.
At runtime, the application gets data from the roles plug-in to decide whether the logged user has the administrative role or not.

h1. Configuration {anchor:id=KSref.RolesPluginConfiguration.Configuration}
The plug-in is configured in the _roles-configuration.xml_ file.

When the user signs in, his or her username, group and membership will be compared with the user roles defined in the _.xml_ file that is provided by the roles plug-in component.

In particular, at runtime of ForumService, the roles plug-in component is called. The role plug-in is configured in the _roles-configuration.xml_ file. The plug-in component named _add.role.rules.plugin_ will be referred to _org.exoplatform.ks.common.conf.RoleRulesPlugin_ to create users for Forum corresponding to users who exist in the organization database. In addition, the list of users who have _administration_ roles are also defined.

{code:xml}
<component-plugin>
  <name>add.role.rules.plugin</name>
  <set-method>addRolePlugin</set-method>
  <type>org.exoplatform.ks.common.conf.RoleRulesPlugin</type>
  <description>add role rules</description>
  <init-params>
    <value-param>
      <name>role</name>
      <description>name of the role</description>
      <value>ADMIN</value>
    </value-param>
    <values-param>
      <name>rules</name>
      <description>rules of the role</description>
      <value>root</value>
      <!--value>admin</value -->
      <!--value>member:/demo</value-->
      <!--value>/forums/admin</value-->
      <!--value>*:/forum/admin</value-->
      <!--value>/platform/administrators</value-->
      <!--value>manager:/platform/users</value-->
      <!--value>*:/somegroup/somesubgroup</value-->
      <!--value>manager:/somegroup/someothergroup</value-->
    </values-param>
  </init-params>
</component-plugin>
{code}

In which:

|| Name || Set-method || Type || Description ||
| *add.role.rules.plugin* | addRolePlugin | org.exoplatform.ks. common.conf. RoleRulesPlugin | Add role rules. |

* Init-params:

|| Name || Possible value || Default value || Description |
| *role* | {{string}} | {{ADMIN}} | The name of role. |
| *rules* | {{string}} | {{root}} | The rules of role. |

* When the _role-configuration.xml_ file is executed, the administration role (with {{ADMIN}} value) will be checked and assigned to a matrix of _users/groups/memberships_ defined inside the "value" tags as below:

{code:xml}
<value>...</value>
{code}
 
For example:

{code:xml}
...
<value>root</value>
<value>john</value> 
<value>/platform/administrators</value> 
<value>member:/VIP</value>
<value>validator:/VIP</value>
...
{code}

In the example above, the default administrators of Forum include _root_, _john_, users in _/platform/administrators_ group and users who have _member/validator_ memberships in the VIP group. 

When being _root_, the users who belong to the _/platform/administrators_ group or who have _member/validator_ memberships in the VIP group and sign in the Forum, they will be identified as the default administrator of Forum. 

To add or remove the default administrator of the Forum, simply edit the _roles-configuration.xml_ file, add or remove the relevant "value" tags.

{code:xml}
...             
<values-param>
  ...
  <value>...</value>
  ...
</values-param>
...
{code}

The default administrators of the Forum can only change their roles by editing in the _roles-configuration.xml_ file.

At runtime, modifications in the _roles-configuration.xml_ file will be read and database will be updated. Normal users of the Forum and default administration will be created correspondingly.
