Non-Graph data-plane registration — when a Graph scope is only half the permission¶

A few Microsoft Graph endpoints are a front end over a data plane that keeps its own principal registry. For those, granting the Graph application permission puts the scope in the poller's token and changes nothing: the service behind the endpoint has never heard of your service principal and refuses it. The other half is a registration in Security & Compliance PowerShell — not a Graph scope, not consentable in the Entra admin center, and not something graph2otel can do for you.

This page is the operator procedure for that second half, and the diagnostic that tells you whether you need it. Read it before granting eDiscovery.Read.All — the grant alone will not produce data, and the failure gives you nothing to work with.

Evidence tags, as in graph-api-gotchas.md: [live YYYY-MM-DD, #issue] was measured on the wire against a real tenant under the poller's own identity; [docs-only] is believed from Microsoft's documentation and cheap to re-open; [n=1] is a single observation; [unverified] is not established either way. Microsoft's documentation has been wrong on essentially every load-bearing detail on this path — wire over docs.

The diagnostic: the status code is the whole tell¶

Both outcomes below were observed in the same tenant in the same session, on two Purview endpoints. They look alike and are different systems failing for different reasons.

Corroborating detail that rules out the alternatives [live 2026-07-16, #102]:

• GET /v1.0/security/cases → 200, but GET /v1.0/security/cases/ediscoveryCases → 401 UnknownError (empty message), v1.0 and beta alike. The parent is Graph-served; the child hits the Purview data plane. So this is not routing, and not the token being rejected wholesale.
• GET /v1.0/compliance/ediscovery/cases → 401 Unauthorized with ServiceFabricGraphAuthenticationMiddleware.ValidateToken in the message — the compliance data plane rejecting the principal, exactly as the middleware name says.
• 401 is not 403. It is not "you lack a scope", it is "I cannot identify you", from a service where the principal does not exist.

Do not generalize either result. A 403 means missing consent far more often than product limitation (#109 called a missing scope a permanent gap and was wrong). But a grant can also be insufficient (#102). Verify, never infer, in both directions.

graph2otel check cannot see this failure mode: it reports whether a permission is granted and consented, which for a token holding eDiscovery.Read.All is a clean pass while the endpoint 401s. See permissions.md for the caveats it documents about itself.

Who needs it¶

Audit result: eDiscovery is the only surface on graph2otel's map that needs this. Every other Purview and M365 collector either takes a plain Graph application permission, or takes none because it reads a different data plane with its own Entra app roles. Recorded so the absence of findings is on the record rather than assumed.

What this does not fix¶

Registering the principal makes a data plane recognize you. It does not create an API where none exists. These are named so you do not run the procedure hoping:

• Purview retention labels — GET /security/labels/retentionLabels → 500 DataInsightsRequestError + "Forbidden" on v1.0 and beta with RecordsManagement.Read.All granted and in the token [live 2026-07-16, #109/#126]. Microsoft's permission table says Application: Not supported [docs-only]. This is a product gap, not a registration gap. Retention label definitions being Graph-exposed does not change the app-only verdict.
• Retention policy location bindings — S&C PowerShell only (Get-RetentionCompliancePolicy), no Graph list equivalent [live, #99].

Correction (live-measured 2026-07-23, #237): an earlier version of this list said "DLP policy enumeration — the Purview APIs evaluate content against policy; they never enumerate policy." That generalization was true of the #99 Purview Ecosystem roles and is false of Graph: GET /beta/security/dataSecurityAndGovernance/policyFiles returns the full DLP policy set app-only, on scopes the poller already holds — no data-plane registration needed. #246 builds it. Only retention policy bindings remain a genuine gap.

The distinction that matters: this procedure only helps where a Graph endpoint exists and the data plane behind it refuses you. Retention bindings are reachable from S&C PowerShell — but graph2otel speaks Graph at runtime, never PowerShell, so a reachable-only-from-PowerShell surface is out of reach regardless of what you register.

The procedure¶

Run once per app registration, per tenant. It mutates the tenant. Every value below is a placeholder except the device-code client id in step 1.

0. Resolve the object id — this is the trap¶

The role-group cmdlets take the enterprise-application object id, not the appId. They are different GUIDs for the same app, and using the appId is the documented common mistake [docs-only]. On the reference tenant the two values are unrelated strings and neither is derivable from the other [live 2026-07-17, #102/#148].

Resolve it from Graph and read .id:

GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='<appId>')

The id this returns is the value to paste into -ObjectId, -Member, and -User below. It was confirmed correct against the live directory before the cmdlets ran [live 2026-07-17, #102/#148].

1. Connect — app-only does not work; use a delegated device-code token¶

Do not plan around app-only Connect-IPPSSession. On the reference tenant it fails, and a Windows host does not fix it [live 2026-07-17, #102/#148]:

Same module version, same identity, same org, two operating systems, byte-identical failure. -Verbose places it after authentication — Successfully got a token from AAD, then a NullRef in Microsoft.Exchange.Management.ExoPowershellSnapin.NewEXOModule.ProcessRecord(). Ruled out with evidence: not the platform (Windows reproduces it); not the certificate or the identity (Connect-ExchangeOnline with the same pfx from the same host connects and returns live data); not a missing role (the identity held Compliance Administrator, Security Administrator, Exchange Administrator and Exchange.ManageAsApp, live-read); not replication lag (three days). Why app-only fails is open [unverified] — the obvious explanation, "the principal is unknown to compliance RBAC", is refuted: that principal was already registered and it still NullRefs [live 2026-07-17, #102].

A delegated device-code token connects first try from the same host that fails app-only [live 2026-07-17, #102/#148]. There is also a bootstrap argument for it: New-ServicePrincipal is itself an S&C cmdlet, so registering a principal for app-only access appears to require an already-working session, which app-only cannot give you. That is a deduction from the cmdlet's location, not a measurement [unverified].

The device-code client id matters [live 2026-07-17, #149]:

Scope: https://ps.compliance.protection.outlook.com/.default.

Install-Module ExchangeOnlineManagement    # 3.10.0 is the measured version
Import-Module ExchangeOnlineManagement

# $token: delegated device-code token for client fb78d390-… , scope above.
Connect-IPPSSession -AccessToken $token -Organization "<tenant>.onmicrosoft.com"

The signing-in user must be able to run New-ServicePrincipal and Add-RoleGroupMember; on the reference tenant this was a Global Administrator [live 2026-07-17, #102/#148]. The minimum role that suffices was not established [unverified] — if you establish it, that is worth recording. The -AccessToken / -Organization parameter spelling above is also [unverified]: the issues record that the token was acquired and the session connected, not the cmdlet's exact parameter form.

2. Register the principal and grant the role¶

Get-ServicePrincipal first — it lists what the compliance data plane already knows, and an app registered by some earlier process will already be there [live 2026-07-17, #102].

Get-ServicePrincipal

New-ServicePrincipal -AppId "<appId>" `
                     -ObjectId "<enterprise app object id, from step 0>" `
                     -DisplayName "graph2otel-poller"

Add-RoleGroupMember -Identity "eDiscoveryManager" -Member "<object id>"
Get-RoleGroupMember -Identity "eDiscoveryManager"

Add-eDiscoveryCaseAdmin -User "<object id>"
Get-eDiscoveryCaseAdmin

On least privilege. These three ran as one batch, so which subset is minimally sufficient is unverified — the 401 → 200 transition is attributable to the batch, not to any one cmdlet. eDiscoveryManager is not a read-only role group; Microsoft documents it as able to create and manage cases [docs-only], which is more than a telemetry poller needs. A Reviewer role group was named as the lower-privileged alternative when the fix was scoped [#102] and was not tested [unverified]. If you want strict read-only, try Reviewer first, and record what happens — a narrower working configuration is a finding this page should carry.

3. Verify — re-request the endpoint as the poller¶

Mint a fresh token (app-only tokens embed roles at issue time) with the poller's own credentials, and request the endpoint that was failing:

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

Expect 200 where you had 401. Measured on the reference tenant, v1.0 and beta both moved 401 → 200, one live case returned [live 2026-07-17, #102/#148].

Do not wait 24 hours. The ≤24h compliance-RBAC replication lag that Microsoft's guidance implies did not apply: the probe returned 200 on the first attempt, immediately after the cmdlets, with no wait [live 2026-07-17, #102/#148]. If yours still 401s, then replication is a candidate — as a fallback explanation, not as an instruction.

Probe as the poller identity itself, never with another app. A different app's access answers a different question — that is how #109 reached a wrong verdict, and the verdict then suppressed re-investigation until #126 re-probed correctly.

Runtime: graph2otel never speaks PowerShell¶

This is a one-time setup action, not a dependency. graph2otel reads eDiscovery over Graph as the poller, with eDiscovery.Read.All, like every other collector [live 2026-07-17, #102]. Nothing in the binary imports, shells out to, or requires the ExchangeOnlineManagement module. If you rotate to a new app registration, the new principal needs its own registration — the compliance data plane keys on the principal, not the tenant. Whether a registration ever expires or needs re-running is [unverified]; the reference tenant's is one day old.

eDiscovery.Read.All stays granted after this runs: it is read-only, and it is half of a working configuration rather than a permission the poller cannot use.