AzureFeeds

The Microsoft Purview APIs for eDiscovery in Microsoft Graph enable organizations to automate repetitive tasks and integrate with their existing eDiscovery tools to build repeatable workflows that industry regulations might require.

Before you can make any calls to the Microsoft Purview APIs for eDiscovery you must first register an app in the Microsoft’s Identity Platform, Entra ID.

An app can access data in two ways:

• Delegated Access: an app acting on behalf of a signed-in user


• App-only access: an app action with its own identity

For more information on access scenarios see Authentication and authorization basics.

This article will demonstrate how to configure the required pre-requisites to enable access to the Microsoft Purview APIs for eDiscovery. This will based on using app-only access to the APIs, using either a client secret or a self-signed certificate to authenticate the requests.

The Microsoft Purview APIs for eDiscovery have two separate APIs, they are:

• Microsoft Graph: Part of the Microsoft.Graph.Security namespace and used for working with Microsoft Purview eDiscovery Cases.


• MicrosoftPurviewEDiscovery: Used exclusively to download programmatically the export package created by a Microsoft Purview eDiscovery Export job.

Currently, the eDiscovery APIs in Microsoft Graph only work with eDiscovery (Premium) cases.

For a list of supported API calls within the Microsoft Graph calls, see Use the Microsoft Purview eDiscovery API.

Microsoft Graph API

Pre-requisites

Implementing app-only access involves registering an app in Azure portal, creating client secret/certificates, assigning API permissions, setting up a service principal, and then using app-only access to call Microsoft Graph APIs.

To register an app, create client secret/certificates and assign API permissions the account must be at least a Cloud Application Administrator.

For more information on registering an app in the Azure portal, see Register an application with the Microsoft identity platform.

Granting tenant-wide admin consent for Microsoft Purview eDiscovery API application permissions requires you to sign in as a user that is authorized to consent on behalf of the organization, see Grant tenant-wide admin consent to an application.

Setting up a service principal requires the following pre-requisites:

• A machine with the ExchangeOnlineManagement module installed


• An account that has the Role Management role assigned in Microsoft Purview, see Roles and role groups in Microsoft Defender for Office 365 and Microsoft Purview

Configuration steps

For detailed steps on implementing app-only access for Microsoft Purview eDiscovery, see Set up app-only access for Microsoft Purview eDiscovery.

Connecting to Microsoft Graph API using app-only access

Use the Connect-MgGraph cmdlet in PowerShell to authenticate and connect to Microsoft Graph using the app-only access method. This cmdlets enables your app to interact with Microsoft Graph securely and enables you to explore the Microsoft Purview eDiscovery APIs.

Connecting via client secret

To connect using a client secret, update and run the following example PowerShell code.

$clientSecret = “” ## Update with client secret added to the registered app
$appID = “” ## Update with Application ID of registered/Enterprise app
$tenantId = “” ## Update with tenant ID
$ClientSecretPW = ConvertTo-SecureString “$clientSecret” -AsPlainText -Force
$clientSecretCred = New-Object System.Management.Automation.PSCredential -ArgumentList (“$appID”, $clientSecretPW)
Connect-MgGraph -TenantId “$tenantId” -ClientSecretCredential $clientSecretCred

Connecting via certificate

To connect using a certificate, update and run the following example PowerShell code.

$certPath = “Cert:currentusermy” ## Update with the cert thumbnail
$appID = “” ## Update with Application ID of registered/Enterprise app
$tenantId = “” ## Update with tenant ID
$ClientCert = Get-ChildItem $certPath
Connect-MgGraph -TenantId $TenantId -ClientId $appId -Certificate $ClientCert

Invoke Microsoft Graph API calls

Once connected you can start making calls to the Microsoft Graph API.

For example, lets look at listing the eDiscovery cases within the tenant, see List ediscoveryCases.

Within the documentation, for each operation it will list the following information:

• Permissions required to make the API call


• HTTP request and method


• Request header and body information


• Response


• Examples (HTTP, C#, CLI, Go, Java, PHP, PowerShell, Python)

As we are connected via the Microsoft Graph PowerShell module we can either use the HTTP or the eDiscovery specific cmdlets within the Microsoft Graph PowerShell module.

First let’s look at the PowerShell cmdlet example.

Figure 1: PowerShell command output of the Get-MgSecurityCaseEdiscoveryCase cmdlet displaying a list of eDiscovery cases with their creation dates, descriptions, display names, and IDs

As you can see it returns a list of all the cases within the tenant. When delving deeper into a case it is important to record the Case ID as you will use this in future calls.

Then we can look at the HTTP example, we will use the Invoke-MgGraphRequest cmdlet to make the call via PowerShell.

First we need to store the URL in a variable as below.

$uri = “https://graph.microsoft.com/v1.0/security/cases/ediscoveryCases”

Then we will use the Invoke-MgGraphRequest cmdlet to make the API call.

Invoke-MgGraphRequest -Method Get -Uri $uri

As you can see from the output below, we need to extract the values from the returned response.

Figure 2: PowerShell command output displaying the returned response from the REST API call using the Invoke-MgGraphRequest cmdlet.

This can be done by saving the Value elements of the response to a new variable using the following command.

$cases = (Invoke-MgGraphRequest -Method Get -Uri $uri).valueFigure 3: PowerShell command output displaying the number of cases returned by the Rest API call using the Invoke-MgGraphRequest cmdlet. It shows that the returned data is a Hashtable PowerShell object type and it shows the list of eDiscovery cases. Demonstrating more transformation work is required to make the returned cases easier to work with in PowerShell.

This returns a collection of Hashtables; optionally you can run a small bit of PowerShell code to convert the hash tables into PS Objects for easier use with cmdlets such as format-table and format-list.

$CasesAsObjects = @()
foreach($i in $cases) {$CasesAsObjects += [pscustomobject]$i}Figure 4: PowerShell command output displaying the transformed results of the REST API call. Demonstrating how the Format-Table cmdlet can be used to create a table of eDiscovery cases listing their name, ID and case status.

MicrosoftPurviewEDiscovery API

You can also configure the MicrosoftPurviewEDiscovery API to enable the programmatic download of export packages and the item report from an export job in a Microsoft Purview eDiscovery case.

Pre-requisites

Prior to executing the configuration steps in this section it is assumed that you have completed and validated the configuration detailed in the Microsoft Graph API section. The previously registered app in Entra ID will be extended to include the required permissions to achieve programmatic download of the export package. This already provides the following pre-requisites:

• Registered App in Azure portal configured with the appropriate client secret/certificate


• Service principal in Microsoft Purview assigned the relevant eDiscovery roles


• Microsoft eDiscovery API permissions configured for the Microsoft Graph

To extend the existing registered apps API permissions to enable programmatic download, the following steps must be completed

• Registering a new Microsoft Application and service principal in the tenant


• Assign additional API permissions to the previously registered app in the Azure Portal

Granting tenant-wide admin consent for Microsoft Purview eDiscovery APIs application permissions requires you to sign in as a user that is authorized to consent on behalf of the organization, see Grant tenant-wide admin consent to an application.

Configuration steps

Step 1 – Register the MicrosoftPurviewEDiscovery app in Entra ID

First validate that the MicrosoftPurviewEDiscovery app is not already registered by logging into the Azure Portal and browsing to Microsoft Entra ID > Enterprise Applications.

Figure 5: The Enterprise Applications blade in the Microsoft Azure, listing various applications with their name, object IDs, application IDs, and homepage URLs.

Change the application type filter to show Microsoft Applications and in the search box enter MicrosoftPurviewEDiscovery. If this returns a result as below, move to step 2.

Figure 6: Enterprise applications blade in the Microsoft Azure portal showing a single application named ‘MicrosoftPurviewEDiscovery’ when searching for it.

If the search returns no results as per the example below, proceed with registering the app in Entra ID.

Figure 7: Enterprise applications blade in the Microsoft Azure portal showing no results found when searching for the ‘MicrosoftPurviewEDiscovery’ Enterprise Application.

The Microsoft.Graph PowerShell Module can be used to register the MicrosoftPurviewEDiscovery App in Entra ID, see Install the Microsoft Graph PowerShell SDK.

Once installed on a machine, run the following cmdlet to connect to the Microsoft Graph via PowerShell.

Connect-MgGraph -scopes “Application.ReadWrite.All”

If this is the first time using the Microsoft.Graph PowerShell cmdlets you may be prompted to consent to the following permissions.

Figure 8: Example of the admin consent dialog box showing the Microsoft Graph Command Line Tools requesting consent for various permissions, including reading and writing applications, viewing your basic profile, and maintaining access to data

To register the MicrosoftPurviewEDiscovery app, run the following PowerShell commands.

$spId = @{“AppId” = “b26e684c-5068-4120-a679-64a5d2c909d9” }
New-MgServicePrincipal -BodyParameter $spId;Figure 9: PowerShell command output showing the New-MgServicePrincipal cmdlet being executed and the returned results.

Step 2 – Assign additional MicrosoftPurviewEDiscovery permissions to the registered app

Now that the Service Principal has been added you can update the permissions on your previously registered app created in the Microsoft Graph API section of this document. Log into the Azure Portal and browse to Microsoft Entra ID > App Registrations.

Find and select the app you created in the Microsoft Graph API section of this document. Select API Permissions from the navigation menu.

Figure 10: Overview of the “eDiscovery App Auth” registered app in the Microsoft Azure Portal. Showing information such as the Object ID, Application ID and Display name of the app.

 

Figure 11: Overview of the API permissions assigned to the “eDiscovery App Auth” registered app in the Microsoft Azure Portal. Showing that the eDiscovery.Read.All, eDiscovery.ReadWrite.All and User.Read Microsoft Graph API permissions have been added and admin consent granted.

Select Add a permission and then APIs my organization uses. Search for MicrosoftPurviewEDiscovery and select it.

Figure 12: Request API permissions dialogue box showing the “APIs my organization uses” being searched for the MicrosoftPurviewEDiscovery APIs and returning the relevant API.

Then select Application Permissions and select the tick box for eDiscovery.Download.Read before selecting Add Permissions.

Figure 13: Request API permissions dialogue box showing the eDiscovery.Download.Read application permission for the MicrosoftPurviewEDiscovery API selected as well as the “Add permissions” and “Discard” buttons.

You will be returned to the API permissions screen, now you must select Grant Admin Consent.. to approve the newly added permissions.

Figure 14: Overview of the API permissions assigned to the “eDiscovery App Auth” registered app in the Microsoft Azure Portal. Showing that the eDiscovery.Read.All, eDiscovery.ReadWrite.All and User.Read Microsoft Graph API permissions have been added and admin consent granted. It also shows that the eDiscovery.Download.Read MicrosoftPurviewEDiscovery API application permissions have been added but admin consent has not yet been granted.

Once admin consent is granted you will see the Status of the newly added permissions update to Granted for...

Figure 15: Overview of the API permissions assigned to the “eDiscovery App Auth” registered app in the Microsoft Azure Portal. Showing that the eDiscovery.Read.All, eDiscovery.ReadWrite.All and User.Read Microsoft Graph API permissions have been added and admin consent granted. It also shows that the eDiscovery.Download.Read MicrosoftPurviewEDiscovery API application permissions have been added and admin consent granted.

Downloading the export packages and reports

Retrieving the case ID and export Job ID

To successfully download the export packages and reports of an export job in an eDiscovery case, you must first retrieve the case ID and the operation/job ID for the export job.

To gather this information via the Purview Portal you can open the eDiscovery Case, locate the export job and select Copy support information before pasting this information into Notepad.

Figure 16: An eDiscovery case is opened within the Microsoft Purview Portal and an Export Job is selected. The flyout on the right hand side shows the Export Job details, packages and also shows the “Copy support information” button.Figure 17: Notepad opened with the pasted support information within it. Contains information such as the tenant ID, case ID, job ID, job state, created by, created timestamp, completed timestamp and support information generation time.

To access this information programmatically you can make the following Graph API calls to locate the case ID and the job ID you wish to export.

First connect to the Microsoft Graph using the steps detailed in the previous section titled “Connecting to Microsoft Graph API using app-only access”

Figure 18: PowerShell command output showing the commands to connect to the Microsoft Graph API using app-only access.

Using the eDiscovery Graph PowerShell Cmdlets you can use the following command if you know the case name.

Get-MgSecurityCaseEdiscoveryCase | where {$_.displayname -eq “”}Figure 19: PowerShell command output showing the eDiscovery case ‘HK001 – OneDrive Testing’. Displays the created date time, description, display name, Id, last modified date time, status, closed date time and external id for the case.

Once you have the case ID you can look up the operations in the case to identify the job ID for the export using the following command.

Get-MgSecurityCaseEdiscoveryCaseOperation -EdiscoveryCaseId “”Figure 20: PowerShell command output showing the operations for the eDiscovery case ‘HK001 – OneDrive Testing’. Displays the Id, Action, Completed Date Time, Created Date Time, Percent Progress and Status of each operation in the case.

Export jobs will either be logged under an action of exportResult (direct export) or ContentExport (export from review set).

The name of the export jobs are not returned by this API call, to find the name of the export job you must query the specific operation ID. This can be achieved using the following command.

Get-MgSecurityCaseEdiscoveryCaseOperation -EdiscoveryCaseId “” -CaseOperationId “”Figure 20: PowerShell command output showing a specified operation from the eDiscovery case ‘HK001 – OneDrive Testing’. Displays the Id, Action, Completed Date Time, Created Date Time, Percent Progress, Results Info, Additional Properties and Status for the operation.

The name of the export operation is contained within the property AdditionalProperties.

Figure 21: PowerShell command output showing two ways to access the AdditionalProperties property of an export job to discover the name of the export job.

If you wish to make the HTTP API calls directly to list cases in the tenant, see List ediscoveryCases – Microsoft Graph v1.0 | Microsoft Learn.

Figure 22: PowerShell command output showing how to make the direct REST API call using the Invoke-MgGraphRequest cmdlet before transforming the returned results into PS Custom Objects to make it easier to locate a specific case based on the case name.

If you wish to make the HTTP API calls directly to list the operations for a case, see List caseOperations – Microsoft Graph v1.0 | Microsoft Learn.

You will need to use the Case ID in the API call to indicate which case you wish to list the operations from. For example:

https://graph.microsoft.com/v1.0/security/cases/ediscoveryCases//operations/

Figure 23: PowerShell command output showing how to make the direct REST API call using the Invoke-MgGraphRequest cmdlet to return a list of operations associated with a specific eDiscovery case.

The name of the export jobs are not returned with this API call, to find the name of the export job you must query the specific job ID. For example:

https://graph.microsoft.com/v1.0/security/cases/ediscoveryCases//operations/

Figure 24: PowerShell command output showing how to make the direct REST API call to return the information about a specific operation in an eDiscovery cases using the Invoke-MgGraphRequest cmdlet. Information of the operation is displayed such as Id, status, action, name and created date time is shown.

Downloading the Export Package

Retrieving the download URLs for export packages

The URL required to download the export packages and reports are contained within a property called exportFileMetaData. To retrieve this information we need to know the case ID of the eDiscovery case that the export job was run in, as well as the operation ID for the export job.

Using the eDiscovery Graph PowerShell Cmdlets you can retrieve this property use the following commands.

$Operation = Get-MgSecurityCaseEdiscoveryCaseOperation -EdiscoveryCaseId “” -CaseOperationId “”
$Operation.AdditionalProperties.exportFileMetadataFigure 25: PowerShell command output showing the exportFileMetadata data from the AdditionalProperties property for an export operation within a case from the Get-MgSecurityCaseEdiscoveryCaseOperation cmdlet. Information such as the file name, size and download URL is shown for each export package.

If you wish to make the HTTP API calls directly to return the exportFileMetaData for an operation, see List caseOperations – Microsoft Graph v1.0 | Microsoft Learn.

Figure 26: PowerShell command output showing the exportFileMetadata data for an export operation within a case when using the direct REST API call with the Invoke-MgGraphRequest cmdlet. Information such as the file name, size and download URL is shown for each export package.

For each export package visible in the Microsoft Purview Portal there will be an entry in the exportFileMetaData property. Each entry will list the following:

• The export package file name


• The downloadUrl to retrieve the export package


• The size of the export package

Figure 27: Image of the export job information and export packages from the Purview Portal.Figure 28: PowerShell command output showing the same export packages shown in the Purview Portal from Figure 27 by selecting each individual entry from the exportFileMetadata property of the operation.

Example scripts to download the Export Package

As the MicrosoftPurviewEDiscovery API is separate to the Microsoft Graph API, it requires a separate authentication token to authorise the download request. As a result, you must use the MSAL.PS PowerShell Module and the Get-MSALToken cmdlet to acquire a separate token in addition to connecting to the Microsoft Graph APIs via the Connect-MgGraph cmdlet.

The following example scripts can be used to as a reference when developing your own scripts to enable the programmatic download of the export packages.

Connecting with a client secret

If you have configured your app to use a client secret, then you can use the following example script for reference to download the export package and reports programmatically. Copy the contents into notepad and save it as DownloadExportUsingApp.ps1.

[CmdletBinding()]
param (
[Parameter(Mandatory = $true)]
[string]$tenantId,
[Parameter(Mandatory = $true)]
[string]$appId,
[Parameter(Mandatory = $true)]
[string]$appSecret,
[Parameter(Mandatory = $true)]
[string]$caseId,
[Parameter(Mandatory = $true)]
[string]$exportId,
[Parameter(Mandatory = $true)]
[string]$path = “D:Temp”,
[ValidateSet($null, ‘USGov’, ‘USGovDoD’)]
[string]$environment = $null
)

if (-not(Get-Module -Name Microsoft.Graph -ListAvailable)) {
Write-Host “Installing Microsoft.Graph module”
Install-Module Microsoft.Graph -Scope CurrentUser
}

if (-not(Get-Module -Name MSAL.PS -ListAvailable)) {
Write-Host “Installing MSAL.PS module”
Install-Module MSAL.PS -Scope CurrentUser
}

$password = ConvertTo-SecureString $appSecret -AsPlainText -Force
$clientSecretCred = New-Object System.Management.Automation.PSCredential -ArgumentList ($appId, $password)

if (-not(Get-MgContext)) {
Write-Host “Connect with credentials of a ediscovery admin (token for graph)”
if (-not($environment)) {
Connect-MgGraph -TenantId $TenantId -ClientSecretCredential $clientSecretCred
}
else {
Connect-MgGraph -TenantId $TenantId -ClientSecretCredential $clientSecretCred -Environment $environment
}
}

Write-Host “Connect with credentials of a ediscovery admin (token for export)”
$exportToken = Get-MsalToken -ClientId $appId -Scopes “b26e684c-5068-4120-a679-64a5d2c909d9/.default” -TenantId $tenantId -RedirectUri “http://localhost” -ClientSecret $password

$uri = “/v1.0/security/cases/ediscoveryCases/$($caseId)/operations/$($exportId)”

$export = Invoke-MgGraphRequest -Uri $uri;
if (-not($export)){
Write-Host “Export not found”
exit
}
else{
$export.exportFileMetadata | % {
Write-Host “Downloading $($_.fileName)”
Invoke-WebRequest -Uri $_.downloadUrl -OutFile “$($path)$($_.fileName)” -Headers @{“Authorization” = “Bearer $($exportToken.AccessToken)”; “X-AllowWithAADToken” = “true” }
}
}

Once saved, open a new PowerShell windows which has the following PowerShell Modules installed:

• Microsoft.Graph


• MSAL.PS

Browse to the directory you have saved the script and issue the following command.

.DownloadExportUsingApp.ps1 -tenantId “” -appId “” -appSecret “” -caseId “” -exportId “” -path “”Figure 29: PowerShell command output showing the results of running the DownloadExportUsingApp.ps1 script to download the export packages from an export job to the c:ediscoapi folder. It shows two export packages being downloaded.

Review the folder which you have specified as the Path to view the downloaded files.

Figure 30: View of the c:ediscoapi folder in Windows Explorer showing that two export packages have been successfully downloaded.

Connecting with a certificate

If you have configured your app to use a certificate then you can use the following example script for reference to download the export package and reports programmatically. Copy the contents into notepad and save it as DownloadExportUsingAppCert.ps1.

[CmdletBinding()]
param (
[Parameter(Mandatory = $true)]
[string]$tenantId,
[Parameter(Mandatory = $true)]
[string]$appId,
[Parameter(Mandatory = $true)]
[String]$certPath,
[Parameter(Mandatory = $true)]
[string]$caseId,
[Parameter(Mandatory = $true)]
[string]$exportId,
[Parameter(Mandatory = $true)]
[string]$path = “D:Temp”,
[ValidateSet($null, ‘USGov’, ‘USGovDoD’)]
[string]$environment = $null
)

if (-not(Get-Module -Name Microsoft.Graph -ListAvailable)) {
Write-Host “Installing Microsoft.Graph module”
Install-Module Microsoft.Graph -Scope CurrentUser
}

if (-not(Get-Module -Name MSAL.PS -ListAvailable)) {
Write-Host “Installing MSAL.PS module”
Install-Module MSAL.PS -Scope CurrentUser
}

##$password = ConvertTo-SecureString $appSecret -AsPlainText -Force
##$clientSecretCred = New-Object System.Management.Automation.PSCredential -ArgumentList ($appId, $password)

$ClientCert = Get-ChildItem $certPath

if (-not(Get-MgContext)) {
Write-Host “Connect with credentials of a ediscovery admin (token for graph)”
if (-not($environment)) {
Connect-MgGraph -TenantId $TenantId -ClientId $appId -Certificate $ClientCert
}
else {
Connect-MgGraph -TenantId $TenantId -ClientId $appId -Certificate $ClientCert -Environment $environment
}
}

Write-Host “Connect with credentials of a ediscovery admin (token for export)”

$connectionDetails = @{
‘TenantId’ = $tenantId
‘ClientId’ = $appID
‘ClientCertificate’ = $ClientCert
‘Scope’ = “b26e684c-5068-4120-a679-64a5d2c909d9/.default”
}

$exportToken = Get-MsalToken @connectionDetails

$uri = “/v1.0/security/cases/ediscoveryCases/$($caseId)/operations/$($exportId)”

$export = Invoke-MgGraphRequest -Uri $uri;
if (-not($export)){
Write-Host “Export not found”
exit
}
else{
$export.exportFileMetadata | % {
Write-Host “Downloading $($_.fileName)”
Invoke-WebRequest -Uri $_.downloadUrl -OutFile “$($path)$($_.fileName)” -Headers @{“Authorization” = “Bearer $($exportToken.AccessToken)”; “X-AllowWithAADToken” = “true” }
}
}

Once saved open a new PowerShell windows which has the following PowerShell Modules installed:

• Microsoft.Graph


• MSAL.PS

Browse to the directory you have saved the script and issue the following command.

.DownloadExportUsingAppCert.ps1 -tenantId “” -appId “” -certPath “” -caseId “” -exportId “” -path “”Figure 31: PowerShell command output showing the results of running the DownloadExportUsingAppCert.ps1 script to download the export packages from an export job to the c:ediscoapitest folder. It shows two export packages being downloaded.

Review the folder which you have specified as the Path to view the downloaded files.

Figure 32: View of the c:ediscoapitest folder in Windows Explorer showing that two export packages have been successfully downloaded.

Conclusion

Congratulations you have now configured your environment to enable access to the eDiscovery APIs! It is a great opportunity to further explore the available Microsoft Purview eDiscovery REST API calls using the Microsoft.Graph PowerShell module.

For a full list of API calls available, see Use the Microsoft Purview eDiscovery API.

Stay tuned for future blog posts covering other aspects of the eDiscovery APIs and examples on how it can be used to automate existing eDiscovery workflows.