Skip to main content

​
Overview

The Microsoft Teams integration uses an application registration in Microsoft Entra ID and authenticates with Tenant ID, Client ID, and Client Secret. Microsoft documents this as the standard application-based method for accessing Microsoft Defender APIs without a user session.

​
Supported Versions

ComponentSupported Version
Microsoft Defender XDRCurrent cloud tenant
Microsoft Defender for Endpoint APIsCurrent supported API set
Microsoft Entra IDCurrent supported cloud directory
AirMDR PlatformCurrent supported cloud deployments
Microsoft provides separate but similar app-registration guidance for Microsoft Defender XDR and Microsoft Defender for Endpoint, both using Microsoft Entra application authentication. 

​
Authentication

AirMDR uses application-based OAuth authentication through Microsoft Entra ID.
CredentialDescription
Tenant IDDirectory (tenant) identifier from the Microsoft Entra app
Client IDApplication (client) identifier from the Microsoft Entra app
Client SecretSecret generated under the app registration
Remote AgentOptional AirMDR routing component selected in AirMDR, not generated in Microsoft Defender

​
Pre-requisites

Active tenant in Microsoft Entra IDAccess to Microsoft Defender for Endpoint (or relevant Defender service with API data)

​
Set Up Steps

1

Register a Microsoft Entra Application

  1. Log in to your Azure Portal.
  2. Go to Microsoft Entra ID (formerly Azure AD).
  3. In the left menu, click Manage → App registrations.
2

Register a New Application

  1. Click + New registration.
  2. Provide the mandatory details:
    • (Application Name: Enter a name for your app (e.g., airmdr-defender).
    • Supported Account Types: Select “Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant)” option).
  3. Click Register.
Redirect URI (Optional): If your app uses authentication, enter a URL (e.g., https://myapp.com/auth).
3

Retrieve the Application (Client) ID and Tenant ID

  1. After successful registration, you will see the App Overview page.
Copy Application (Client) ID – Identifies your app.
Copy Directory (Tenant) ID – Identifies your Azure AD tenant.
4

Configure API Permissions

  1. In the application Overview page left navigation pane, select Manage dropdown.
  2. Click API Permissions.
  3. Click + Add a permission
  4. Select APIs my organization uses tab.
  5. Search and select the API “Microsoft Threat Protection”.
  6. Click on Application permissions.
  7. Select the required permissions:
    • To Fetch List of Incidents - Incident.Read.All
  8. Click Add permissions at the bottom of the page.
  9. Click API permissions, select Yes for Grant admin consent confirmation to allow access.
5

Create a Client Secret (For Authentication)

  1. In the application Overview page left navigation pane, select Manage dropdown.
  2. Click Certificates & secrets.
  3. Click + New client secret. MDE6 Pn
  4. Enter a description (e.g., MySecretKey) and set expiration.
  5. Click Add.
Copy and secure the Value (Client Secret) immediately – (It won’t be shown again!)
Email the Tenant ID, Client ID and the Client Secret Value to AirMDR or self Configure Microsoft Defender in AirMDR Integrations Dashboard.

​
Evaluate Microsoft Defender

​
Pre-requisites

Azure App Registration with API permissions for Microsoft Defender.
Client ID, Tenant ID, and Client Secret.
1

Obtain an Access Token

Open cURL and run the following command to check if your API Access is working:MDE uses OAuth 2.0 authentication. First, request an access token from Microsoft Entra ID (Azure AD):

curl -X POST "https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "client_id=<client_id>" \
     -d "client_secret=<client_secret>" \
     -d "grant_type=client_credentials" \
     -d "scope=https://api.security.microsoft.com/.default"
Replace:
  • <tenant_id> – Your Azure Directory (Tenant) ID.
  • <client_id> – Your App Registration Client ID.
  • <client_secret> – Your App Registration Client Secret.
Expected Response (Success):

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhb..."
}
  • This verifies if the user can retrieve device information based on the assigned scope.
2

Test API Access with MDE

Once you have the access_token, use it in API calls.
  • To Get Device List

curl -X GET "https://api.security.microsoft.com/api/machines" \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json"
Expected Response: A JSON list of devices onboarded to Microsoft Defender.
  • To Get Alerts

curl -X GET "https://api.security.microsoft.com/api/alerts" \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json"
Expected Response:A list of security alerts detected by Microsoft Defender.

​
Configure Microsoft Teams in AirMDR Integrations Dashboard

  1. Navigate to AirMDR, provide the credentials and click Login
  2. Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select Integrations.
  3. Use the search option, enter the keyword “Microsoft Defender”, select the Connections tab, and click + Create button.
  4. Enter an unique name to the Instance (e.g., your org name-Microsoft Defender) to easily identify the user connection by AirMDR.
  5. Enter the generated Tenant ID, Client ID and the Client Secret in the Authentication Details field params, and click Save.

​
Skills provided by this Integration

Skill IDPurpose
List Microsoft Defender Incidents for DetectionsFetches and normalizes all security incidents from Microsoft Defender XDR using the Incidents API (GET /api/incidents on api.security.microsoft.com) with full pagination support for detection workflows. Microsoft Defender XDR aggregates incidents across all Defender services — Endpoint, Identity, Cloud Apps, Office 365, and Sentinel. Each incident is expanded into alert-level rows using Spark SQL, producing a normalized dataset with incident metadata (ID, name, severity, status, classification, determination, assigned analyst) and per-alert fields (alert ID, title, category, severity, status, service source, detection source). The duration and duration_type parameters scope results to a rolling time window via OData filter on createdTime or lastUpdateTime. Use this skill as the detection entry point for automated triage, alert correlation, and scheduled detection pipelines.
List Microsoft Defender IncidentsRetrieves a paginated list of security incidents from Microsoft Defender XDR using the Incidents API (GET /api/incidents on api.security.microsoft.com). Microsoft Defender XDR aggregates incidents across all Defender services - Endpoint, Identity, Cloud Apps, Office 365, and Sentinel - into a unified incident queue. Each incident object includes the incident ID, name, severity (Informational, Low, Medium, High), status (Active, Resolved, Redirected), classification, determination, assigned analyst, creation and last update timestamps, and a nested list of alerts from the originating Defender services. The duration and duration_type parameters construct an OData filter applied against either createdTime or lastUpdateTime, scoping results to a rolling time window. Use this skill for SOC triage, daily alert review, or SIEM enrichment. Pivot to get_microsoft_defender_incident for full incident details including alerts, devices, and entities.
Get Microsoft Defender IncidentRetrieves full details of a single incident by ID from Microsoft Defender XDR using the Incidents API (GET /api/incidents/ on api.security.microsoft.com ). The response includes the complete incident object with incident ID, name, severity (Informational, Low, Medium, High), status (Active, Resolved, Redirected), classification, determination, assigned analyst, creation and last update timestamps, and the full list of associated alerts. Each alert contains the alert ID, service source (indicating the originating Defender service such as MicrosoftDefenderForEndpoint, MicrosoftDefenderForldentity, MicrosoftCloudAppSecurity, MicrosoftDefenderForOffice365), title, description, severity, status, category, devices, and entities. Use this skill during incident triage to get the full attack chain across all Defender services, or during incident response to understand the scope and impact of a specific incident. Obtain incident IDs from list_microsoft_defender_incidents.
To view the details of Input Parameters and Output for the respective skills

​
Additional Information

Error CodePossible IssueSolution
401 UnauthorizedInvalid tokenRegenerate token, check credentials
403 ForbiddenInsufficient API permissionsGrant admin consent in Azure Portal
400 Bad RequestIncorrect request formatVerify API endpoint and headers
500 Internal Server ErrorService issueRetry later, check the Defender status
  • Secure service account credentials
  • Use built-in RBAC from Microsoft Defender for Endpoint and related Defender services.
  • Assign only the minimum required permissions using Microsoft Entra ID roles.
  • Enforce:
    • Multi-Factor Authentication (MFA)
    • Device compliance checks
    • Location-based access restrictions
  • Ensure all endpoints:
    • Are onboarded to Microsoft Defender for Endpoint
    • Meet compliance policies
  • Enable:
    • Attack Surface Reduction (ASR) rules
    • Endpoint Detection and Response (EDR)
  • Disable:
    • Unnecessary services and ports
  • Ensure encryption:
    • In transit → TLS 1.2+
    • At rest → Microsoft-managed or customer-managed keys
  • 📧 Contact AirMDR Support through your designated support channel.
  • 🔁 Rotate:
    • Client secrets (recommended every 30–90 days)
    • Certificates before expiration
  • Implement automated rotation where possible
  • 🔄 Reconnect in AirMDR when secrets are changed.