Microsoft 365 preservation source

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

Licenses

View the requirements for the Microsoft 365 commercial and Microsoft 365 Government.

Microsoft 365 commercial

  • All custodians must have a E3 license, or higher.

Microsoft 365 Government

  • All custodians must have a E3 license, or higher.

  • Tenants must have Office 365 GCC High service.

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 Sharepoint. Microsoft stores them in Group Mailboxes.
  • 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.

Accessing Microsoft 365 tenants

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

Preservation in-place is also set up to point at Government APIs instead of commercial APIs. 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.

Depending on your RelativityOne license, commercial or government, and your Microsoft tenant, Microsoft 365 or Microsoft 365 Government, you can preserve data from Microsoft 365 or both Microsoft 365 and Microsoft 365 Government. Commercial users can only preserve in Microsoft 365 tenants. Government users can use Legal Hold in Microsoft 365 and Government 365 tenants. These data sources have different icons within Preservation in-place.

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.

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

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

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

Assign API permissions

The API permissions you want to grant to your application are:

  • Sites.Read.All—this permission is needed to do OneDrive & SharePoint Discovery in Relativity.

  • Exchange.ManageAsApp—this permission is needed so that the application can run cmdlets in Exchange Online in each tenant organization. The Exchange.ManageAsApp permission is added when you update the manifest. For more information, see Modify the manifest.

To verify that you added the Exchange.ManageAsApp permission and add the Sites.ReadAll permission,

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

  3. Click Add a permission.
  4. Click Microsoft Graph.
  5. Select Application Permissions.
  6. Select theSites.Read.All option from the Application Permissions section.
  7. Click Grant admin consent for <Organization>, Yes.

Both permissions, Exchange.ManageAsApp and Sites.ReadAll, should now be added to your application.

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 "test" value in the $password = ConvertTo-SecureString "test" string with a secure password.
  3. Run the script in Windows Powershell.
  4. On your application page, select Certificates & secrets.
  5. Click Upload certificate.

Assign application roles

To assign the required application roles,

  1. Navigate to the Microsoft Entra roles and administrators page within the Services section.
  2. Select Compliance Administrator.
  3. Click the Add assignments button.
  4. Select the Preservation in-place app you created.
  5. Click Add.
  6. Select Exchange Administrator.
  7. Click the Add assignments button.
  8. Click Add.

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

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

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.

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

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. Select or sign into the account on which behalf preservations will be performed.
    If authentication is successful, a confirmation message appears.

  8. Close the window the successful authentication window.

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