Integrating Entra ID for Custodian Portal SSO

To complete the set up of SSO authentication using the Entra ID provider, you need:

  • Log into your .onmicrosoft.com account.
  • Azure user with sufficient access to create, register, and modify Azure applications.
  • Azure Active Directory with at least one user.
  • A Relativity users with workspace Admin rights.
  • Additional people as custodians to assist in verifying Portal SSO access.
  • Portal Settings have been populated within Legal Hold Settings.

For more information, see Custodian Portal Authentication Provider.

Understanding Code flow and Implicit flow

Before registering Relativity as an application and setting up a custodian portal authentication provider, it is best to understand Code flow and Implicit flow. It is best to know what will work for your organization.

Custodian Portal Authentication can use OAuth 2 framework to enable Relativity to authorize users to access to the Custodian Portal. Legal Hold can utilize either Implicit Flow or Code flow to accomplish this.

  • Implicit flow—passes an access token directly, not as a URL parameter.

  • Code flow—passes the access token as a parameter of the HTTP Request when preforming authorization.

We recommend consulting your internal security teams to decide which flow to use for Custodian Portal Authentication Provider.

Registering an Azure application and credentials

Portal SSO authentication requires a reference to a dedicate Entra ID application that has the appropriate permission. This needs to be done on the client side by an Entra ID user with sufficient rights.

Register the Relativity application to gain access to Microsoft Entra ID. Access to Entra ID gives Relativity the ability to complete multiple tasks.

Start with registering your app by following the steps below:

Note: The person completing the application registration process needs to be an Azure Administrator with sufficient privileges.

  1. Open your Azure Portal.

  2. Navigate to the App registrations page.

  3. Click New Registration to display the Register an application page.

  4. Enter an application name in the Name field.

  5. Select Accounts in this organizational directory only as the supported account type.

  6. Click Register.

For more information on registering an application in Azure, see Microsoft's documentation or Microsoft's authentication documentation.

Creating a client secret

A client secret from Microsoft Azure AD is needed to integrate Microsoft and Relativity.

To create a client secret:

  1. In the left-navigation menu, click Certificates & secrets.

  2. Navigate to the Client secrets tab.

  3. Click the New Client Secret button.

    Note: Do not navigate away from the page once the client secret is created.

  4. Populate the Description and Expires fields. You can leave the default, or recommended, values.

  5. Click the Add button.
    If the client secret was successfully created, you will see the Client Secret displayed on the table and the Value field should be displayed in plain text.

  6. Copy the Value field and store it safely.

If you leave the page and comeback to get the value the Value field will be masked and you will not be able to copy it

You can repeat steps 4-5 to generate a new client secret.

Setting API Permissions

Open the application to view the application's homepage. From the application's page, add permissions to the web API. 

To add permissions:

  1. Click API permissions.
  2. Click Add a Permission.
  3. Click Microsoft Graph.
  4. Select Delegated Permissions.
  5. Select the User - User.Read option from the Delegated Permissions section.
  6. Click Add Permissions.
  7. Click Grant admin consent for Relativity.

At this point the Application should be full configured. It can take a few minutes to update

Editing the custodian portal authentication provider

Continue adding the Entra ID application by navigating to the Custodian Portal Authentication Provider tab located within the Hold Admin tab.

Do the following on the Custodian Portal Authentication Provider tab:

  1. Click Edit.
  2. Enter information in the following fields:
    • Name—the application name.
    • OAuth2 Flow—select Implicit or Code. Selecting the Code option typically requires that a Client Secret be generated and copied into the Client Secret field that displays.

      Note: Custodian portal authentication can use OAuth 2 framework to enable Relativity to authorize users to access to the Custodian Portal. Relativity can utilize Implicit flow or Code flow.

      • Implicit flow—passes an access token directly, not as a URL parameter.
      • Code flow—passes the access token as a parameter of the HTTP Request when preforming authorization.
      For deciding which flow to use for Custodian Portal Authentication Provider, it is recommended that clients consult their internal security teams.

    • Client ID—the organization's security and compliance identifier. This is the Application (client) ID in the App Overview page in the Azure Portal.
    • Authority URL—the authenticated URL provided by organization's SSO provider. Relativity redirects to the next Redirect URL, which is the Custodian Portal URL.
      • Example of Azure URLs
        •  https://login.microsoftonline.com/mydomain.com
        • https://login.microsoftonline.com/tenantid

          Note: The TenantID is unique identifier (Guid) of your Azure tenant (domain). The Directory (tenant) ID on the App Overview page in the Azure Portal. This information can be provided by your Azure admin.

    • Subject Claim Type—the information the SSO provider verifies the custodian's identity.
      • The values are from the SSO Provider. If unsure about what to enter, type UNKNOWN. Some Azure claim types are:
        • http://schemas.microsoft.com/identity/claims/objectidentifier (recommended setup)
        • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn (easiest setup)
    • Claim ID Verification Field—the value which will be used to match value coming in selected Subject Claim Type. Select Entity field where you expect to have a value which will be used to match value coming in selected Subject Claim Type. If you are not sure at this time, please select UniqueID.
  3. Click Save.
  4. After refreshing the page, the Redirect URL value is populated with the unique link. Copy the Redirect URL and use it in the next section. The RedirectURL, a read-only value, is the URL which will be used by SSO Provider to redirect back to Legal Hold Portal after successful custodian authentication.

Configuring the redirect URL

You will use the copied Authority Redirect URL from the Custodian Portal Authentication Provider tab in the previous section in this section. Navigate back to the newly created application in Azure Portal window.

In Azure Portal, navigate to the Overview page for the application being used for the integration and follow the steps below.

  1. Using the left navigation column, click into the Authentication page.

  2. Click the Add a platform button.

  3. Click the Web drop-down text.

  4. Paste over the Redirect URL you generated earlier.

  5. Click the Configure button.

For more information on adding a redirect URL to Azure, see Microsoft’s documentation.

Note: It can take up to 10 minutes until the Custodian Portal Authentication Provider settings to go into effect. To speed up the update, you will need to create/modify Instance setting with a shorter time rate refresh.

Enabling ID tokens for Azure application

Follow the steps below to enable ID tokens for the Azure application for Custodian Portal SSO.

  1. In the left-navigation menu, select Authentication.

  2. Scroll to Implicit grant and hybrid flows section.

  3. Check the ID Tokens (used for implicit and hybrid flow) box.

  4. Click Save.

Troubleshooting Claims

If unsure about what to put under the Subject Claim Type and Claim ID Verification Field columns in SSO setup, you will need to use the Troubleshoot Claims option.

  1. Click Troubleshoot Claims.
  2. The top of the Troubleshooting Claims page, under Main Claims, includes TenantID information. This value corresponds to currently accessed unique identifier of your Azure tenant (domain). This information can also be used for "Authority URL" as described above. The Troubleshooting Claims page has three columns:
    • Claim Type—lists all claim types which were transmitted by Entra ID authentication provider.
    • Claim Value—contains corresponding value for each claim type transmitted.
    • Potential Claim ID Verification Field—contain potential corresponding Entity fields where matching values were detected.

        Notes: Only populated if your Relativity account, which you currently logged in under, has corresponding Custodian (Entity) entry with the same email address. So, to help with this troubleshooting process, it would be recommended to import such Custodian before.
  1. Looking at the data on this page helps to select proper Claim Type and Relativity Entity field values to populate the Subject Claim Type and Claim ID Verification Field respectively.
  1. Make necessary changes to Custodian Portal Authentication Provider settings at this time. It might take some time for this change to go into effect.