Microsoft 365 preservation source

You can preserve data in Microsoft 365, and Microsoft 365 Government, after completing the integration between RelativityOne and Microsoft 365.

See these related topics:

Licenses and access

You must create and configure a Microsoft 365 preservation data source before creating a preservation hold for a custodian. A legal hold admin will need to run through a one-time setup to connect Microsoft 365 to Relativity. Creating the data source temporarily grants admin permissions to the specified account user to find the custodian SharePoint site access privileges during target discovery. For more information, see Setting up a Microsoft data source.

Preservation in-place functionality uses modern authentication. Modern authentication is certificate-based authentication (CBA) that allows for multi-factor authentication (MFA).

You can preserve data from Microsoft 365 or both Microsoft 365 and Microsoft 365 Government. This depends on your RelativityOne license, commercial or government, and your Microsoft tenant, Microsoft 365 or Microsoft 365 Government

Microsoft 365 commercial

Preservation in-place is set up to point at commercial APIs. Commercial users can only preserve in Microsoft 365 tenants.

To use Microsoft's APIs, all custodians must have a E3 license, or higher.

Microsoft 365 Government

Preservation in-place is also set up to point at Government APIs instead of commercial APIs. Government users can use Legal Hold in Microsoft 365 and Government 365 tenants. These data sources have different icons within Preservation in-place.

To use Microsoft's Government APIs:

  • Tenants must have Office 365 GCC High service.
  • Custodians must have E3 license, or higher.
  • Relativity will put APIs on allowlist for the customer.

Considerations

Consider the following information before creating a Microsoft 365 data source.

Microsoft Outlook

  • Legal Hold accepts one email for one employee at a time. Legal Hold does not set accept multiple email addresses for one employee.
  • Relativity can preserve inactive employee mailboxes.

Microsoft OneDrive

  • Cannot preserve inactive OneDrives.

Microsoft Teams

  • You can preserve data in one-on-one chats only.
    • Teams Channels, group chats, are not preserved because channels are not tied to individual custodian mailboxes.
    • Microsoft stores Teams Channel data in Group Mailboxes and Sharepoint sites.
      Note: You can preserve Teams Channel attachments if you know which SharePoint site they reside on.
  • You must target OneDrive to preserve all Teams data.
    • Microsoft preserves Teams messages in a custodian’s Outlook mailbox.
    • Microsoft preserves Teams message attachments in a custodian’s OneDrive.

Microsoft Government

  • If you have a GCC high tenant, than you must use the GCC High connector when setting up a data source. For more information, see Microsoft's GCC High endpoints documentation.
  • If in GCC only, you can only use the Microsoft 365 commercial tile.

Setting up a Microsoft data source

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

There is a required, one-time setup to create data sources for a preservation hold. This setup takes place in Microsoft 365. The person completing the application registration process needs to be an Azure Administrator with sufficient privileges.

The Azure Admin must complete all steps to create and configure preservation hold credentials before creating a preservation data source in Relativity:

Note: You must complete all steps to use Preservation in-place.

  1. Register the application.
  2. Modify the manifest.
  3. Assign API permissions.
  4. Generate certificate.
  5. Assign application roles.
  6. Run PowerShell script to create a Service Principal.

After completing all these required steps, you can set up the Microsoft 365 data source in Relativity. For more information, see Creating the Microsoft 365 data source.

Register the application

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. The person performing the steps below should be a Microsoft Azure admin and familiar with setting up certificates. For more information, see Microsoft's documentation.

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. Click More Services.
  3. Search for and select Microsoft Entra ID, formerly known as Azure AD.
  4. In the left-navigation menu, select Manage > App registrations.
  5. Click New Registration.
    This will open the Register an application page.
  6. Enter an application name in the Name field.
  7. Select Accounts in this organizational directory only as the supported account type.
  8. Click Register.

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

After registering the application, you must modify the manifest to add the Exchange.ManageAsApp permission to the application. For more information, see Modify the manifest.

Modify the manifest

From the app's page, modify the app manifest and add permissions to the web API. During this procedure, you will add the Exchange.ManageAsApp permission to the application. To update the manifest, follow the steps below:

  1. In the left-navigation menu, select Manage > Manifest.
  2. Locate the requiredResourceAccess property in the manifest, and add the following JSON script inside the requiredResourceAccess square brackets ([ ]):
    Copy
    "requiredResourceAccess": [
        {
            "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
            "resourceAccess": [
                {
                    "id": "dc50a0fb-09a3-484d-be87-e023b12c6440",
                    "type": "Role"
                }
            ]
        },
        {
            "resourceAppId": "00000003-0000-0000-c000-000000000000",
            "resourceAccess": [
                {
                    "id": "e1fe6dd8-ba31-4d61-89e7-88639da4683d",
                    "type": "Scope"
                }
            ]
        }
    ],
  3. Click Save.

You have updated the manifest and added the Exchange.ManageAsApp permission to the application. This permission is needed so that the application can run cmdlets in Exchange Online in each tenant organization.

To verify that you added the Exchange.ManageAsApp permission:

  1. In the left-hand navigation, select Manage > API Permissions.
  2. Verify Office 365 Exchange Online > Exchange.ManageAsApp is listed and click Grant admin consent for <Organization>, Yes.
    The Exchange.ManageAsApp permission is needed so the application can run cmdlets in Exchange Online in each tenant organization.

Note: If you have trouble with the adding to the manifest, we recommend deleting the manifest and creating a new one.

Next, you must assign the Sites.Read.All API permission. For more information, see Assign API permissions.

Assign API permissions

You must add the Sites.Read.All API permissions to your application. The Sites.Read.All permission is needed to do OneDrive & SharePoint Discovery in Relativity.

To add the Sites.ReadAll permission,

  1. In the left-hand navigation, select Manage > API Permissions.
  2. Click Add a permission.
  3. Click Microsoft Graph.
  4. Select Application Permissions.
  5. Select theSites.Read.All option from the Application Permissions section.
  6. Click Grant admin consent for <Organization>, Yes.

The Sites.ReadAll permission should now be added to your application.

Next, you must generate a self-signed certificate. For more information, see Generate certificate.

Generate certificate

You must create a self-signed certificate. Use the script below. The script below will create two files:

  • mycert.pfx—use the .pfx file to upload to Relativity.
  • mycert.cer—use the .cer file to upload to the application in Azure.

The script creates a certificate that is valid for one year. After a year, you must replace this certificate with a new valid certificate.

To generate a self-signed certificate,

  1. Copy the following PowerShell script. For more information on creating a x.509 certificate, see Microsoft's documentation.
    2. Copy 
    # Create certificate
    $mycert = New-SelfSignedCertificate -DnsName "contoso.org" -CertStoreLocation "cert:\CurrentUser\My" -NotAfter (Get-Date).AddYears(1) -KeySpec KeyExchange
    # Export certificate to .pfx file
    $password = ConvertTo-SecureString "test" -AsPlainText -Force
    $mycert | Export-PfxCertificate -FilePath mycert.pfx -Password $password
    # Export certificate to .cer file
    $mycert | Export-Certificate -FilePath mycert.cer

    Note: You can also use a purchased or generated certificate from your organization.
  2. Replace the "contoso.org" value in the -DnsName "contoso.org" string with the matching the domain name in your Microsoft Entra admin center.
    Note: Relativity does not validate or need this value to be RelativityOne's Instance DNS.
  3. Replace the "test" value in the $password = ConvertTo-SecureString "test" string with a secure password.
  4. Run the script in Windows Powershell.
  5. On your application page, select Certificates & secrets.
  6. Click Upload certificate.

Assign application roles

To assign the required application roles,

  1. In the top-most search bar, enter Entra ID Roles and administrators.
  2. Select Compliance Administrator.
  3. Click the Add assignments button.
  4. Select the Preservation in-place app you created.
  5. Click Add.

You now have the Compliance Administrator Entra role assigned to the application. For information on roles, see Microsoft’s documentation.

You will use the information created for the next steps.

Run PowerShell script to create a Service Principal

After setting up an app in Entra ID in the Register the application section, you need to create a Service Principal to associate with the app.

You may need to install the AzureAD and ExchangeOnlineManagement modules.

To install the modules:

Copy 
Install-Module AzureAD
Import-Module AzureAd
Install-Module ExchangeOnlineManagement
Import-Module ExchangeOnlineManagement

To create the Service Principal and assign it to the application, you must have a Global Admin run the following PowerShell script.

Note: Use the copy button to copy the script.

Copy 
## 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
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 you created during app registration. For more information, see Register the application.
  • $appName—replace "AppNAME-FROM-Azure-AD" with the Application Name that you created during app registration. For more information, see Register the application.
  • $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.

Next, you can open Relativity and use the information to create the Microsoft 365 data source. For more information, see Creating the Microsoft 365 data source.

Creating the Microsoft 365 data source

Then create the Microsoft 365 data source in RelativityOne:

  1. Navigate to the Preservation Data Source tab.
  2. Click the New Preservation Data Source button.
  3. Enter in a unique name for the data source in the Name field.
  4. Select Microsoft 365 or Microsoft 365 Government data Source Type.
  5. Enter in the data source-specific fields for your select data source. For more information, see Preservation data source fields.
  6. Click Validate Credentials.
    Note: While the validation job is running, navigate to the Preservation Hold Jobs tab to see the status of the Validate Credentials job.
  7. Close the window the successful authentication window.
  8. Click the Re-Validate Authentication button in the right pane on the Preservation Data Source that you created. You should see the following status, “The user credentials are authenticated and ready to use.”

Preservation data source fields

In RelativityOne, you must add Microsoft 365-specific data into the fields in the Default Category during the creation of a Microsoft 365 data source.

  • Name—enter a unique name for this preservation data source.
  • Source Type—select a Microsoft 365 source.
  • Entity ID Field—select an entity type.
  • Client ID—enter your application's ID.
  • Certificate Password—enter the password that protects the private key of the certificate that you created in Register the application.
  • Certificate—add the self-signed certificate that you created in Register the application.
  • Tenant ID—enter the tenant ID created during registering the preservation application in Microsoft 365.
  • Domain—enter the domain name of the Microsoft 365 tenant the preservation is for.

Validate preservation hold credentials

After saving the credentials, 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.

On the Preservation Data Source page:

  1. Click into your Microsoft data source.
  2. Click the Validate Credentials button in the console.
    This will validate that modern authentication is configured correctly. It also creates, and then deletes, a sample preservation case in Microsoft Purview.
  1. 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.
  2. Once the validation is successful, you can set up preservation holds using the Legal Hold wizard. See Preservations.

You will get a pop-up window to authenticate into Microsoft with the admin login credentials.

Click the Re-validate Authentication button to update the status bar near the top of the page.

Data source details

Each data source details page includes a console to complete actions. Each data source has different actions.

For Microsoft 365:

  • Validate credentials—click to run a validation process with the client ID, certificate, and other credentials with Microsoft 365. You can see the result in the Validation Status field.
  • Re-validate authentication—click to refresh the status of the credentials. To validate credentials, you must click Validate credentials.

The Preservation data source layout for a Microsoft 365 data source.

Data services

On the data source details page, there is the Services section. In the Services section, you can click on a data source to see the service information.

For Microsoft OneDrive, you can overrid the entity field with the Entity OneDrive URL field.

Entity OneDrive URL field

The Sites.Read.All GraphAPI permission is required for automated look up of a custodian's OneDrive Site URL. If the preservation account cannot be granted the Sites.Read.All GraphAPI permission, then enter the Entity OneDrive URL field for each custodian so that automated look up is not required.

When the preservation account used for Microsoft 365 preservations does not have the Sites.Read.All GraphAPI permission the Entity OneDrive URL field is the alternative way to put a custodian's OneDrive source on a preservation hold. When the Entity SharePoint URL is provided, Relativity Legal Hold uses it to put a custodian's OneDrive content on a hold.

If the User Principal Name in your Entra ID account does not match the email address, you can use the Entity OneDrive URL field to put a custodian's OneDrive account on hold. Sharepoint Sites cannot be placed on Hold if the User Principal Name is different from Email in your Entra ID account.

If the Entity OneDrive URL field setting is empty, Legal Hold reverts to the original logic and queries SharePoint directly for this information.

Setting up Entity OneDrive URL field

An administrator needs to perform additional setup for this functionality to work. Use an existing field or create a new field on the entity object to host OneDrive URL information for each custodian. Use Integration Points or the Import/Export to populate this field with fully qualified OneDrive URL for each custodian.

Point Relativity to use such field as a reference to OneDrive URL information:

  1. Navigate to the Preservation Data Service tab.
  2. Click Edit.
  3. Click the Entity OneDrive URL field Select button.
  4. In the Select Items - Entity OneDrive Url Field modal, select an existing field that can contain OneDrive URL information. For example, select the Note field.
  5. Click Set.
  6. Enter each entity's OneDrive URL for their OneDrive site in the selected field. For example, enter https://company-my.sharepoint.com/personal/firstlast01_company_com in the OneDrive URL in the Note field.
  7. Click Save.