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.
- Sign in to the Microsoft Entra admin center.
- Go to Identity > Applications > App registrations > All applications.
- Select the application registration that the add-on uses.
- Select API permissions.
- Select Add a permission.
- Select the API used by your input or alert action.
- Select Application permissions.
- Select the permissions from the permission reference.
- Select Add permissions.
- Select Grant admin consent and confirm the action.
- 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.
- In the Azure portal, open the Event Hubs namespace or event hub that the add-on uses.
- Select Access control (IAM).
- Add a role assignment for Azure Event Hubs Data Receiver.
- Assign the role to the identity represented by the add-on’s Microsoft Entra application.
- 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.
- In the Azure portal, open the subscription that contains the security alerts.
- Select Access control (IAM).
- Add a role assignment for Security Admin, or assign a custom role that includes
Microsoft.Security/locations/alerts/dismiss/action. - Assign the role to the service principal for the Microsoft Entra application configured as the add-on account.
- 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.