Configuration

Choose an Authentication Method

Agility Blue offers two authentication methods to connect to Relativity: Basic or OAuth2

Our recommendation

The OAuth2 authentication method is our recommended approach. There is additional setup involved on the Relativity side, but the benefit is that you do not have to expose any username or password information to Agility Blue in order to communicate with Relativity.

Relativity Permissions

Regardless of the chosen authentication method, it is necessary that the linked Relativity user account has enough permissions to be able read a list of Relativity Workspaces and have the ability to read Relativity Production Sets within a workspace.

RelativityOne Usage Report Metrics

To allow Agility Blue the ability to collect usage report metrics from a RelativityOne instance, Relativity requires the following:

• You must use the OAuth2 authorization method to connect to Relativity

• The connected Agility Blue account must be a System Administrator or a Client Domain Administrator

• The connected Agility Blue account must have the View Usage Report instance permission

• The connected Agility Blue account must have the View Admin Repository permission

These requirements are set by Relativity and are outlined under their usage reports documentation. For more information on setting up RelativityOne instance permissions, please refer to their help documentation on setting instance permissions or contact Relativity support for assistance.

Configure Relativity Authentication

Relativity documentation

For more information on how Relativity leverages basic and bearer (OAuth2) authentication, refer to Relativity’s API authentication documentation.

Configure Relativity for Basic Authorization

If you choose to use the Basic Authorization method to connect to Relativity from Agility Blue, there is not much setup needed from Relativity. We recommend that a dedicated Relativity user account be created specifically for Agility Blue for access control and auditing purposes — however, this is not necessary. The Relativity user account must be setup with a Password Authentication Provider, as you will need to provide the Relativity username and password to Agility Blue.

Configure Relativity for OAuth2 Authorization ^{(Recommended)}

Login to Relativity as a user that has permission to create OAuth2 Clients.

Navigate to the OAuth2 Client tab (this can be found under the Authentication parent tab).

Click on the New OAuth2 Client button and you will be presented with the following page:

Fill out the OAuth2 Client Information form with the following information:

• Name: Agility Blue

• Flow Grant Type: Client Credentials

• Context User: Select a user that will be represented by calls from Agility Blue. We recommend that a dedicated Relativity user account be created specifically for Agility Blue for access control and auditing purposes, though not necessary.

• Enabled: Yes

• Access Token Lifetime: Relativity recommends setting this value to 60 (1 hour). This means that when Agility Blue receives an OAuth2 token from Relativity, the token will be valid for one hour before Agility Blue needs to ask Relativity for a new token.

When you save the form, Relativity will display the OAuth2 client details. Pay attention to the two fields that Relativity generates on this screen: Client Id and Client Secret. You will need to provide these values to Agility Blue while configuring the connection information.

Configure Agility Blue

Within an Agility Blue workspace, navigate to the workspace settings page by clicking on the gear icon in the top right and choosing the Settings option.

Click on the integrations section tab on the left to view the list of installed integrations.

Locate the Relativity integration. If the toggle switch on the far right is switched off, click on it to enable it. If the toggle switch is already enabled, click on the cog icon button to the left of the switch. If you do not see the Relativity Integration listed, please contact support to get one installed into your workspace.

After clicking on the cog icon button, you will be presented with the following window:

Fill out the form with the following information

• Relativity Instance URL

  This is the base URL for your Relativity instance. For example: https://agilityblue.relativity.one. It is highly recommended that your Relativity Instance URL is configured as HTTPS to ensure secure communication between Agility Blue and Relativity.

• Relativity Authorization Method

  Choose the authorization method you would like Agility Blue to use to communicate with Relativity.

• If you choose the Basic authorization method, the following fields become visible:

  • Relativity Username

    Enter a Relativity username.

  • Relativity Password

    Enter the password for the Relativity user

• If you choose the OAuth2 authorization method, the following fields become visible:

  • Relativity OAuth2 Client Id

    Enter the OAuth2 Client Id that Relativity provided during the OAuth2 Client setup instructions above.

  • Relativity OAuth2 Client Secret

    Enter the OAuth2 Client Secret that Relativity provided during the OAuth2 Client setup instructions above.

• If your Relativity instance URL is not a RelativityOne instance, you will see a Use Modern Relativity APIs? switch

  Disable this switch if your version of Relativity Server is lower than version 12.1.431.2 (this is uncommon).

• Click on the Save button

After saving, Agility Blue will attempt to reach out to Relativity and test the connection. If Agility Blue is able to connect to your Relativity instance, a message will briefly display that a successful connection was made and the connected Relativity version. If you receive an error, make sure that your settings are correct and the account you are using in Relativity has the proper permissions setup. Contact support at support@sadiebluesoftware.com to receive troubleshooting assistance on connection issues.