Configuring the Liberty user registry

The access levels that each user receives within i2 Analyze are determined by their membership of groups. The names of these groups must match the group permissions elements values that are defined in your security schema.

In the production deployment process, you must configure the Liberty user registry when you modify the groups in the security schema in the schema development or configuration development environments.

The following rules apply:

You must create groups in the Liberty user registry whose names exactly match the UserGroup attribute of the group permissions elements in the security schema.
You must ensure that every user is a member of enough groups such that they are assigned a dimension value and level from each access security dimension. A user does not require a mapping to a grant security dimension.

To illustrate these rules, consider that the example security schema defines the following dimensions and groups:

Group Permissions `UserGroup` value	Group Permissions for Dimension	Dimension values and level
Analyst	Security Compartment	Human Informants - update, Open Source Intelligence - read_only
Clerk	Security Compartment	Open Source Intelligence - update
Controlled	Security Level	Controlled - update
Unclassified	Security Level	Controlled - update, Unclassified - update
Security Controller	Grant Access	Security Controller - update

To map to this security schema, the user group values in the table must match with the user groups in the user repository.

Each user in this deployment must be in either of the "Analyst" or "Clerk" groups, and either of the "Controlled" or "Unclassified" groups.

Every deployment must contain an account that is associated with the administrator role. You can create a group in the user registry named "Administrator", or you can change the value of the security.administrator.group property to the name of an existing group in the repository. The security.administrator.group property is in the environment-advanced.properties file for each application, in the toolkit\configuration\environment\application directory. When an i2 Analyze user is a member of this group, they can access administrative features.

The following process is an approach to security in Liberty that uses a basic user registry.

Create the users and groups in Liberty for each of the group permissions elements in the security schema.
1. In an XML editor, open the user.registry.xml file. You can find this file in the C:\i2\i2analyze\deploy\wlp\usr\shared\config directory of your Liberty installation.
2. Use the following template to add your users and groups to the user.registry.xml file as the first child of the <server> element:
```
<basicRegistry id="basic" realm="WebRealm">
    <user name="" password="" />
    <group name="">
        <member name="" />
    </group>
</basicRegistry>
```
  Use the following information to populate the template:
  - There is a <user> element for each user of the system. The <user> element's name and password attributes must be populated for that user.
  - There is a <group> element with a name attribute that matches the name of each security dimension in the security schema.
  - The <group> elements are populated by <member> elements. For a user to be a member of a group, a <member> element's name attribute must match that user's name attribute.
  If you are using the example deployment, the user Jenny is a member of each group.
  In the following example user.registry.xml, the users Analyst1, and Clerk1 have been added into a subset of the groups. If you use the following example, log in as these users to see the different permission levels of each group:
```
<basicRegistry id="basic" realm="WebRealm">
        <user name="Jenny" password="{xor}FToxMSY="/>
        <user name="Analyst1" password="{xor}FToxMSY=" />
        <user name="Clerk1" password="{xor}FToxMSY=" />
        <group name="Analyst">
            <member name="Jenny"/>
            <member name="Analyst1"/>
        </group>
        <group name="Clerk">
            <member name="Jenny"/>
            <member name="Clerk1"/>
        </group>
        <group name="Controlled">
            <member name="Jenny"/>
            <member name="Analyst1"/>
        </group>
        <group name="Unclassified">
            <member name="Jenny"/>
            <member name="Clerk1"/>
        </group>
        <group name="Security Controller">
            <member name="Jenny"/>
        </group>
        <group name="Administrator">
            <member name="Jenny"/>
        </group>
  </basicRegistry>
```

The passwords can be encoded by the Liberty security utility.

Use the Liberty securityUtility command to encode the password for each user.
1. Navigate to the bin directory of your WebSphere® Application Server Liberty profile deployment that is configured by the deployment toolkit. By default Liberty is deployed in the C:\i2\i2analyze\deploy\wlp directory.
2. In a command prompt, run the following command:
```
securityUtility encode password
```
  The encoded password is displayed in the command line. Record the encoded password, including the {xor} prefix, and use the encoded password as the password in the user.registry.xml file.
  For more information about using the security utility, see securityUtility command.
Save and close the file.

To test that your changes have worked, log in to i2 Analyze as one of the users that you added to the user registry.

After you test your changes to the user registry, you can configure user access to features. To access the REST endpoints, a user must be a member of a group that has the i2:Administrator permission under command access control. For more information, see Configuring command access control.