Using Microsoft Graph API for sending email communications

To use the Microsoft Graph API for Legal Hold email communications, you need to register the RelativityOne Legal Hold application in Entra ID and set your processor type to Graph API in RelativityOne. For more information on setting your processor type, see Adding email settings.

The Microsoft Graph API is an endpoint used to access data and services across Microsoft services. It is a RESTful web API that performs a variety of tasks. In this case, to send communications as a Microsoft user from Relativity.

Requirements

When leveraging the Graph API, you must use a Microsoft user email address and licensed mailbox. For more information, see Registering an Azure application and credentials.

Relativity Government users with a GCC High license can use the Graph API.

Considerations

When leveraging the Graph API, we recommend:

  • Creating a legal hold-specific email address. For example, legalholds@companyxyz.com to send hold communications.
  • Not using an individual user email address as legal hold notices will appear as if they are coming from that individual user.

This email requires an individual user license to authenticate with the Graph API. You cannot use emails from shared or group mailboxes because application permissions cannot be authenticated with those account types.

Registering an Azure application and credentials

To use the Microsoft Graph API, you need to register the RelativityOne Legal Hold application in Entra ID. Authentication requires a reference to a dedicate Azure application that has the appropriate permission. This needs to be done on the client side by an Azure user with sufficient rights.

Start with registering your application in the Azure portal by following the steps below. For more information on registering an application in Azure, see Microsoft's documentation or Microsoft's authentication documentation.

Note: These steps must be completed by a Microsoft 365 administrator.

  1. Open your Azure Portal.
  2. Click Microsoft Entra ID (formerly known as Azure Active Directory).
  3. Click App registrations.
  4. Click New Registration to display the Register an application page.
  5. Enter an application name in the Name field.
  6. Accept the default setting, Accounts in this organizational directory only, as the supported account type.
  7. Click Register.
  8. Once the application is registered, make note of the Application (client) ID and Directory (tenant) ID for use later when configuring the data source in RelativityOne Collect.

Adding permissions

Next, from the application's page, add permissions to the web API by following the steps below:

  1. Click API Permissions.
  2. Click Add a permission.
  3. Click Microsoft Graph.
  4. Select Delegated Permissions.
  5. Select the following options from the Delegated Permissions section:
    • Mail – Mail.Send, Mail.ReadWrite
    • User – User.Read
  6. Click Add Permission.
  7. Click Grant Admin Consent and then click Yes.

Configuring the redirect URL

In Azure Portal, navigate to the application's Overview page you are using for the integration. 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 in your Redirect URL.
    Replace the bold part of the URL with your organization's subdomain, domain, and top-level domain.
    Format:https://{RelativityURL}/Relativity.Rest/API/kCura.LegalHold.Services.ILegalHoldModule/Graph%20Authorization%20Manager/graph-auth-response >
    Example:https://yourorganization.relativity.one/Relativity.Rest/API/kCura.LegalHold.Services.ILegalHoldModule/Graph%20Authorization%20Manager/graph-auth-response
  5. Click the Configure button.

For more information on adding a redirect URL to Azure, see Microsoft’s 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.

After you complete registering your app and have your client secret, you need to add this information to your email settings. For more information, see Adding email settings.

Authenticating with Microsoft

After registering the Relativity app in Microsoft, you must authenticate your application ID and password in Relativity, and your user email inbox. For example, legalholds@companyxyz.com. To authenticate with Microsoft, follow the steps below.

  1. Open your Relativity instance.
  2. Navigate to the Legal Hold Settings page.
  3. Enter the required email settings fields. For more information, see Fields and Adding email settings.
    Note: We recommend saving the required email settings information in a secure location.
  4. In the Settings console on the right side of the Legal Hold Settings page, click one of the Authenticate with Microsoft buttons.
    Click Authenticate with Microsoft (Outgoing) if using the Graph API for outgoing emails or Authenticate with Microsoft (Incoming) if using the Graph API for incoming emails. For more information, see Testing the outgoing email settings or Testing your incoming email settings.
    Clicking either of these buttons opens a Microsoft login screen.
  5. Authenticate with the user you would like to send or receive communications through.
  6. Click Sign in.

Note: Once set up, if Graph API is not used within 90 days for sending emails, you must authenticate again in RelativityOne. Additionally, if the password for the account you authenticate with changes at any time, you must authenticate again in RelativityOne.

After signing in, Legal Hold displays a confirmation message telling you that the authentication is complete and that you can close the current tab. At this point, authentication with Microsoft is complete.

Fields

The fields you need to complete in Relativity to use the Graph API.

  • Application Client ID—enter the Application Client ID created during registering the Legal Hold application in Microsoft 365.
  • Application Client Secret—enter the Application Client Secret created during registering the Legal Hold application in Microsoft 365.
  • Tenant ID/Domain—enter the Domain name of the Microsoft 365 tenant the collection is intended for.
  • From Email Address—enter the email address you authenticated with Microsoft. Relativity will only use the email inbox that you authenticated with.
  • Reply to Email Address—enter the email address you authenticated with Microsoft. Relativity will only use the email inbox that you authenticated with.
  • Email Processor Type—select the Graph API in the drop-down menu.
  • Enable Auto Refresh—enable to have Relativity automatically refresh the token if an email has not been sent for 70 days eliminating the need re-authenticate.
    Note: If disabled and the Graph API is not used for 90 days, then the refresh token will be invalidated.