Configuring claims-based authentication

When i2 Analyze uses an identity provider for authentication, authenticated users are associated with claims that provide information about them, including their group memberships. i2 Analyze supports user authentication through Security Assertion Markup Language (SAML) and OpenID Connect (OIDC) identity providers.

Configuring i2 Analyze for claims-based authentication

To use any kind of claims-based authentication with i2 Analyze, you must first configure the system to use the claims-based user groups provider.

Claims-based authentication requires that your deployment is configured for TLS. For more information, see Transport Layer Security connections with i2 Analyze.
Update the configuration\fragments\common\WEB-INF\classes\ApolloServerSettingsMandatory.properties file to specify the claims-based user groups provider in the UserGroupsProvider setting:
```
UserGroupsProvider=com.i2group.disco.user.ClaimsBasedUserGroupsProvider
```

After you've made those changes, you can set up i2 Analyze to use either a SAML or an OIDC identity provider for user authentication.

Configuring SAML authentication

To configure SAML authentication, you must update the Liberty configuration to work with your identity provider and redeploy the system.

Update the configuration\liberty\server.extensions.xml file to include the samlWeb-2.0 feature:
```
<featureManager>
  ...
  <feature>samlWeb-2.0</feature>
</featureManager>
```
Redeploy and restart Liberty by running the following commands:
```
setup -t deployLiberty
setup -t startLiberty
```
Navigate to https://<liberty-hostname>:<ssl-port>/ibm/saml20/defaultSP/samlmetadata to download a server provider (SP) metadata file named spMetadata.xml.
Send the spMetadata.xml file to your identity provider and receive an identity provider (IdP) metadata file in exchange. Ensure that you are added to the correct group. You'll be given a group ID that you can use to configure the server.
Rename the IdP file that you received to idpMetadata.xml, and place it in the i2analyze\deploy\wlp\usr\servers\opal-server\resources\security\ directory on the Liberty server.
Update the server.xml file to include a <samlWebSso20> element with a groupIdentifier attribute. The value for the attribute comes from the URI for the "Groups" claim type in the idpMetadata.xml file. For example:
```
<samlWebSso20 id="defaultSP" groupIdentifier="http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"/>
```
For more information about all of the options for configuring SAML in Liberty, see SAML Web Single Sign-On 2.0.
Ensure that the group names that i2 Analyze receives from the identity provider align with the groups referenced in your security schema and command access control files.
To update your security schema, follow the instructions in Configuring the security schema.
Note: If the group names from the identity provider don't match the group names in your security schema, one solution is to use provisioning to map from one to the other.
Redeploy and restart Liberty again by running the following commands:
```
setup -t deployLiberty
setup -t startLiberty
```
Connect to the system, and log in as a user that is authenticated by your identity provider.

Configuring OIDC authentication

To configure OIDC authentication, you must update the Liberty configuration to work with your identity provider and redeploy the system.

Update the configuration\liberty\server-extensions.xml file to include the openidConnectClient-1.0 feature:
```
<featureManager>
  ...
  <feature>openidConnectClient-1.0</feature>
</featureManager>
```
In the same file, add an <openidConnectClient> element and populate its attributes according to the values from your identity provider.
The following values are used in the example configuration below:
- id - an identifier for this OIDC client defined in Liberty. This value is used in the redirect URI of the client in the provider.
- clientId - the identifier of the client for i2 Analyze defined in the identity provider.
- clientSecret - if your identity provider is configured for client authentication, this is the secret used to authenticate the client with the provider.
- discoveryEndpointUrl - the URL for the OpenID endpoint configuration from the identity provider.
- signatureAlgorithm - the algorithm used to encrypt the tokens that the identity provider returns.
- userIdentifier - the name of the claim in the token that contains the user's username.
- uniqueUserIdentifier - the name of the claim in the token that contains a unique identifier for the user.
- groupIdentifier - the name of the claim in the token that contains a user's group information.
```
<openidConnectClient 
    id="client01"
    clientId="oidc-example"
    clientSecret="PUgXRYXhWmVDUbAwHy4Bjg7LiKV"
    discoveryEndpointUrl="https://keycloak.eia:8443/realms/oidc-example/.well-known/openid-configuration"
    signatureAlgorithm="RS256"
    userIdentifier="preferred_username"
    uniqueUserIdentifier="sub"
    groupIdentifier="groups"
/>
```
For more information about all of the options for configuring OIDC in Liberty, see OpenID Connect Client 1.0.
Ensure that the group names that i2 Analyze receives from the identity provider align with the groups referenced in your security schema and command access control files.
Redeploy and restart Liberty by running the following commands:
```
setup -t deployLiberty
setup -t startLiberty
```
Connect to the system, and log in as a user that is authenticated by your identity provider.