> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airmdr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Graph

> Microsoft Graph is an API that allows developers to access Microsoft 365 data and services. It provides a unified endpoint (https://graph.microsoft.com) to interact with various Microsoft services.

### Pre-requisites

<Check>
  Microsoft 365 Tenant & Azure AD Access

  * A **Microsoft 365 account** with **Azure Active Directory (Azure AD)** access
  * If you don’t have one, you can sign up for a free trial at [https://signup.microsoft.com](https://signup.microsoft.com) and receive an *your‑[tenant.onmicrosoft.com](http://tenant.onmicrosoft.com)* domain plus a 30‑day evaluation of Microsoft 365 and Azure AD.
</Check>

<Check>
  Azure AD App Registration Permissions

  * **Global Admin** or **App Registration Administrator** role in Azure AD is required to register an app in **Azure Active Directory**
</Check>

### Setup Microsoft Graph API

Setting up the **Microsoft Graph API** involves a few steps, including registering an app in **Azure AD** and configuring permissions.

<Steps>
  <Step title="Register an App in Azure AD">
    1. Go to [Azure Portal](https://portal.azure.com/).
    2. Search and select "Microsoft Entra ID" in the search bar. <img src="https://mintcdn.com/airmdr/wb8NOGyN5Zdemkpe/images/MSGraph3.png?fit=max&auto=format&n=wb8NOGyN5Zdemkpe&q=85&s=fdf861af0103ba0cbfabd85d26378198" alt="images/MSGraph3.png" width="861" height="313" data-path="images/MSGraph3.png" />
    3. Navigate to **Manage** → **App registrations.**
    4. Click **+ New registration.** <img src="https://mintcdn.com/airmdr/wb8NOGyN5Zdemkpe/images/MSGraph4.png?fit=max&auto=format&n=wb8NOGyN5Zdemkpe&q=85&s=d943add40d1938e0c8a2cc061e24cb3a" alt="images/MSGraph4.png" width="861" height="605" data-path="images/MSGraph4.png" />
    5. Provide:
       * **Name**: For e.g., "graphapi-client-airmdr"
       * **Supported account types**: Select “*Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant)*” option).
    6. Click **Register.**

           <Note>
             Post successful registration, the application must open automatically if not

             1. Search for Microsoft Entra ID.
             2. Select **Manage** → **App registrations.**
             3. Select the **All Applications** tab.
                1. Search and click on the registered app (For e.g., "graphapi-client-airmdr").
           </Note>
  </Step>

  <Step title="Configure API Permissions">
    1. Go to **Manage** → **API Permissions** in the app settings.
    2. Click **+ Add a permission.**
    3. Select **Microsoft Graph.**
    4. Choose **Application permissions**. <img src="https://mintcdn.com/airmdr/wb8NOGyN5Zdemkpe/images/MSGraph6.png?fit=max&auto=format&n=wb8NOGyN5Zdemkpe&q=85&s=b09e2c763dde04c83d0e919603d2b525" alt="images/MSGraph6.png" width="862" height="349" data-path="images/MSGraph6.png" />
    5. To use the Skills in AirMDR Integration select the required permissions as stated below:
           <Warning>
             **SecurityAlert.Read.All** and **SecurityIncident.Read.All** are mandatory
           </Warning>
           <Check>
             Preferably provide other application permissions for better enrichment of the cases.
           </Check>
       | **Skill Name** | **Application permission** | **Endpoint** |
       | :- | :- | :- |
       | Disable/Enable User | User.EnableDisableAccount.All + [User.Read](http://User.Read).All, or User.ReadWrite.All | PATCH /v1.0/users/\{id} (accountEnabled) |
       | Reset User Password | User-PasswordProfile.ReadWrite.All — app must also hold the User Administrator Entra role | PATCH /v1.0/users/\{id} (passwordProfile) |
       | Revoke Sign-In Session | User.RevokeSessions.All | POST /v1.0/users/\{id}/revokeSignInSessions |
       | Fetch User Details | [User.Read](http://User.Read).All | GET /v1.0/users / /users/\{id} |
       | List Microsoft Graph Users | [User.Read](http://User.Read).All (User.ReadBasic.All only for basic props) | GET /v1.0/users |
       | Fetch User Groups | [Directory.Read](http://Directory.Read).All — app-only does not accept [User.Read](http://User.Read).All here | GET /v1.0/users/\{id}/memberOf |
       | Fetch User Sign-In Logs · Microsoft Graph Fetch User Signin Logs | [AuditLog.Read](http://AuditLog.Read).All (+ [Policy.Read](http://Policy.Read).All to get appliedConditionalAccessPolicies) | GET /v1.0/auditLogs/signIns |
       | Fetch Audit Logs | [AuditLog.Read](http://AuditLog.Read).All | GET /v1.0/auditLogs/\{directoryAudits\|signIns\|provisioning} |
       | List Graph API Security Alerts · List Graph Api Alerts | [SecurityAlert.Read](http://SecurityAlert.Read).All | GET /v1.0/security/alerts\_v2 |
       | List Incidents | [SecurityIncident.Read](http://SecurityIncident.Read).All | GET /v1.0/security/incidents |
       | Get Incident | [SecurityIncident.Read](http://SecurityIncident.Read).All | GET /v1.0/security/incidents/\{id} |
       | Update Incident | SecurityIncident.ReadWrite.All | PATCH /v1.0/security/incidents/\{id} |
       | Create Incident Comment | SecurityIncident.ReadWrite.All | POST /v1.0/security/incidents/\{id}/comments |
       | Run Hunting Query | [ThreatHunting.Read](http://ThreatHunting.Read).All | POST /v1.0/security/runHuntingQuery |
       | Get Vulnerability | [ThreatIntelligence.Read](http://ThreatIntelligence.Read).All — requires a Defender TI portal + API add-on license | GET /v1.0/security/threatIntelligence/vulnerabilities/\{id} |
       | List Microsoft Graph Risky Users | [IdentityRiskyUser.Read](http://IdentityRiskyUser.Read).All — Entra ID P2 | GET /v1.0/identityProtection/riskyUsers |
       | Confirm Microsoft Graph User Compromised | IdentityRiskyUser.ReadWrite.All — Entra ID P2 | POST /v1.0/identityProtection/riskyUsers/confirmCompromised |
       | Dismiss Microsoft Graph User Risk | IdentityRiskyUser.ReadWrite.All — Entra ID P2 | POST /v1.0/identityProtection/riskyUsers/dismiss |
       | List Microsoft Graph Devices | [Device.Read](http://Device.Read).All | GET /v1.0/devices |
       | Get Microsoft Graph Device | [Device.Read](http://Device.Read).All | GET /v1.0/devices/\{id} |
       | Send Email | Mail.Send | POST /v1.0/users/\{id}/sendMail |
       | Microsoft Graph Fetch Office Calendar · Fetch Office Calendar on userId | [Calendars.Read](http://Calendars.Read) (Calendars.ReadBasic if only names/ids needed) | GET /v1.0/users/\{id}/calendars |
       | List Analyzed Emails | [SecurityAnalyzedMessage.Read](http://SecurityAnalyzedMessage.Read).All — Defender for Office 365 P2 / M365 E5 | GET /beta/security/collaboration/analyzedEmails |
       | Remediate Analyzed Email | SecurityAnalyzedMessage.ReadWrite.All — Defender for Office 365 P2 / M365 E5 | POST /beta/security/collaboration/analyzedEmails/remediate |
       | App Consent and Permission Profiler | [DelegatedPermissionGrant.Read](http://DelegatedPermissionGrant.Read).All + [Application.Read](http://Application.Read).All | GET /v1.0/\{users\|servicePrincipals}/\{id}/oauth2PermissionGrants, /appRoleAssignments, /appRoleAssignedTo, /servicePrincipals/\{id} |
       | PIM and Entra Role Management Profiler | [RoleManagement.Read.Directory](http://RoleManagement.Read.Directory) (or [RoleManagement.Read](http://RoleManagement.Read).All) — Entra ID P2 for PIM | GET /v1.0/roleManagement/directory/\{roleEligibilityScheduleInstances,roleAssignmentScheduleInstances,roleAssignmentScheduleRequests} |
       | Application and Service Principal Profiler | [Application.Read](http://Application.Read).All | GET /v1.0/applications, /servicePrincipals, /\{...}/owners |
       | Mailbox Rule and Forwarding Profiler | [MailboxSettings.Read](http://MailboxSettings.Read) | GET /v1.0/users/\{id}/mailFolders/inbox/messageRules, /mailboxSettings |
       | Unified Audit Log Search | `AuditLogsQuery.Read.All`, or the required workload-scoped permissions such as `AuditLogsQuery-Exchange.Read.All` and `AuditLogsQuery-Entra.Read.All` | `POST /v1.0/security/auditLog/queries`; `GET /v1.0/security/auditLog/queries/{query-id}`; `GET /v1.0/security/auditLog/queries/{query-id}/records` |
    6. Click on **Add Permissions**.
    7. In API permissions, click **Grant admin consent**.
    8. In the **Grant admin consent** confirmation modal, click **Yes**. <img src="https://mintcdn.com/airmdr/wb8NOGyN5Zdemkpe/images/MSGraph7.png?fit=max&auto=format&n=wb8NOGyN5Zdemkpe&q=85&s=e58a12a3a4b8fa3d9e6f1ca0e6704f9c" alt="images/MSGraph7.png" width="843" height="226" data-path="images/MSGraph7.png" />
  </Step>

  <Step title="Create Client Secret (For Authentication)">
    1. In the left navigation pane, go to **Manage** → **Certificates & secrets.**
    2. Select **Client Secrets** tab.
    3. Click **+ New client secret.** <img src="https://mintcdn.com/airmdr/wb8NOGyN5Zdemkpe/images/MSGraph8.png?fit=max&auto=format&n=wb8NOGyN5Zdemkpe&q=85&s=c8867b2eff9b99548b9d9bd70c4e1add" alt="images/MSGraph8.png" width="845" height="344" data-path="images/MSGraph8.png" />
    4. Add a **description** and **expiration period.**
    5. Click **Add**.
           <Warning>
             Copy and securely save the **Client Secret Value** (it won’t be shown again)
           </Warning>
  </Step>

  <Step title="Securely share the Client ID and Tenant ID to AirMDR">
    To access the Client ID, and the Tenant ID to use in Graph API authentication

    1. Go to [Azure Portal](https://portal.azure.com/).
    2. Navigate to **Azure Active Directory.**
    3. Click **App registrations.**
    4. Select your **registered app.**
    5. Under the **Overview** section, locate the **Application (client) ID** and **Tenant ID (Directory ID).**
    6. Click the **Copy** icon **📋** next to the Client ID, and the Tenant ID respectively.
           <Info>
             Now, your **Tenant ID** and **Client ID** are copied and ready to use for authentication in Microsoft Graph API.
           </Info>
           <Check>
             <Icon icon="mail" /> Share the **Tenant ID**, **Client ID**, and **Client Secret Value** securely with the AirMDR operations team or self-configure them in the AirMDR Integrations Dashboard.
           </Check>
  </Step>
</Steps>

### Skills Provided by this Integration

| **Skill name** | **Display name** | **Permission required (application)** |
| :- | :- | :- |
| get\_microsoft\_graph\_managed\_devices | Get Intune Managed Devices | [DeviceManagementManagedDevices.Read](http://DeviceManagementManagedDevices.Read).All |
| get\_microsoft\_graph\_user\_devices | Get User Devices | [DeviceManagementManagedDevices.Read](http://DeviceManagementManagedDevices.Read).All (Entra ownedDevices/registeredDevices are delegated-only — 403 on app auth) |
| get\_microsoft\_graph\_managed\_app\_registrations | Get MAM App Registrations | [DeviceManagementApps.Read](http://DeviceManagementApps.Read).All |
| get\_microsoft\_graph\_managed\_app\_policies | Get MAM App Protection Policies | [DeviceManagementApps.Read](http://DeviceManagementApps.Read).All |
| get\_microsoft\_graph\_device\_detected\_apps | Get Device Detected Apps | [DeviceManagementManagedDevices.Read](http://DeviceManagementManagedDevices.Read).All |
| get\_microsoft\_graph\_device\_malware | Get Device Malware and Defender State | [DeviceManagementManagedDevices.Read](http://DeviceManagementManagedDevices.Read).All |
| get\_microsoft\_graph\_device\_configuration\_states | Get Device Configuration States | [DeviceManagementManagedDevices.Read](http://DeviceManagementManagedDevices.Read).All |
| get\_microsoft\_graph\_intune\_audit\_events | Get Intune Audit Events | [DeviceManagementApps.Read](http://DeviceManagementApps.Read).All |
| run\_microsoft\_graph\_device\_defender\_scan | Run Defender Antivirus Scan | DeviceManagementManagedDevices.PrivilegedOperations.All |
| retire\_or\_wipe\_microsoft\_graph\_device | Retire or Wipe Device | DeviceManagementManagedDevices.PrivilegedOperations.All |
| lock\_or\_reboot\_microsoft\_graph\_device | Lock or Reboot Device | DeviceManagementManagedDevices.PrivilegedOperations.All |
| sync\_microsoft\_graph\_device | Sync Device | DeviceManagementManagedDevices.PrivilegedOperations.All |
| microsoft\_graph\_search\_unified\_audit\_log | Unified Audit Log Search | `AuditLogsQuery.Read.All`, or the required workload-scoped `AuditLogsQuery-*.Read.All` permissions |
| wipe\_microsoft\_graph\_managed\_app\_data | Wipe Managed App Data | DeviceManagementApps.ReadWrite.All |

### Configure Microsoft Graph in AirMDR Integrations Dashboard

1. Navigate to [AirMDR](https://app.airmdr.com/auth/login), provide the credentials and click **Login.**
2. Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select **ADMIN → Integrations.**
3. Use the search option, enter the keyword "**Microsoft Graph**", select the **Connections** tab, and click the **+ New Connection** icon.
4. Enter an unique name to the **Instance** (e.g., `your org name-MSGraph`) to easily identify the user connection by AirMDR and brief **Description**.
5. Enter the generated **Tenant ID, Client ID** and the **Secret Value** in the Authentication Details field params, and click **Save.**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.