Microsoft Purview eDiscovery V2

LAST UPDATED: OCTOBER 30, 2025

Overview

Microsoft Purview eDiscovery V2 (formerly known as Microsoft 365 eDiscovery) is a comprehensive solution designed to help organizations locate, preserve, collect, and review electronically stored information (ESI) for compliance, legal, and investigative purposes. It is part of Microsoft's Purview suite of tools, which provide security, compliance, and risk management for organizations using Microsoft 365. This integration works with Microsoft Purview eDiscovery (Premium).

D3 SOAR is providing REST operations to function with Microsoft Purview eDiscovery V2.

Microsoft Purview eDiscovery V2 is available for use in:

Connection

Gather the following information to connect D3 SOAR to Microsoft Purview eDiscovery V2.

READER NOTE

The prerequisite for using this guide is access to eDiscovery (Premium).

Refer to Use the Microsoft Purview eDiscovery API for more information.

Permission Requirements

Each endpoint in the Microsoft Purview eDiscovery V2 API requires a certain permission scope. The following are required scopes for the commands in this integration:

READER NOTE

• All API permissions must be granted admin consent on the Azure Portal.

• Purview Roles refer to individual permission sets that form the basis of built-in and custom role groups.

• When using application permissions, assign the role group to the service principal using PowerShell, not through the UI.

  • After assigning the service principal through PowerShell, the assignment will be visible in the Microsoft Purview UI.

    

    Although the Type column lists the value as User, the entry represents a service principal.

• Users can access and modify only the cases they own. To grant permission to manage all cases, add them to the built-in eDiscovery Administrator sub-group.

Configuring Microsoft Purview eDiscovery V2 to Work with D3 SOAR

Setting up the Microsoft Purview eDiscovery v2 integration with D3 involves several key steps. The process varies slightly depending on whether Delegated (Grant Type: Authorization Code) or Application (Grant Type: Client Credentials) permissions are used.

The table below compares the configuration steps required for Delegated and Application permissions.

Users should review the detailed instructions below carefully to ensure successful execution of commands in this integration.

Creating a Custom Role Group in Microsoft Purview

PREREQUISITES

To create or manage role groups in Microsoft Purview, users must sign in with an account assigned to a role group with the Role Management role.

To view Roles and scopes > Role groups in Microsoft Purview, use an account assigned to the built-in Organization Management role group (refer to Permissions in the Microsoft Purview portal for details). This group includes the Role Management role, among others, which allows users to:

• Create custom, least-privilege role groups that provide the granular access required to run the commands in this integration.

• Successfully execute the PowerShell steps when using application permissions.

1. Create a custom role group.

   

   1. Navigate to the Settings page.

   2. Open the Role and Scopes accordion.

   3. Click the Role groups option.

   4. Click the + Create role group button.

2. Enter a descriptive name for the role group and click the Next button.

   

3. Click the Choose roles button, then select the appropriate roles according to the Permission Requirements table.

   

4. Click the Next button.

   

5. (Delegated permissions only) Assign the user account associated with the D3 connection to the custom role group.

   

   1. Click the Choose users button.

   2. Search for and select the appropriate user to be used for the D3 connection.

   3. Click the Select button.

6. Click the Next button, then click the Create button.

   

READER NOTE

Users in the Organization Management role group can optionally create a custom role group that includes the Role Management role to:

• Delegate the ability to create and manage role groups.

• Allow another user to perform the PowerShell steps for application permissions if that user does not already belong to a role group that includes the Role Management role.

WARNING

If authenticating with application permissions, do not assign the service principal associated with the D3 connection to the custom role group through the Microsoft Purview UI, even if it appears selectable. This assignment must be completed later using PowerShell. Assigning it at this stage can cause errors.

Registering an Azure App and Collecting Credentials

1. Log into Azure portal using the credentials of the user to be associated with the D3 connection.

   

2. Register a new application.

   

   1. Search for and select the App registrations option.

   2. Click the + New registration button.

   3. Enter a unique name and select a supported account type.

   4. (Delegated permissions only) Paste the callback URL from vSOC.

      Refer to 3.i.7 in Configuring D3 SOAR to Work with Microsoft Purview eDiscovery V2.

   5. Click the Register button.

3. Copy the Tenant ID and Client ID. Refer to 3.i.1 and 3.i.3 in Configuring D3 SOAR to Work with Microsoft Purview eDiscovery V2.

   

4. Create the Client Secret.

   

   1. Navigate to the Certificates & secrets tab.

   2. Click the + New client secret button.

   3. Add a description and configure the expiry time.

   4. Click the Add button.

5. Save the client secret Value in a secure location. Refer to 3.i.4 in Configuring D3 SOAR to Work with Microsoft Purview eDiscovery V2.

After leaving this page, the client secret value will no longer be accessible.

Granting API Permissions

1. Navigate to the API permissions tab, click the + Add a permission button, then select the Microsoft Graph option.

   

2. Add the necessary delegated or application permissions.

   

3. Click the Add permissions button, then click the Grant admin consent for <tenant-name> button on the API Permissions page.

   

READER NOTE

Only privileged role administrators (e.g., Global Administrator or Privileged Role Administrators) can grant admin consent.

Setting Up a Service Principal Using PowerShell

This section applies only to users who are authenticating using application permissions.

1. Navigate to Enterprise applications, then search for and select the registered app.

   

2. Copy and save the following values in a secure location:

   

   1. Application display name

   2. Application ID

   3. Object ID (ID of the service principal)

   IMPORTANT It is essential that users obtain the Object ID from Enterprise applications and not App registrations, as the two values represent different objects. The Object ID in Enterprise applications refers to the service principal, while the one in App registrations refers to the application object.

   

3. Copy the following PowerShell cmdlets to a text editor, then replace each placeholder in angle brackets (<...>) with the appropriate values.

   POWERSHELL

   $AppId     = "<paste-the-application-id>"
   $ObjectId  = "<paste-the-object-id>" 
   $DisplayName   = "<enter-the-application-display-name>"
   
   Install-Module -Name ExchangeOnlineManagement 
   Import-Module ExchangeOnlineManagement
   Connect-IPPSSession
   
   # Creates a new Service Principal (SP)
   New-ServicePrincipal -AppId $AppId -ObjectId $ObjectId -DisplayName $DisplayName
   
   # Verifies the SP creation
   Get-ServicePrincipal | Where-Object { $_.AppId -eq $AppId -or $_.Id -eq $ObjectId }
   
   # Assigns the SP to the custom role group
   Add-RoleGroupMember -Identity "<custom-role-group-name>" -Member $DisplayName
   
   # Verifies the SP's membership
   Get-RoleGroupMember -Identity "<custom-role-group-name>" | Where-Object { $_.Name -eq $DisplayName }

   • $AppId: Paste the Application ID from the previous step.

   • $ObjectId: Paste the Object ID from the previous step.

   • $DisplayName = Paste the application Name from the previous step.

   • <custom-role-group-name>: Enter the custom role group name exactly as it appears in the Microsoft Purview UI.

     Refer to step 2 of Creating a Custom Role Group in Microsoft Purview.

4. (Optional) Replace lines 15 to 19 in the previous snippet (starting at the comment "# Assigns the SP…" and ending with the line that finishes with "-eq $DisplayName)" with the following code to assign the authenticated user to the eDiscovery Administrator sub-group, and then confirm their role membership.

   POWERSHELL

   # Assigns the SP to the eDiscovery Administrator sub-group
   Add-eDiscoveryCaseAdmin -User $ObjectId
   
   # Verifies the SP's membership
   Get-eDiscoveryCaseAdmin | Where-Object { $_.Name -eq $ObjectId }

   eDiscovery Administrators can manage all cases.

5. Run Windows PowerShell as an administrator.

   

6. Paste the code snippet from Step 3 into PowerShell and execute it.

   

7. Log in when the Azure pop-up window appears, then wait for the cmdlets to complete execution.

   

   If a different account is used from the one that performed the steps in Creating a Custom Role Group in Microsoft Purview, ensure that the signed-in user in this step belongs to a role group that includes the Role Management role.

8. Confirm that the service principal is now assigned to the custom role group in Microsoft Purview.

   

   If an error occurs while adding the service principal to the custom role group, users can troubleshoot by executing these cmdlets from Step 3 one line at a time:

   POWERSHELL

   Add-RoleGroupMember -Identity "<custom-role-group-name>" -Member $DisplayName
   
   Get-RoleGroupMember -Identity "<custom-role-group-name>" | Where-Object { $_.Name -eq $DisplayName }

READER NOTE

To log in as another Azure user in PowerShell, first run Disconnect-ExchangeOnline -Confirm:$false 2>$null to end the current session, then run Connect-IPPSSession to initiate a new login.

EXAMPLE

POWERSHELL

Disconnect-ExchangeOnline -Confirm:$false 2>$null
Connect-IPPSSession

Configuring D3 SOAR to Work with Microsoft Purview eDiscovery V2

1. Log in to D3 SOAR.

2. Find the Microsoft Purview eDiscovery V2 integration.

   

   1. Navigate to Configuration on the top header menu.

   2. Click on the Integration icon on the left sidebar.

   3. Type Microsoft Purview eDiscovery V2 in the search box to find the integration, then click it to select it.

   4. Click on the + Connection button on the right side of the Connections section. A new connection window will appear.

3. Configure the following fields to create a connection to Microsoft Purview eDiscovery V2.

   

   1. Connection Name: The desired name for the connection.

   2. Site: The site on which to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.

   3. Recipient site for events from connections Shared to Internal Sites: This field is displayed when Share to Internal Sites is selected for the Site field, allowing selection of the internal site for deploying the integration connection.

   4. Agent Name (Optional): The proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.

   5. Description (Optional): The description for the connection.

   6. Tenant (Optional): When configuring the connection from a master tenant site, users can choose the specific tenant sites with which to share the connection. Once this setting is enabled, users can filter and select the desired tenant sites from the dropdowns to share the connection.

      

   7. Configure User Permissions: Defines which users have access to the connection.

   8. Active: The checkbox that enables the connection to be used when selected.

   9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.

      Grant Type: Client Credentials

      

      Use the Client Credentials grant type when authenticating with application permissions.

      1. Input the Tenant ID. Refer to step 3 of Registering an Azure App and Collecting Credentials.

      2. Select the Grant Type.

      3. Input the Client ID. Refer to step 3 of Registering an Azure App and Collecting Credentials.

      4. Input the Client Secret. Refer to step 5 of Registering an Azure App and Collecting Credentials.

      5. Input the API Version. The default value is v1.0.

      Grant Type: Authorization Code

      

      Use the Authorization Code grant type when authenticating with delegated permissions. For this grant type, complete the same steps required for Grant Type: Client Credentials, plus the following additional steps.

      6. Click Get Authorization to automatically retrieve the authorization code and populate the field.

      7. Copy the Callback URL. Refer to step 2d in Registering an Azure App and Collecting Credentials.

      8. Click the Get Refresh Token button.

   10. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Refer to the password vault connection guide if needed.

   11. Connection Health Check: Periodically checks the connection status by scheduling the Test Connection command at the specified interval (in minutes). Available only for active connections, this feature also allows configuring email notifications for failed attempts.

4. Test the connection.

   

   1. Click on the Test Connection button to verify credentials and connectivity. A success alert displays Passed with a green checkmark. If the connection fails, review the parameters and retry.

   2. Click OK to close the alert window.

   3. Click + Add to create and add the configured connection.

Commands

Microsoft Purview eDiscovery V2 includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command function, users can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the Microsoft Purview eDiscovery V2 API, refer to the Microsoft Purview eDiscovery V2 API reference.

READER NOTE

Certain permissions are required for each command. Refer to the Permission Requirements and Configuring Microsoft Purview eDiscovery V2 to Work with D3 SOAR sections for details.

Note for Time-related parameters

The input format of time-related parameters may vary based on user account settings, which may cause the sample data in commands to differ from what is displayed. To adjust the time format, follow these steps:

1. Navigate to Configuration > Application Settings. Select Date/Time Format.

   

2. Choose the desired date and time format, then click on the Save button.

   

The selected time format will now be visible when configuring Date/Time command input parameters.

Create Case

Creates a new eDiscovery Case object.

Input

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Create eDiscovery Email Search

Creates a new eDiscovery Search object within a specified eDiscovery case to search emails based on a content query. This command is often paired with the Purge Emails command to identify messages for removal. Ensure to narrow the search with parameters, as broad queries can result in errors when Purge Email is executed.

READER NOTE

Case ID is a required parameter to run this command.

• Run the List eDiscovery Cases command to obtain the Case ID. Case IDs can be found in the raw data at $.value[*].id.

Input

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

List eDiscovery Cases

Retrieves a list of eDiscovery case objects and their properties.

Input

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Purge Emails

Deletes Exchange mailbox items returned in a specified eDiscovery search result. A maximum of 100 email items per mailbox can be purged at once. Carefully review the eDiscovery search results before running this command.

READER NOTE

Case ID and Search ID are required parameters to run this command.

• Run the Create eDiscovery Email Search command to obtain the Case ID and Search ID. Case IDs and Search IDs can be found in the raw data at:

  • $.CaseID (Case ID)

  • $.SearchID (Search ID)

Input

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Test Connection

Allows users to perform a health check on an integration connection. Users can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.