Manage eDiscovery Cases with Background Processes
After writing about how to manage Purview eDiscovery cases with PowerShell, a reader noted that I reported working in an interactive session and asked if there was a way to use apps to manage eDiscovery cases. The idea is to handle long-running tasks like adding hundreds or thousands of mailboxes as data sources for searches in a background process.
My initial reaction was negative. Although Graph application permissions are available, Purview uses its own role groups to control access to its solutions, and there didn’t seem to be any way to add an Entra ID app to a role group in the same way as you can add the service principal for an app to an Entra ID administrative role. A chat with Microsoft revealed that I was wrong. I was directed to an article explaining how to setup app-only access for Purview eDiscovery.
Connecting the Dots
The key point in the description is the use of an Exchange Online service principal to allow an app to become a member of the Purview eDiscovery Managers role group. An Exchange Online service principal that’s used to make a link to an Entra ID service principal. Another example of the use of an Exchange service principal is when an app wants to connect to Exchange mailboxes via IMAP4 or POP3. Service principals are also the foundation for the RBAC for applications feature to limit app access to mailboxes.
The basic outline is as follows. First, create an Entra ID registered app. Call the app whatever you want (I use “AppforEDiscovery” in this example). Grant administrator consent for the app to the eDiscovery.Read.All and eDiscovery.ReadWrite.All application permissions. Given that the latter is a higher permissioned version of the former, I think the read-write permission is sufficient but went with the documented configuration.
Now the magic happens. Run the Connect-IPPSSession cmdlet to connect PowerShell to the compliance endpoint with an Exchange or Global administrator account and create an Exchange service principal that references the app and its Entra ID service principal (to be able to read the consented permissions). Then use cmdlets to add the service principal to the eDiscovery managers role group and as an eDiscovery administrator.
The net result is that the service principal connects the app to Purview and allows the app to work on cases using the Graph APIs or the eDiscovery cmdlets from the Microsoft Graph PowerShell SDK.
Enabling App-Only Access to eDiscovery Cases with PowerShell
Let’s explore the PowerShell commands to set everything up. I assume that the app is already completed and has assigned permissions. We check its details and store the app identifier in a variable:
$App = Get-MgApplication -filter "displayName eq 'AppforEDiscovery'" $App | Format-Table DisplayName, Id, AppId DisplayName Id AppId ----------- -- ----- AppForeDiscovery 87adafdf-6023-470b-9d24-2e1e40300c13 ea4fb85b-0116-428a-8c57-8177b4666244 $AppId = $App.AppId
Now use the app identifier to find the app’s Entra ID service principal and store its details in a variable:
Connect-IPPSSession -ShowBanner:$false New-ServicePrincipal -AppId $AppId -ObjectId $SP.Id -DisplayName 'AppForEDiscovery' Get-ServicePrincipal -Identity 'AppforEDiscovery' DisplayName ObjectId AppId ----------- -------- ----- AppForeDiscovery 8c750e6d-490d-43b7-bd56-e084e56ce37d ea4fb85b-0116-428a-8c57-8177b4666244
Add the service principal that was just created to the eDiscovery Manager role group. You can see that the identifier for the Exchange service principal is the same as the one used for the Entra ID service principal. In effect, the identifier connects the two objects.
Add-RoleGroupMember -Identity "eDiscoveryManager" -Member $SP.Id Get-RoleGroupMember -Identity 'eDiscoveryManager' Name RecipientType ---- ------------- James Abrahams MailUser Tony Redmond MailUser AppForeDiscovery MailUser
Finally, add the service principal as an eDiscovery administrator:
Add-eDiscoveryCaseAdmin -user $SP.Id Get-eDiscoveryCaseAdmin Name RecipientType ---- ------------- Tony Redmond MailUser 8c750e6d-490d-43b7-bd56-e084e56ce37d User
Figure 1 shows what you might see through the Purview portal UX when an app is a member of the eDiscovery managers role group.
With all that done, it’s possible to create an app-only session with the Microsoft Graph PowerShell SDK and interact with eDiscovery cases using the cmdlets described in the article referenced above:
Connect-MgGraph -NoWelcome -AppId $AppId -CertificateThumbprint $Thumbprint -TenantId
Get-MgSecurityCaseeDiscoveryCase | Sort-Object {$_.CreatedDateTime -as [datetime]} -Descending | Format-Table Id, Description -Autosize
Id Description
-- -----------
a34b5e1b-b15d-438a-bb26-1d91e5fdc688 eDiscovery Case to Find and Remove unwanted SharePoint Online Alert notifications
b111e498-e24b-45ac-9e67-225a29c0caeb Checking for the Fallen Madonna
ea0ab0b7-0b64-479d-b0b9-eae7b50ae4b7 User data search case for GDPR subject LotteVetler
1c75ff90-ef24-494e-8602-a8be9d48593c Case to Track insider dealing in the sales department
Azure Automation and Managed Identities
The same technique can be exploited to use the eDiscovery APIs in Azure Automation using a managed identity for authentication. In this case, the automation account takes the role of the app. Like apps, automation accounts have Entra ID service principals, so it’s easy to find the service principal identifier. To find the app identifier, use the automation account to execute a PowerShell runbook that simply authenticates and then runs the Get-MgContext cmdlet to report the authentication context. The client identifier reported in this information is the app identifier.
For the automation account selected for this example, (Get-MgContext).ClientId reported a value of d8713b80-acb8-40bc-a074-ddd2890beb17, so the commands to add the automation account to the eDiscovery managers role group were:
$AppId = 'd8713b80-acb8-40bc-a074-ddd2890beb17' $SP = Get-MgServicePrincipal -Filter "appId eq '$AppId'" $SP | Format-Table DisplayName, Id, AppId DisplayName Id AppId ----------- -- ----- M365Automation a7c1f06e-85a5-4c74-b046-743afd496c3a d8713b80-acb8-40bc-a074-ddd2890beb17 New-ServicePrincipal -AppId $AppId -ObjectId $SP.Id -DisplayName 'M365Automation' Add-RoleGroupMember -Identity "eDiscoveryManager" -Member $SP.Id Add-eDiscoveryCaseAdmin -user $SP.id
Before it’s possible to create and execute a PowerShell runbook with the eDiscovery cmdlets, two further tasks are necessary. First, install the Microsoft.Graph.Security module from the Microsoft Graph PowerShell SDK as a module resource for the automation account. Second, assign the eDiscovery Graph permissions to the automation account. This action isn’t possible through the Entra admin center and must be done with PowerShell. Here’s how I assigned the two eDiscovery permissions to the service principal for the automation account:
$GraphApp = Get-MgServicePrincipal -Filter "AppId eq '00000003-0000-0000-c000-000000000000'"
$TargetSP = Get-MgServicePrincipal -Filter "displayname eq 'M365Automation'"
[array]$Permissions = "eDiscovery.Read.All", "eDiscovery.ReadWrite.All"
# Get Graph app details
$GraphApp = Get-MgServicePrincipal -Filter "AppId eq '00000003-0000-0000-c000-000000000000'"
# Define the target
$TargetId = (Get-MgServicePrincipal -filter "displayname eq 'M365Automation'").id
# Loop through each permission and assign it to the target
ForEach ($Permission in $Permissions) {
$Role = $GraphApp.AppRoles | Where-Object {$_.Value -eq $Permission}
$AppRoleAssignment = @{}
$AppRoleAssignment.Add("PrincipalId",$TargetId)
$AppRoleAssignment.Add("ResourceId",$GraphApp.Id)
$AppRoleAssignment.Add("AppRoleId", $Role.Id)
# Assign Graph permission
New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $TargetSP.Id `
-BodyParameter $AppRoleAssignment
}
Figure 2 shows a successful test of an Azure Automation runbook that retrieves details of eDiscovery cases.
Some Recent API Changes
In closing, let me note the recent message center notification (MC1115305, 14 July 2025, Microsoft 365 roadmap item 495458), which covers some improvements made to the eDiscovery APIs. If you’re interested in working with eDiscovery cases through the Graph, it’s worth checking out the updates to see if there’s something that you can use.
