Skip to content

Configure Microsoft Entra permissions

Create a Microsoft Entra application registration and grant only the permissions required by the inputs and alert actions that you use. Configure permissions as Application permissions, not Delegated permissions.

Permission reference

The following table maps add-on capabilities to Microsoft API permissions or Azure roles:

Capability Source type Required permission or role Component
Collect incidents and their alerts by using the Microsoft 365 Defender API ms365:defender:incident, ms365:defender:incident:alerts Incident.Read.All Modular input
Collect incidents and their alerts by using Microsoft Graph ms365:defender:incident, ms365:defender:incident:alerts SecurityIncident.Read.All Modular input
Collect endpoint alerts by using the Microsoft Defender for Endpoint API ms:defender:atp:alerts Alert.Read.All Modular input
Collect endpoint alerts by using Microsoft Graph ms:defender:atp:alerts SecurityAlert.Read.All Modular input
Collect Microsoft Defender for Endpoint machine inventory ms:defender:machines Machine.Read.All Modular input
Update incidents by using the Microsoft 365 Defender API ms365:defender:incident, ms365:defender:incident:alerts Incident.ReadWrite.All Alert action
Update incidents by using Microsoft Graph ms365:defender:incident, ms365:defender:incident:alerts SecurityIncident.ReadWrite.All Alert action
Run Defender Advanced Hunting queries m365:defender:incident:advanced_hunting ThreatHunting.Read.All Alert action
Collect attack simulation reports ms:defender:simulations AttackSimulation.Read.All Modular input
Collect streamed Advanced Hunting events from Azure Event Hubs ms:defender:eventhub Azure Event Hubs Data Receiver Modular input
Collect Microsoft Defender Threat Intelligence datasets ms:defender:ti:* ThreatIntelligence.Read.All Modular input
Dismiss an Azure subscription-level security alert Not applicable Security Admin, or a custom Azure role that includes Microsoft.Security/locations/alerts/dismiss/action Alert action

Important

In version 5.0.0, the Defender Advanced Hunting alert action uses Microsoft Graph only. The legacy AdvancedHunting.Read.All permission does not authorize this action. Add ThreatHunting.Read.All and grant administrator consent before you upgrade.

Add API permissions

You need a Microsoft Entra role that can manage application permissions. An application owner can add requested permissions, but an administrator must grant tenant-wide consent.

  1. Sign in to the Microsoft Entra admin center.
  2. Go to Identity > Applications > App registrations > All applications.
  3. Select the application registration that the add-on uses.
  4. Select API permissions.
  5. Select Add a permission.
  6. Select the API used by your input or alert action.
  7. Select Application permissions.
  8. Select the permissions from the permission reference.
  9. Select Add permissions.
  10. Select Grant admin consent and confirm the action.
  11. Verify that the status for each required permission is Granted.

For the Microsoft Graph permission definitions, see the Microsoft Graph permissions reference. For ThreatHunting.Read.All, see Run hunting query. For the Microsoft Defender for Endpoint permission, see List machines API.

Assign the Azure Event Hubs role

The Microsoft Defender Event Hub input uses an Azure role instead of a Microsoft Graph application permission.

  1. In the Azure portal, open the Event Hubs namespace or event hub that the add-on uses.
  2. Select Access control (IAM).
  3. Add a role assignment for Azure Event Hubs Data Receiver.
  4. Assign the role to the identity represented by the add-on’s Microsoft Entra application.
  5. Verify the assignment before you configure the input.

For information about configuring Microsoft Defender XDR streaming, see Stream data from Microsoft Defender XDR to Event Hubs.

Assign permission to dismiss Azure alerts

The Dismiss Azure Alert action uses Azure role-based access control instead of a Microsoft Graph application permission.

  1. In the Azure portal, open the subscription that contains the security alerts.
  2. Select Access control (IAM).
  3. Add a role assignment for Security Admin, or assign a custom role that includes Microsoft.Security/locations/alerts/dismiss/action.
  4. Assign the role to the service principal for the Microsoft Entra application configured as the add-on account.
  5. Verify the assignment before you configure the alert action.

Grant the role at the narrowest scope that contains the alerts the action must dismiss. See Azure permissions for Security and Security Admin in the Microsoft documentation.