# Navigating between Azure, Graph, and others

This documentation outlines the three primary API ecosystems within the Microsoft Cloud: **Microsoft Graph**, **Azure Management (ARM)**, and **Microsoft Defender for Endpoint (MDE)**.

While all three utilize **Microsoft Entra ID** (formerly Azure AD) for identity, they differ significantly in their resource identifiers, permission models, and configuration workflows.

## 1. Executive Summary Table

| **Feature**         | **Microsoft Graph**           | **Azure Management (ARM)**           | **Microsoft Defender (MDE)**               |
| ------------------- | ----------------------------- | ------------------------------------ | ------------------------------------------ |
| **Primary Focus**   | Identity, Productivity, M365  | Infrastructure & Cloud Resources     | Security, EDR, Machine Actions             |
| **API Endpoint**    | `graph.microsoft.com`         | `management.azure.com`               | `api.securitycenter.microsoft.com`         |
| **Auth Resource**   | `https://graph.microsoft.com` | `https://management.azure.com`       | `https://api.securitycenter.microsoft.com` |
| **Authorization**   | **OAuth2 Scopes** (Additive)  | **Azure RBAC** (Hierarchical)        | **OAuth2 Scopes** (Specific)               |
| **Portal Location** | App Reg -> API Permissions    | Subscription -> Access Control (IAM) | App Reg -> APIs my org uses                |

## 2. Microsoft Graph API

**Purpose:** The "gateway" to Microsoft 365. It is used to manage the "Software as a Service" (SaaS) layer.

- **Key Entities:** Users, Groups, Teams, Outlook, OneDrive, SharePoint, Intune, and Entra ID itself.
- **Permission Model:** **Scope-based.** You define permissions (e.g., `User.ReadWrite.All`) directly on the App Registration.
- **Token Request:**
  - Scope: `https://graph.microsoft.com/.default`
- **Crucial Step:** Most permissions require **Admin Consent**. Without a global admin clicking "Grant Admin Consent" in the portal, the app will receive a `403 Forbidden` despite having the permissions listed.

## 3. Azure Management API (ARM)

**Purpose:** The control plane for Azure Infrastructure. It is used to manage "Infrastructure as a Service" (IaaS) and "Platform as a Service" (PaaS).

- **Key Entities:** Virtual Machines, SQL Databases, Resource Groups, Subscriptions, VNETs.
- **Permission Model:** **Role-Based Access Control (RBAC).** \* Adding permissions in the App Registration (like `user_impersonation`) only says "this app is allowed to talk to Azure."
  - **The real permission** is granted by going to the Azure Resource (e.g., a Subscription) and assigning a **Role** (Contributor, Reader, Owner) to the App's Service Principal.
- **Token Request:**
  - Scope: `https://management.azure.com/.default`

## 4. Microsoft Defender for Endpoint (MDE) API

**Purpose:** Advanced security operations, threat hunting, and device-level remediation.

- **Key Entities:** Machines (endpoints), Alerts, Vulnerabilities, Indicators (IoCs).
- **Permission Model:** **Hybrid/Scope-based.** Like Graph, it uses scopes, but they are found under a different "hidden" API in the portal.
- **The "Hidden" API:** To add these, you must search for **"WindowsDefenderATP"** under the "APIs my organization uses" tab in the App Registration.
- **Key Capabilities:** Unlike Graph (which sees alerts), the MDE API allows for **Remediation Actions**—such as isolating a machine from the network or running a remote antivirus scan.
- **Token Request:**
  - Scope: `https://api.securitycenter.microsoft.com/.default`

## 5. Summary of Differences & "Gotchas"

### A. Token Audience (The #1 Error)

You cannot "multi-purpose" an access token. If you get a token for Graph, it will fail if sent to the Azure Management API.

:::note
**Rule:** One Token = One Resource Audience.
:::

### B. Permission Management

- **Graph/Defender:** Defined at the **App Level**. If the app has `Machine.Read.All`, it sees _every_ machine in the tenant.
- **Azure ARM:** Defined at the **Resource Level**. If the app is a "Contributor" on _Resource Group A_, it cannot see anything in _Resource Group B_.

### C. Use Case Scenario

If you are building an automation script to handle a compromised laptop:

1. **Use Microsoft Graph** to reset the user's password and revoke their O365 sessions.
2. **Use Microsoft Defender API** to isolate the laptop from the network and collect a forensic investigation package.
3. **Use Azure Management API** to lock down the specific Virtual Desktop (AVD) resource or Network Security Group (NSG) associated with that user.

## 6. Implementation Checklist

- [ ] **Identify your Audience:** Are you touching a User (Graph), a VM (Azure), or an Alert (Defender)?
- [ ] **App Registration:** Create the registration in Entra ID.
- [ ] **Secret/Cert:** Generate a Client Secret or upload a Certificate for authentication.
- [ ] **Assign Permissions:** \* For **Graph/Defender**: API Permissions -> Grant Admin Consent.
  - For **Azure**: Go to Subscription -> IAM -> Add Role Assignment for the App.
- [ ] **Request Token:** Use the specific URL for that API in your OAuth2 request.