Custom provisioning with an identity provider

When i2 Analyze is using an identity provider for user authentication, you can choose whether provisioning happens "just in time", from the claims in the tokens that the identity provider sends, or whether it is controlled by another file that you provide. The choice affects your users' experience of the system.

Just-in-time provisioning

Just-in-time provisioning is the default behavior of an i2 Analyze deployment that uses an identity provider for user authentication.

In just-in-time provisioning, i2 Analyze receives its information about a user and the groups they're a member of from claims in a token that the identity provider creates. In other words, i2 Analyze knows nothing about any users or groups until they appear in a claim. Rather, it builds up a picture as more users log in.

One of the consequences of this behavior is that users can't share artifacts with each other until they've both logged in at least once. It also means that in theory, any user with a valid token from the identity provider can log in to i2 Analyze.

To change the default behavior, you have to include the identityProviderConfig object in the provisioning-configuration.json file. The object contains the following properties:

provisionUsing

A string value that indicates the source of the identity provider's provisioning data. Use CLAIMS to retain the default behavior but gain the ability to specify which claim contains the user's display name.

displayNameClaim

A string value that specifies the claim that contains the display name of the user. The default value is name. displayNameClaim is only used when provisionUsing is set to CLAIMS.

"identityProviderConfig": {
  "provisionUsing": "CLAIMS",
  "displayNameClaim": "name"
}

File-based provisioning

In file-based provisioning, you provide i2 Analyze with advance knowledge of the users and groups from the identity provider. This behavior improves on just-in-time provisioning in two ways:

  • The users and groups that you specify in the file are the only ones that can access i2 Analyze or appear as system groups. This restriction is useful if you want to limit access to a subset of the users in the identity provider.

  • The users and groups in the file are available as soon as the system starts, so users can share artifacts with each other before everyone has logged in.

To specify file-based provisioning, you must set the value of the provisionUsing property of the identityProviderConfig object to FILE in the provisioning-configuration.json file:

"identityProviderConfig": {
  "provisionUsing": "FILE"
}

This setting tells i2 Analyze to look for a file called identity-provider-users-and-groups.json in the same directory as the provisioning-configuration.json file. The file must contain the users and groups that you want to provision, in arrays named users and groups.

A user can only access the system if their user name is present in the users array. Their group membership is defined by the groups they are a member of in the groups array.

Note: To log into the system successfully, a user must receive at least the "Read only" access level for at least one value in every security dimension. For more information, see i2 Analyze security permissions.

users

In the identity-provider-users-and-groups.json file, the users array contains objects that specify the users available to the system.

id

A string that specifies the unique identifier of the user.

userName

A string that specifies the user name of the user.

displayName

A string that specifies the display name of the user.

groups

The groups array contains objects that specify the groups available to the system, and the users that are members of each group.

id

A string that specifies the unique identifier of the group.

displayName

A string that specifies the display name of the group.

memberIds

An array of strings that specify the unique identifiers of the users or groups that are members of the group.

An example identity-provider-users-and-groups.json file is shown below:

{
  "users": [
    {
      "id": "40bd47aa-a672-46d3-94b3-51c938aa5dd0",
      "userName": "Imogen.Evans@example.com",
      "displayName": "Imogen Evans"
    }
  ],
  "groups": [
    {
      "id": "6ec017b0-ba12-42d9-80e6-d99c37a0896b",
      "displayName": "Investigation Group 1",
      "memberIds": [
        "40bd47aa-a672-46d3-94b3-51c938aa5dd0"
      ]
    }
  ]
}

In this example, the user Imogen Evans is a member of the group Investigation Group 1.