Item type security

In some deployments of i2 Analyze, it is necessary to configure the system so that only users in specific groups are able to interact with records with particular item types. For users without the necessary permissions, records with those types are invisible - it is as if they do not exist.

The type-access-configuration.xml file in the toolkit/configuration/live directory contains the item type security configuration, which defines how user groups have visibility of specified item types.

Note: The type-access-configuration.xml file allows item type security to be determined by user group membership. However, it is possible to configure item type security based on additional user information, for example their record security access permissions (defined by the security schema). To do this, you must implement the item type security SPI.

By default (and ignoring metadata), the type-access-configuration.xml file contains only its root element:


<tns:TypePermissions>
</tns:TypePermissions>

If the file does not exist or remains in its default state, then all users have access to all records, subject to the rules of the security schema.

Note: The configuration file is processed after item type conversion takes place. As such, the restrictions you define apply only to the types that are present post-mapping.

Configuration example

Given a deployed schema that contains the entity types ET1, ET2, ET3, and LT1, consider the following configuration:


<tns:TypePermissions DefaultSchemaShortName="...">
  <ItemType Id="ET1" SchemaShortName="...">
    <Allow>
      <UserGroup Name="Analyst"/>
      <UserGroup Name="Clerk"/>
    </Allow>
  </ItemType>
  <ItemType Id="ET3">
    <Allow></Allow>
  </ItemType>
  <ItemType Id="LT1"></ItemType>
</tns:TypePermissions>

This configuration defines the following:

Records with type ET1 are visible only to users who belong to the Analyst or Clerk groups. Users belonging to other groups are not able to see records with this type.
There is no permission for the type ET2. All users can see records with that type.
The permission for type ET3 contains an empty <Allow> element. This means that records with type ET3 are invisible to all users except those in groups that have the i2:Administrator command access permission.
The permission for type LT1 contains no <Allow> element. As such, just like ET2, all users can see records with the LT1 type.

Schema short names

In a deployment of i2 Analyze that contains several schemas, it is possible for item types from different schemas to have the same identifier. To avoid this potential problem, you can specify the short name of the schema that contains each type you want to configure.

As shown in the example above, you specify the schema short name through either the SchemaShortName attribute on an <ItemType> element, or the DefaultSchemaShortName attribute on the root <tns:TypePermissions> element.

If you omit the SchemaShortName attribute for an <ItemType> element, the value of DefaultSchemaShortName is used instead. If you provide neither attribute, i2 Analyze attempts to resolve the identifier against all schemas in the deployment. If the item type appears in more than one schema (or in none of them), i2 Analyze logs a warning that it cannot resolve the specified item type.

Note: It is not possible to specify more than one <ItemType> element with the same Id and SchemaShortName attributes.

Other considerations

Take note of the following considerations when you configure item type security in your deployment of i2 Analyze.

Command access control

Users in groups with the i2:Administrator command access permission are never affected by item type permissions.

Connectors & services

A connector service is hidden from the list of services on the client if all the possible item types of result records, as defined by resultItemTypeIds in the service configuration, are invisible to the user. If all of a connector's services are hidden for this reason, the connector itself is hidden.

Entities & links

Item type security restrictions on one entity type have no implications for other entity types. Similarly, restrictions on one link type have no implications for other link types, or for entity types. However, restrictions on the visibility of entity records can also affect the visibility of link records.

Taking the example configuration above, the deployed schema might specify that the entity type ET1 is the only permitted type for records at one end of links with type LT1. In other words, ET1 is the only entity type identifier in the fromTypeIds or toTypeIds attribute for the link type, like this:

<LinkType Id="LT1" FromTypeIds="ET1" ToTypeIds="ET2" ...>

In this situation, users who cannot see records of type ET1 also cannot see records of type LT1.

On the other hand, if the definition of LT1 specifies other valid link end types that are not restricted for the same users, as in this case, then records of type LT1 remain visible:

<LinkType Id="LT1" FromTypeIds="ET1 ET2" ToTypeIds="ET2" ...>

Seeds

Item type security restrictions can affect the behavior of seeded search services. The following rules apply to services configured with seedConstraints:

If the service accepts seeds of a restricted type, and does not specify that it must have at least one seed of that type (that is, it is possible to use the service without a seed of the restricted type), then that constraint is removed from the user's view.
If the service accepts seeds of a restricted type, and it must have at least one seed of that type, then the service is removed from the user's view.

Item type conversion

As previously mentioned, item type restrictions apply only after item type conversion has taken place.

Asynchronous queries

Asynchronous queries are validated when they are launched, to ensure that the seeds are visible to the user.

If a user's permissions change after initiating the asynchronous query on the connector, the query runs to completion, but any results no longer visible to the user are filtered out of the result set (which might be empty as a result).