Entra app registration

Setting up the Entra app registration

xdr can instead authenticate as you through an app registration in your tenant, over Microsoft’s supported APIs. One registration can be shared by everyone on the team.

1. Azure Portal → Microsoft Entra ID → App registrations → New registration. Name it (xdr-cli), choose Single tenant, and add a Public client/native redirect URI of http://localhost. If anyone will sign in on Windows, also add ms-appx-web://Microsoft.AAD.BrokerPlugin/<client-id> (your application ID from step 2), which the Windows sign-in broker (WAM) requires.

2. From Overview, copy the Application (client) ID and Directory (tenant) ID.

3. API permissions → Add a permission. Add these delegated permissions:

   API	Permission	Used by
   Microsoft Graph	SecurityIncident.ReadWrite.All	incidents list/show/update, investigate
   Microsoft Graph	SecurityAlert.Read.All	alerts list/show
   Microsoft Graph	ThreatHunting.Read.All	hunt run, library run, investigate, schema
   Microsoft Graph	Domain.Read.All	Entra portion of domains list
   WindowsDefenderATP¹	Machine.Read	device show, device action-status, hostname lookups
   WindowsDefenderATP	Machine.Isolate	device isolate / unisolate
   WindowsDefenderATP	Machine.Scan	device scan
   WindowsDefenderATP	Machine.CollectForensics	device collect-package
   WindowsDefenderATP	Machine.RestrictExecution	device restrict, device unrestrict
   WindowsDefenderATP	AdvancedQuery.Read	Hunting fallback only (see below)

   ¹ Under APIs my organization uses, search for WindowsDefenderATP. Defender for Endpoint tokens are still issued for the api.securitycenter.microsoft.com audience even though requests go to api.security.microsoft.com; that is why these live under WindowsDefenderATP rather than Microsoft Graph.

   The minimum for the quick start above is the first three Graph rows plus Machine.Read (used by investigate to enrich devices). Grant only what the commands you intend to use need. device download-package and the Active Directory part of domains list have no official API and stay cookie-only.

   Hunting goes through Microsoft Graph. If Graph hunting returns 403 or 404, xdr retries the query once against the Defender for Endpoint hunting API (api.security.microsoft.com/api/advancedqueries/run), which needs AdvancedQuery.Read and only sees Defender for Endpoint tables. Microsoft began retiring that API in January 2026, so configure Graph hunting and treat the fallback as temporary.

4. Grant admin consent for your tenant. Every permission above is delegated, so a Cloud Application Administrator, Application Administrator, or Privileged Role Administrator can grant it (Microsoft’s requirements). Security Administrator alone cannot. The service-principal setup described under Configuration uses Microsoft Graph application permissions, which need Privileged Role Administrator.

5. Authentication → Advanced settings → Allow public client flows → Yes.

6. Sign in. This opens an interactive sign-in (the WAM broker on Windows, your browser elsewhere); if neither can start, e.g. on a headless host, it prints a device code instead. tenant_id and client_id are saved to ~/.xdr-cli/config.toml.

   xdr auth login --tenant-id <TENANT_ID> --client-id <CLIENT_ID>
   xdr auth status                            # main.backend: official

The signed-in user also needs the Defender roles that match what they run (Security Reader for triage; Active remediation actions for device actions). The app registration cannot grant more than the user has.

If you add a permission after signing in, run xdr auth logout && xdr auth login afterwards. Until then xdr keeps using the cached access token issued before the change, and the new permission fails with PERMISSION_MISSING_SCOPE until that token expires (up to about 90 minutes).