User-specific configuration

User-specific configuration is an advanced feature of i2 Connect that enables a connector to provide different configurations that are customized to specific users or groups of users. With the exception of the schema and the charting scheme (which remain global for a connector), you can customize all elements of connector configuration dynamically.

A connector can provide user-specific configuration through a separate /USER_CONFIGURATION_URL endpoint, the URL of which you can provide in your response from the standard /CONFIGURATION_URL endpoint. When an endpoint (excluding the /CONFIGURATION_URL endpoint) is called on behalf of an authenticated user, the i2 Connect gateway provides headers that you can use to identify the user making the request:

Header	Description	Type	Example value (when decoded)
`I2-User-Id`	The user's identifier	String	`4a888bdd-0b09-4cf7-9ce8-b5ab99758338`
`I2-Principal`	The user's principal name	String	`cn=user,dn=example`
`I2-Display-Name`	The user's display name	String	`User Name`
`I2-User-Groups`	The user's group membership	Base64-encoded JSON array	`["Analyst","Clerk"]`
`I2-Security-Permissions`	The user's security permissions	Base64-encoded JSON array	`[{"dimension":"SD-SL","permissions":[{"dimensionValue":"CON","level":"UPDATE"},{"dimensionValue":"UC","level":"UPDATE"}]}]`
`I2-Command-Access-Permissions`	The user's command access control permissions	Base64-encoded JSON array	`["i2:Connectors","i2:Notes"]`
`I2-Oidc-Access-Token`	The user's OIDC access token, if OIDC is the authentication mechanism for the i2 Connect gateway	Base64-encoded JSON	A set of claims, in an OIDC JSON Web Token

Important: The I2-User-Id and I2-Oidc-Access-Token headers were introduced at version 4.4.4 of i2 Analyze. Older versions of the i2 Connect gateway do not provide these headers.

Creating user-specific configurations

To implement user-specific configurations for your connector, you must first enable and then provide them.

Enable user-specific configurations

To enable user-specific configurations, you set the userConfigUrl field of a connector's configuration. For example:

{
  "userConfigUrl": "/userconfig"
}

Here, the userConfigUrl field defines the (relative) URL at which the user specific configuration can be found. When userConfigUrl is present, the only other fields that can appear in the connector's configuration are:

version
schemaUrl
chartingSchemesUrl
schemaShortName
gatewaySchema

Important: You must also instruct the i2 Connect gateway to send the above headers in requests to the connector. The headers can contain sensitive information, so the gateway does not send them by default.

To add the headers to requests that reach the connector, you must add the send-sensitive-headers attribute to the entry for the connector in the topology file:
<connectors>
  <connector id="..."
             name="..."
             base-url="..."
             configuration-url="..."
             send-sensitive-headers="true"/>
</connectors>
When the send-sensitive-headers attribute is absent, i2 Analyze behaves as if its value is false.

Provide user-specific configurations

The endpoint at the URL specified in the userConfigUrl field must return a configuration response similar to the one that the standard configuration endpoint returns. The user-specific configuration response supports the following fields:

defaultValues
services
clientConfigs
authConfigs

When a user connects to the i2 Connect gateway and a connector with user-specific configuration is present, the gateway checks whether it has a configuration cached for that user. If it does not, it calls the userConfigUrl endpoint with the headers that are listed above.

The connector can use the headers to determine which configuration to provide for the requesting user. In the example connector, the user-specific configuration is simply provided from two different static files with hard-coded settings. In practice, you can create the configurations in any way that meets your needs, including by dynamically generating them in code.

Note: In the current version of i2 Analyze, the user configuration endpoint always receives all the custom HTTP headers. It is good practice, however, to treat them as optional and handle their absence gracefully.

Setting up an example connector

The instructions in the second half of this topic describe how to extend the Java version of the NYPD example connector to support user-specific configurations.

Ensure that you have a working deployment of the Java version of the NYPD connector before you continue:

If you already followed the NYPD connector example using Java, you can use it as your starting point and build on it.
Otherwise, you can start with the sample solution (sample-solution/nypd-connector) and follow the deployment instructions.

1. Add the user-specific example override

This example works by overriding some aspects of the NYPD example connector.

Make a copy of the sample solution (or your existing NYPD connector example, if you are using it).
Copy the contents of the user-config/override directory over your copied solution. The differences between the override and the sample solution are:
- ConnectorController.java is modified to return global-config.json as the standard configuration, and to return analyst-config.json and other-config.json for the new, user-specific configurations.
- The existing config.json file is no longer used.
Note: The imports used in the modified ConnectorController.java class are based on the sample solution project. You may need to update the imports to point to the correct POJO classes defined in your existing NYPD connector example.

2. Start the connector

To start the modified connector, open a command prompt, navigate to the location that you used in the previous step, and run the application:

mvnw spring-boot:run

3. Configure group membership

To activate the modified connector, ensure that your user.registry.xml file contains at least two users. One must be a member of the Analyst group but not the Clerk group, while the other must have the opposite settings.

You can find the file at i2analyze\deploy\wlp\usr\shared\config, and a minimal example looks like this:

<user name="analyst-user" password="password"/>
<user name="clerk-user" password="password"/>
<group name="Analyst">
  <member name="analyst-user"/>
</group>
<group name="Clerk">
  <member name="clerk-user"/>
</group>
<group name="Controlled">
  <member name="analyst-user"/>
  <member name="clerk-user"/>
</group>

Note: The example assumes that you are using the example security schema. Users must also have access to at least one value from each security dimension in the security schema in order to access the system.

4. Configure command access control

The group names in the command access control file must match the names of user groups in the user registry file. To ensure that users in the Clerk group are able to view the connector, you must update the command access control file.

Navigate to toolkit\configuration\fragments\opal-services\WEB-INF\classes and open the example-command-access-control.xml file in a text editor.
Add the user group specified in the user registry file to the command access control file, and include the permission for the connector. For example:
```
<CommandAccessPermissions UserGroup="Clerk">
  <Permission Value="i2:Connectors:nypd-connector" />
</CommandAccessPermissions>
```

5. Deploy and start i2 Analyze

Next, deploy and start the Liberty server that hosts i2 Analyze:

setup -t deployLiberty
setup -t startLiberty

6. Test the connector

To test the connector, you must log in with different credentials that you expect to receive different configurations.

Using Analyst's Notebook, log in as a user that is not an Analyst and open the External Searches tool. Check that you only have access to the NYPD Connector: Search service, and that the Law Category drop-down does not contain FELONY.
Log out and log back in as a user that is an Analyst, and open the External Searches tool again. Check that the list now includes the other connector services (for example, NYPD Connector: Expand), and that the options in the Law Category drop-down include FELONY.