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

# Microsoft Defender EDR Instructions

> Instructions on how to onboard a Microsoft Defender Integration

Leen supports Microsoft Defender for Endpoint two ways: admin consent to Leen's Microsoft Defender app, or an app registration you create and control in your own tenant. Admin consent is described first, and every section from here down to [Microsoft Defender App](#microsoft-defender-app) applies to that route only.

<Info>
  **Prefer to use your own application?** The app-only route has no authorizing user and grants nothing to a Leen-owned application, so none of the admin consent requirements below apply to it. See [Connecting with your own app registration](#connecting-with-your-own-app-registration) at the end of this page.
</Info>

### Admin Consent Requirement

On this route, the user authorizing the Microsoft Defender connection must be able to **grant tenant-wide admin consent**.

This route uses the `/adminconsent` endpoint, which requires admin consent to authorize the application on behalf of the entire organization. Microsoft Defender APIs require **application permissions** that need admin consent to access organizational data across all users.

<Info>
  **Important:** Application registration only defines which permissions the application requires. A Microsoft Entra tenant administrator must explicitly grant these permissions by granting admin consent. This must be done per tenant and must be performed every time the application permissions are changed.
</Info>

### Roles That Can Grant Admin Consent

**Privileged Role Administrator** (Recommended)

* Can grant consent for apps requesting **any permission, for any API**
* No limitations on API types or permission scopes
* Full admin consent capabilities

**Cloud Application Administrator**

* Can grant consent for apps requesting any permission for any API
* **Limitation:** Cannot grant consent for Microsoft Graph app roles (application permissions)
* Can grant all Microsoft Defender API permissions (uses WindowsDefenderATP API, not Microsoft Graph)

**Application Administrator**

* Can grant consent for apps requesting any permission for any API
* **Limitation:** Cannot grant consent for Microsoft Graph app roles (application permissions)
* Can grant all Microsoft Defender API permissions

**Global Administrator**

* Can grant consent for any application
* Has full access to all administrative features
* Can grant admin consent without restrictions

### Which Role to Use

<Info>
  **Recommendation:** Use a **Privileged Role Administrator**, **Cloud Application Administrator**, or **Global Administrator** account for the authorization in step 2. Since Microsoft Defender uses the WindowsDefenderATP API (not Microsoft Graph), the Cloud Application Administrator role has sufficient permissions.
</Info>

## Key Points

* Admin consent is required to grant application permissions to Microsoft Defender APIs
* The authorizing user must have one of the admin roles listed above
* Permissions must be explicitly granted even after application registration
* Admin consent must be re-granted if application permissions are changed

## Microsoft Defender App

Leen supports Microsoft Defender for Endpoint two ways: through Leen's own Microsoft Defender app,
or through an app registration the customer creates in their own tenant. Either authorizes Leen to
read the appropriate Microsoft Defender resources in the organization's account.

**Admin consent (the default).** Users authorize Leen's Microsoft Defender app, which is an OAuth2 app.
Leen takes care of the OAuth2 code-flow and access token management, so you don't have to worry about it.
Everything above about admin roles and consent applies to this route.

**Your own app registration.** The customer registers an application in their own Microsoft Entra tenant,
grants it the Defender permissions themselves, and supplies the tenant ID, application ID and client
secret. Leen then authenticates as that application. Nothing is redirected to Microsoft, so there is no
consent step for Leen to run and no `oauth2_authorize_url` in the response. See
[Connecting with your own app registration](#connecting-with-your-own-app-registration) below.

<Note>
  The two routes are mutually exclusive per connection. Supplying the three credential values selects
  the app-only route; omitting them selects admin consent. A connection created one way keeps that
  identity — an ordinary update cannot move it to the other.
</Note>

## Onboarding

Follow the steps below to onboard your environment to our Microsoft Defender app.

<Steps>
  <Step title="Create Microsoft Defender Connection">
    With your Leen API Key and your Customer's Org ID, make a API request to create a new Microsoft Defender Connection.
    More information can be found on the [API Reference page.](/api-reference/provisioning/add-new-connection)

    <Accordion title="Example POST body and response">
      ```json theme={null}
          {
            "vendor": "MS_DEFENDER_ENDPOINT"
          }
      ```

      The response will look like this:

      ```json theme={null}
        {
            "id": "c54de187-df62-4e95-b10f-0ab53b095d9d",
            "vendor": "MS_DEFENDER_ENDPOINT",
            "refresh_interval_secs": 14400,
            "timeout_secs": 1800,
            "organization_id": "fbd8b095-3c39-4137-9478-c32308444202",
            "oauth2_authorize_url": "https://login.microsoftonline.com/common/adminconsent?....."
        }
      ```
    </Accordion>
  </Step>

  <Step title="Granting permission to Leen app for Microsoft Defender">
    Open the `oauth2_authorize_url` from the previous step in a new tab.
    This will prompt the admin user to authorize Leen's Microsoft Defender app to access their Microsoft Defender resources.

    <img src="https://mintcdn.com/leen/vQ2Rhs44KY1LGMJC/images/ms_defender/permission_grant_page.png?fit=max&auto=format&n=vQ2Rhs44KY1LGMJC&q=85&s=26545908d2194c5b618462375276e4fe" alt="Microsoft Defender-auth" width="521" height="720" data-path="images/ms_defender/permission_grant_page.png" />

    Once the user has authorized the app, they will be redirected to Leen on a successful authorization.

    <img src="https://mintcdn.com/leen/vQ2Rhs44KY1LGMJC/images/ms_defender/successful_connection.png?fit=max&auto=format&n=vQ2Rhs44KY1LGMJC&q=85&s=61fd0c0fa6dd3807fdd50d4dd4c2178e" alt="Microsoft Defender-auth-success" width="1072" height="1236" data-path="images/ms_defender/successful_connection.png" />
  </Step>

  <Step title="Pull Data">
    Now that the user has authorized the app, you can pull data from Microsoft Defender using the `connection_id` from the first step.
    More information can be found on the [API Reference page.](/api-reference/appsec/get-issues)
  </Step>
</Steps>

## Connecting with your own app registration

Use this route when the customer would rather Leen authenticated as an application they own and
control, instead of granting consent to Leen's multi-tenant app. It is Microsoft's documented
"access without a user" flow — the customer registers the app, grants it the Defender permissions,
and consents to it themselves inside their own tenant.

<Info>
  Microsoft's own walkthrough for creating the app registration is
  [Create an app to access Microsoft Defender for Endpoint without a user](https://learn.microsoft.com/en-us/defender-endpoint/api/exposed-apis-create-app-webapp).
  The steps below cover what Leen needs from it.
</Info>

<Steps>
  <Step title="Register an application in Microsoft Entra">
    In the Azure portal, open **Microsoft Entra ID > App registrations > New registration**.
    Give it a name and register it. No redirect URI is required — this application never signs a
    user in.

    From the app's **Overview** page, note the **Application (client) ID** and the
    **Directory (tenant) ID**.
  </Step>

  <Step title="Grant the Defender API permissions">
    Under **API permissions**, add permissions for **APIs my organization uses > WindowsDefenderATP**,
    and choose **Application permissions** — not delegated. Leen reads alerts and machines, so
    `Alert.Read.All` and `Machine.Read.All` are the minimum.

    Then select **Grant admin consent** for the tenant. This is the same consent requirement
    described above; the difference is that it is granted against the customer's own application
    rather than Leen's.

    <Info>
      The roles listed under [Roles That Can Grant Admin Consent](#roles-that-can-grant-admin-consent)
      apply here too.
    </Info>
  </Step>

  <Step title="Create a client secret">
    Under **Certificates & secrets**, create a new client secret and copy its **Value** immediately.
    Azure shows the value only once; the Secret ID is not the value and cannot be used.

    <Warning>
      Client secrets expire. When the customer rotates the secret in Azure, the connection must be
      updated with the new value or syncs will begin failing at expiry.
    </Warning>
  </Step>

  <Step title="Create the Microsoft Defender connection">
    With your Leen API Key and your Customer's Org ID, make an API request to create a new
    Microsoft Defender Connection with the three values from the previous steps.
    More information can be found on the [API Reference page.](/api-reference/provisioning/add-new-connection)

    <Accordion title="Example POST body and response">
      ```json theme={null}
      {
          "vendor": "MS_DEFENDER_ENDPOINT",
          "credentials": {
              "tenant_id": "...",   // Directory (tenant) ID
              "client_id": "...",   // Application (client) ID
              "client_secret": "..." // the secret Value, not the Secret ID
          }
      }
      ```

      The response will look like this:

      ```json theme={null}
      {
          "id": "c54de187-df62-4e95-b10f-0ab53b095d9d",
          "vendor": "MS_DEFENDER_ENDPOINT",
          "refresh_interval_secs": 14400,
          "timeout_secs": 1800,
          "organization_id": "fbd8b095-3c39-4137-9478-c32308444202",
          "state": "ACTIVE"
      }
      ```

      Note there is no `oauth2_authorize_url`. The connection is active immediately — there is
      nothing for the customer to click through.
    </Accordion>

    <Note>
      All three values are required together. A partial credential is rejected rather than
      treated as an admin-consent connection, so a connection can never silently authenticate as
      the wrong application.
    </Note>
  </Step>

  <Step title="Pull Data">
    Pull data using the `connection_id` from the previous step, exactly as you would for a
    consent-based connection.
    More information can be found on the [API Reference page.](/api-reference/edr/get-alerts)
  </Step>
</Steps>

### Rotating the client secret

Send the full credential again — all three values — on an update to the connection. The stored
secret and the connection's recorded tenant move together.

One Microsoft tenant can hold at most one live Defender for Endpoint connection per organization. To
point an existing connection at a different tenant, update it with the new tenant's credentials
rather than creating a second connection.


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