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

# Microsoft Entra ID (Client Credentials)

> Connect Microsoft Entra ID using client credentials to import user, security alert, and device data.

export const ConnectInPlatform = ({tile, children}) => <Step title="Enter the credentials in the Living Security Platform">
    <p>
      Completed by whoever holds Living Security access — the program owner, or the system
      admin if they've been invited (delegated setup).
    </p>
    <ol>
      <li>
        Go to <strong>Settings → Integrations → Catalog</strong>, find the{' '}
        <strong>{tile}</strong> tile, click <strong>Connect</strong>.
      </li>
      <li>
        Fill in the fields below, then click <strong>Connect</strong>.
      </li>
    </ol>
    {children}
  </Step>;

export const SystemAdminBanner = ({system, recommendDelegated}) => <Note>
    <p>
      <strong>This guide is for your {system} administrator.</strong> It covers creating API
      credentials inside {system}, which requires admin access to {system} — not to the
      Living Security Platform.
    </p>
    <p>
      If you're the Living Security <strong>program owner</strong> and don't administer {system},
      send this page to whoever does. They complete Part A and hand the credentials back to you
      (or enter them directly if you've invited them into the platform).
      {recommendDelegated && <>
          {' '}Because setup produces sensitive key material, we recommend the{' '}
          <strong>delegated setup</strong> path so the secret is never sent back to you.
        </>}
    </p>
  </Note>;

<SystemAdminBanner system="Microsoft Entra ID" recommendDelegated={true} />

## What Living Security needs

| Credential         | Description                                                                                                  |
| ------------------ | ------------------------------------------------------------------------------------------------------------ |
| **Tenant ID**      | The directory (tenant) UUID from your Microsoft Entra admin center                                           |
| **Client ID**      | The application (client) UUID assigned when you register the app                                             |
| **Client Secret**  | A secret credential generated under your app registration — the connect dialog labels this field **API Key** |
| **Graph API host** | The Microsoft Graph hostname (commercial: `graph.microsoft.com`)                                             |
| **Authority host** | The Microsoft Entra authority hostname (commercial: `login.microsoftonline.com`)                             |

**Scopes (Application permissions):**

| Permission                                | Used for                                  |
| ----------------------------------------- | ----------------------------------------- |
| `User.Read.All`                           | User directory                            |
| `SecurityAlert.Read.All`                  | Security alerts                           |
| `AuditLog.Read.All`                       | Sign-in logs and MFA registration details |
| `DeviceManagementManagedDevices.Read.All` | Intune managed devices                    |

**Required role:** **Application Administrator** or **Global Administrator** in Microsoft Entra ID

### Prerequisites

* You must have **Application Administrator** or **Global Administrator** access in Microsoft Entra ID to register applications and grant admin consent.

***

## Part A — In Microsoft Entra ID

*Your Microsoft Entra ID administrator completes these steps.*

<Steps>
  <Step title="Register a new application">
    1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com).
    2. In the left navigation, browse to **Entra ID** → **App registrations**.
    3. Click **New registration**.
    4. Enter a meaningful name for the app, such as `Living Security Platform`.
    5. Under **Supported account types**, select **Accounts in this organizational directory only**.
    6. Leave **Redirect URI** blank — this integration uses the client credentials flow.
    7. Click **Register**.

    After registration, record the following values from the **Overview** page:

    * **Application (client) ID**
    * **Directory (tenant) ID**
  </Step>

  <Step title="Add Microsoft Graph application permissions">
    1. On your app's **Overview** page, click **API permissions** in the left menu.
    2. Click **Add a permission**.
    3. Select **Microsoft Graph**.
    4. Select **Application permissions**.
    5. Search for and select each permission below, then click **Add permissions**:
       * `User.Read.All`
       * `SecurityAlert.Read.All`
       * `AuditLog.Read.All`
       * `DeviceManagementManagedDevices.Read.All`

    <Note>
      These are the minimum permissions for all data streams. If you only intend to enable a subset of streams, you can omit permissions for streams you won't use.
    </Note>
  </Step>

  <Step title="Grant admin consent">
    Application permissions require explicit admin consent.

    1. On the **API permissions** page, click **Grant admin consent for \<your tenant name>**.
    2. In the confirmation dialog, click **Yes**.
    3. Verify that every permission shows **Granted** under the **Status** column.

    <Note>
      If the **Grant admin consent** button is grayed out, you need **Privileged Role Administrator** or **Global Administrator** privileges. Admin consent must be re-granted any time you add new permissions.
    </Note>
  </Step>

  <Step title="Create a client secret">
    1. On your app's **Overview** page, click **Certificates & secrets** in the left menu.
    2. Click the **Client secrets** tab, then click **New client secret**.
    3. Enter a description (e.g., `Living Security Platform`).
    4. Choose an expiration that matches your rotation policy.
    5. Click **Add**.

    <Warning>
      **Copy the secret value immediately.** Microsoft Entra ID displays the full client secret only once. If you navigate away before copying it, you must delete the secret and create a new one.
    </Warning>

    Store the secret securely. Set a calendar reminder to rotate it before expiration — an expired secret causes syncs to fail with `401 Unauthorized`.
  </Step>

  <Step title="Determine the Graph API and Authority hosts">
    For most organizations on the commercial cloud, use the defaults:

    | Field              | Commercial cloud value      |
    | ------------------ | --------------------------- |
    | **Graph API host** | `graph.microsoft.com`       |
    | **Authority host** | `login.microsoftonline.com` |

    For government or sovereign clouds, use the appropriate endpoints for your environment.

    <Note>
      The Graph API host and Authority host must match — tokens from one cloud's authority are not valid for another cloud's Graph endpoint.
    </Note>
  </Step>
</Steps>

***

## Part B — In the Living Security Platform

*The program owner completes this step, or the system admin if using delegated setup.*

<Steps>
  <ConnectInPlatform tile="Microsoft Entra ID (CC)">
    | Field               | Value                                                  |
    | ------------------- | ------------------------------------------------------ |
    | **API Key**         | The Client Secret from Part A, Step 4                  |
    | **Azure tenant ID** | The Directory (tenant) ID from Part A, Step 1          |
    | **Client ID**       | The Application (client) ID from Part A, Step 1        |
    | **Graph API host**  | `graph.microsoft.com` (or your cloud's endpoint)       |
    | **Authority host**  | `login.microsoftonline.com` (or your cloud's endpoint) |

    <img src="https://mintcdn.com/livingsecurity/oVkrOMkYmNevekTI/integrations/images/microsoft-entra-id-cc/connect-dialog.png?fit=max&auto=format&n=oVkrOMkYmNevekTI&q=85&s=2a192b0a28e753ad0e0bc0b640508136" alt="Living Security connect dialog for Microsoft Entra ID" style={{maxWidth: "450px"}} width="576" height="692" data-path="integrations/images/microsoft-entra-id-cc/connect-dialog.png" />
  </ConnectInPlatform>
</Steps>

You are now connected to Microsoft Entra ID (Client Credentials).

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    The credentials are invalid or expired. Check:

    1. Client Secret has not expired or been rotated
    2. Tenant ID and Client ID are correct
    3. Authority host matches your cloud environment
  </Accordion>

  <Accordion title="403 Forbidden">
    The app registration is missing permissions or admin consent was not granted. Verify:

    1. All required permissions are listed in **API permissions**
    2. Each permission shows **Granted** status (green checkmark)
    3. Admin consent was granted after adding permissions

    <Note>
      If you added new permissions after initial consent, you must re-grant admin consent.
    </Note>
  </Accordion>

  <Accordion title="Empty results for specific data streams">
    The app may be missing the specific permission for that stream:

    * No users → missing `User.Read.All`
    * No security alerts → missing `SecurityAlert.Read.All`
    * No sign-in logs → missing `AuditLog.Read.All`
    * No devices → missing `DeviceManagementManagedDevices.Read.All`
  </Accordion>

  <Accordion title="Token request fails with invalid_client">
    The Graph API host and Authority host may be mismatched. Both must correspond to the same cloud environment (commercial, government, etc.).
  </Accordion>
</AccordionGroup>