Adding preservation hold settings using Modern Authentication (Legacy)

Use the new Preservation in-place application for any new preservation holds. For more information, see Preservation in-place.

Preservation Hold Settings must be configured before creating a preservation hold for a custodian. The Preservation Hold Settings page is used to add, edit, or remove preservation hold data sources from legal hold projects with Microsoft 365 data sources. Preservation hold settings temporarily grant collection admin permissions to the specified account user to determine custodian SharePoint site access privileges during target discovery.

Preservation in-place functionality uses modern authentication, which is certificate-based authentication (CBA) that allows for multi-factor authentication (MFA) and is known to be more secure than providing username and password via the basic authentication method.

A legal hold admin will need to run through a one-time setup to connect Microsoft 365 to Relativity. For more information, see Adding preservation hold settings using Modern Authentication (Legacy).

Background information

Our previous preservation in-place functionality in the Legal Hold application used basic authentication, which involved providing username and password for authenticating with Microsoft Purview eDiscovery Standard.

Due to Microsoft’s deprecation of basic authentication in many places of Microsoft 365, support for basic authentication in our product was deprecated as of June 1, 2023. We updated our authentication approach to use the modern authentication. For more information on Microsoft’s deprecation of basic authentication, please refer to Microsoft's documentation.

Permissions

Enable the Preservation Hold Settings security permission in order to create a preservation hold setting. For more information on security permissions, see Legal Hold Application Permissions.

Adding preservation hold settings

Follow the steps to configure preservation hold settings. This is a one-time setup to create data sources for a preservation hold.

Step 1: Setup in Microsoft

The person performing the steps below should be a Microsoft Azure admin and familiar with setting up certificates. Follow the steps below to set up app-only authentication in Entra ID. For more information, see Microsoft's documentation for setting up app-only authentication in Entra ID.

1. Register the application in Entra ID.
2. Assign the following API permissions with Admin consent granted to the application:
   • Exchange.ManageAsApp
   • Sites.Read.All (this permission is for Graph API)

3. Generate a self-signed certificate.
   Notes:
   • You will need the .pfx file, not the .cer file, generated when entering data in the Step 3: Preservation Hold Settings Configuration section.
   • You can also use a purchased or generated certificate from your organization.

4. Attach the certificate to the Entra ID application.
5. Assign Entra ID roles of Compliance Administrator and Exchange Administrator to the application.

You will use the information created for the next few steps below.

Step 2: Run PowerShell Script to create a Service Principal

Now that you’ve setup an app in Entra ID in Step 1: Setup in Microsoft above, you need to create a Service Principal that is associated with the app. To do this, you will need to run the following PowerShell script:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
## Authenticate with Microsoft (including providing answer for MFA)
$AppId = "Application-ID-FROM-AZURE-AD"
$appName = "AppNAME-FROM-Azure-AD"
$spDisplayName = "your_sp_displayname"
​
# access token is passed to Connect-AzureAD
# the user logging, will require admin permissions. 
Connect-AzureAD
$AADApp = Get-AzureADServicePrincipal -SearchString $appName
​
# create service principal in scc
connect-ippssession
New-ServicePrincipal -AppId $AADApp.AppId -ServiceId $AADApp.ObjectId -DisplayName $spDisplayName
$SP = Get-ServicePrincipal -Identity $spDisplayName
​
#this is the new command that is added
Add-eDiscoveryCaseAdmin -Confirm:$false -User $appId
​
disconnect-exchangeonline -Confirm:$false

Replace these values in the script with your information:

• $AppId—replace "Application-ID-FROM-AZURE-AD" with the Application ID that was created in Step 1: Setup in Microsoft.

• $appName—replace "AppNAME-FROM-Azure-AD" with the Application Name that was created in Step 1: Setup in Microsoft.

• $spDisplayName—replace "your_sp_displayname" with a display name for your service principal. This can be any name that you want to use to identify the service principal, for example RLH_PIP_ServicePrincipal.

Step 3: Preservation Hold Settings configuration

Use the steps in this section to set up modern authentication in the Preservation Hold Settings object in your workspace.

1. Navigate to the Preservation Hold Settings tab within Legal Hold Admin.

2. Click the New Preservation Hold Settings button.

3. Fill out these fields as follows:

   

   Basic Settings:

   • Name—enter the name to identify the data source.
   • Domain Name—enter the Microsoft 365 Tenant name. The domain name is located between @ and .onmicrosoft.com. For example, the domain in ediscovery@relativity.onmicrosoft.com is relativity.
   • URL—this read-only URL is the connection to Microsoft 365 Protection Services utilized by Legal Hold.
   • Account User—leave this field blank. It is not used with modern authentication.
   • Account Password—leave this field blank. It is not used with modern authentication.
   • Resolve SharePoint Site Permissions—select Yes to temporarily grant the required permissions to the account user in order to obtain the list of custodians that have access to a given site during the target discovery process.

     Note: If this option is not enabled, it is possible that not all targets will be returned during the discovery process. The account user must have all required permissions to read the site properties. For more information, see Microsoft's documentation.

   Modern Authentication Settings:

   • Enable Modern Authentication—select Yes.
   • Organization—enter the fully qualified domain name of your Microsoft tenant (organization), including the ".onmicrosoft.com" portion. For example, relativitytest.onmicrosoft.com.
   • Application ID—enter the Application ID that you created in Step 1: Setup in Microsoft.
   • Tenant ID—enter the Tenant ID that you created in Step 1: Setup in Microsoft.
   • Certificate—attach the self-signed certificate that you created in Step 1: Setup in Microsoft.
   • Certificate Password—enter the password that protects the private key of the certificate that you created in Step 1: Setup in Microsoft.

4. Click Save.

Step 4: Validate preservation hold settings

After saving the Preservation Hold Settings, you have the option to validate the connection to Compliance Center. This step also validates that Relativity can place a hold in Exchange Mailbox and OneDrive.

1. Click the Validate Settings button under the Settings bar on the right side to validate that modern authentication is configured correctly.
   This will create and then delete a sample preservation case in Microsoft Purview.

2. If the validation worked correctly, the Validation Status field will display “Validated.” If it did not, the Validation Error field will contain the error message and you will need to correct the error.
3. Once the validation is successful, you are ready to set up preservation holds using the Legal Hold wizard. See Preservation hold (Legacy).

Step 5: Configuring SharePoint preservation holds

If you're interested in placing a hold on SharePoint sites, you will need to follow the steps in Setting up SharePoint Discovery for preservation holds (Legacy).

Deleting a preservation hold setting

1. To delete a preservation hold setting, delete all projects using the setting first. To learn how to delete projects, see Deleting a project.
2. Once the projects have been deleted, navigate to the Preservation Hold Setting and click the Delete button. This action deletes the preservation hold setting from Legal Hold.

Note: Due to background processes, the preservation hold setting may not be immediately deleted.