Microsoft Graph API - Delegated permissions

To use the Microsoft Graph API for hold email communications, you must register the Legal Hold application in Entra ID and set your processor type in RelativityOne to Graph API or Graph API Gov. 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.

Considerations

When leveraging the Graph API or Graph API Gov, we recommend the following:

• Create a legal hold-specific email address. For example, legalholds@companyxyz.com to send hold communications.
  
• Using delegated permissions requires a login from the Legal Hold Settings page. Relativity uses whichever account is logged in to send emails.
• Do not use an individual user email address as legal hold notices will appear as if they are coming from that individual user.
• Do not use emails from shared or group mailboxes because application permissions cannot be authenticated with those account types.

Licenses

When leveraging the Graph API, you must use a Microsoft user email address and licensed mailbox, with at least an E3 license.

If you do not have a Microsoft user email address and licensed mailbox, you must create a user with the correct licenses. For more information on creating a licensed user in Microsoft, see Microsoft's documentation.

To use the Graph API, Relativity commercial and Government users need the following Microsoft licenses:

• Relativity commercial users—the Microsoft user and mailbox must have at least an E3 license.
• Relativity Government users—the Microsoft user and mailbox must have a GCC High license.

For more information on assigning licenses for users in Microsoft 365 admin center, see Microsoft's documentation.

Requirements

When you have the licenses in place, then you must complete the following steps in order before setting up a Microsoft application to communicate:

1. Registering an Azure application and credentials
2. Adding permissions
3. Configuring the redirect URL
4. Creating a client secret
5. Authenticating with Microsoft
6. Adding email settings

After completing these required steps, you can configure the Microsoft account in RelativityOne.

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.

Before you register an application, you must have a licensed Microsoft user email address and mailbox, with at least an E3 license. For more information, see Requirements.

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.

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. Commercial and GCC High users must add Delegated permissions.

To add delegated permissions, complete the following steps:

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.
   
   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, Microsoft will display the Client Secret on the table and the Value field in plain text.
6. Copy the Value field and securely store it.

Microsoft hides the Value field if you leave the page and then come back to get the value. At this point, you cannot 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.

Before adding email settings, make sure you understand all Considerations and completed all tasks in the Requirements sections.

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.
   
   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.

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.
  
  If disabled and the Graph API is not used for 90 days, then the refresh token will be invalidated.

Adding email settings

After completing the required steps in Microsoft, you can then set up the account in RelativityOne.

Before adding email settings, make sure you understand all Considerations and completed all tasks in the Requirements sections.

To set up Microsoft for Legal Hold:

1. Navigate to the Legal Hold Settings page.
2. Click Edit.
3. Select either the Outgoing Email or Incoming Email section.
4. Enter information in the fields. For more information, see Outgoing email fields or Incoming email fields.
   
5. Update another section or click Save.

Outgoing email fields

Enter the information you gathered in Microsoft into the following fields:

• 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. For more information, see Creating a client secret.
• Tenant ID/Domain—enter the Domain name of the Microsoft 365 tenant the collection is intended for.
• From Email Address—enter the email address of the account you registered with or an account you gave mailbox permissions to. If you enter in an email address other than the one you authenticated with, you must give mailbox permissions to that Microsoft 365 account. For more information, see Microsoft Graph API - Application permissions.
  •  When using the Graph API, the From Address will be the address associated to the account that was used to authenticate to Microsoft. When a custodian receives a project communication, it will appear as if it was sent from the account that authenticated to Microsoft.
  • If you want to send from another account that you did not use to authenticate with, you must give the mailbox permissions to the Microsoft 365 account you want to send from For more information, see Microsoft Graph API - Application permissions. If the permissions are not given to the other account, then Relativity will send communications as the registered account holder. For more information, see Microsoft's documentation:
    • For admin's adding up email settings, see Give mailbox permissions to another Microsoft 365 user.
    • For user's creating communications, see Allow members to send as or send on behalf of a group.
• Reply to Email Address—enter the reply to email address. When a custodian clicks reply to a project communication, their reply is sent to this address. See the From Email Address example above.
• 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.
  If disabled and the Graph API is not used for 90 days, then the refresh token will be invalidated.

For more information, see Outgoing email fields.

Incoming email fields

Enter the information you gathered in Microsoft into the following fields:

• 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.
• Mailbox(Optional)—enter the actual name of the folder containing the custodian replies to Legal Hold communications. For example, Inbox. This Mailbox field is case sensitive.

For more information, see Incoming email fields.