Providing security dimension values

If an unordered dimension in your i2 Analyze security schema has values that can change often, or if you have an existing classification system that you want to adopt without duplicating it in the schema, you can use a security dimension values provider to supply some or all of the values for a security dimension.

Before you begin

To use a security dimension values provider in a security schema file, you must create or acquire the Java class that contains it. For more information about creating a provider, see i2 Analyze Developer Essentials.

About this task

To specify that a dimension in your security schema uses values from a security dimension values provider, you add the name of the class to a <Dimension> element in the security schema file, and make the class available to the i2 Analyze application by editing the topology file.

i2 Analyze places no restrictions on the number of security dimension values providers you can use. Each provider adds values to its associated dimension. If a dimension in the file contains no dimension values, then the provider supplies all the values for that dimension.

Note: The security dimension itself must always be defined in the security schema file. It is not possible to add or remove security dimensions dynamically.

Procedure

Configure a security dimension to use a dimension values provider:

Using an XML editor, open the security schema file for the deployment.
The security schema file is in the toolkit\configuration\fragments\common\WEB-INF\classes directory. The name of the file is specified in the DynamicSecuritySchemaResource property of the ApolloServerSettingsMandatory.properties file in the same directory.

In the <Dimension> element for the dimension that the provider works with, add the ProviderClass attribute. For example:

<Dimension Id="SD-SC"
    DisplayName="Security Compartment"
    Description="Security Compartment"
    Ordered="false"
    ProviderClass="com.example.security.provider.SecurityCompartmentDimensionValuesProvider" />

Modify the security permissions so that it's possible for all users to get the "Read only" or "Update" access level for at least one value in the updated dimension.
Note: When you use a dimension values provider, it's likely that you'll also need to use a security permissions provider.
Increment the version number that is stated in the Version attribute of the <SecurityDimensions> element in the security schema file.
Save and close the file.

Update the topology file so that i2 Analyze can retrieve values from the provider:

Copy the JAR file that contains the security dimension values provider, as well as any dependencies of that file, to a new subdirectory of the fragments directory. For example, toolkit\configuration\fragments\security-compartment-provider.
Using an XML editor, open the toolkit\configuration\environment\topology.xml file.

Edit the <fragments> element to include the new fragment. For example:

<fragments>
  <fragment name="opal-services-is"/>
  <fragment name="opal-services"/>
  <fragment name="common"/>
  <fragment name="default-user-profile-provider"/>
  <fragment name="security-compartment-provider"/>
</fragments>

Redeploy i2 Analyze to update the application with your changes:

In a command prompt, navigate to the toolkit\scripts directory.
Stop Liberty:
```
setup -t stopLiberty
```

Update and redeploy the system:

setup -t updateSecuritySchema
setup -t deployLiberty

Start Liberty:
```
setup -t startLiberty
```

After you've configured the i2 Analyze server to use a dimension values provider, you can change the values that it provides without reconfiguring the server.

The server requests values from all providers at startup, and at intervals afterwards, to ensure that it always has an up-to-date set.

What to do next

Security dimension values must have security permissions associated with them. The new provider adds security dimension values to the security schema dynamically, and it is likely that you'll need to deploy a security permissions provider to add those dynamically too.

If you use a security dimension values provider that might stop providing some values, the effect is the same as removing values from the security schema file. It has the same potential impact on users, and you should take the same steps to explain the behavior they see.