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

# Microsoft App Registration setup

> Create the Microsoft Entra app registration Driftmark uses to read tenant configuration.

# Microsoft App Registration setup

Driftmark connects to a Microsoft tenant by using an application registration with Microsoft Graph **application permissions**.

This is the recommended setup when Driftmark runs scheduled snapshots and reports without an interactive user present.

## Before you start

You need:

* access to the Microsoft Entra admin center for the tenant you want to monitor
* permission to create or manage app registrations
* permission to grant admin consent for Microsoft Graph application permissions

Microsoft documents app registration, API permissions, and admin consent here:

* [Register an application in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app)
* [Update an app's requested permissions](https://learn.microsoft.com/en-us/entra/identity-platform/howto-update-permissions)
* [Request application permissions and admin consent](https://learn.microsoft.com/en-us/entra/identity-platform/consent-types-developer)

## 1. Create the app registration

In the Microsoft Entra admin center:

1. Go to **Entra ID -> App registrations**.
2. Select **New registration**.
3. Enter a name such as `Driftmark - Production` or `Driftmark - <tenant name>`.
4. Leave the app as **single tenant** unless you have a very specific reason not to.
5. Redirect URI is not required for Driftmark tenant snapshots.
6. Create the app.

After creation, record:

* **Application (client) ID**
* **Directory (tenant) ID**

These are required in Driftmark when you add the tenant connection.

## 2. Create a client secret

From the app registration:

1. Open **Certificates & secrets**.
2. Choose **New client secret**.
3. Add a description and expiration period that matches your security policy.
4. Save it and copy the secret value immediately.

You will use that value as the **Client Secret** in Driftmark.

## 3. Add Microsoft Graph application permissions

From the app registration:

1. Open **API permissions**.
2. Select **Add a permission**.
3. Choose **Microsoft Graph**.
4. Choose **Application permissions**.
5. Add the minimum required permission:

`Organization.Read.All`

This is the minimum permission required for Driftmark to validate and connect a tenant.

## 4. Add permissions required by your selected Driftmark template

Driftmark templates determine what configuration areas are collected. Each enabled control can require additional Graph application permissions.

Minimum permission required to integrate Driftmark with your tenant:

`Organization.Read.All`

Other common permissions needed for Driftmark snapshots include, but not limited to:

`User.Read.All`
`Group.Read.All`
`Directory.Read.All`
`Application.Read.All`
`Policy.Read.All`
`EntitlementManagement.Read.All`
`RoleManagement.Read.Directory`

The exact required set depends on which controls are enabled in the selected template.

## 5. Grant admin consent

After adding permissions:

1. Stay on **API permissions**.
2. Select **Grant admin consent for `<tenant name>`**.
3. Confirm the consent action.
4. Refresh the page and verify the permissions show as granted.

This step is required because Driftmark uses **application permissions**, and Microsoft documents that application permissions require administrator consent.

## 6. Add the tenant in Driftmark

In Driftmark:

1. Go to **Settings -> Integrations -> Microsoft**.
2. Choose **Add tenant**.
3. Enter:
   * Tenant ID
   * Client ID
   * Client Secret
   * optional label
4. Save the connection.

Driftmark validates the credentials when saving the tenant.

## Minimum permissions vs full monitoring

### Minimum connection permission

At minimum, Driftmark needs:

* `Organization.Read.All`

That is enough for initial connection validation and basic organization-level data.

### Additional permissions for broader monitoring

To collect more than basic organization data, add the permissions required by the controls in your selected template.

Examples:

* **Directory** controls:
  * `User.Read.All`
  * `Group.Read.All`
* **Identity and access** controls:
  * `Directory.Read.All`
  * `User.Read.All`
* **Applications** controls:
  * `Application.Read.All`
* **Security settings** controls:
  * `Policy.Read.All`

## Recommended operational model

For production, use:

* one dedicated app registration per monitored tenant
* a clear naming convention
* a defined secret rotation process
* templates that match your actual review scope

This makes it easier to:

* rotate secrets safely
* audit permissions
* isolate tenant-specific failures

## Troubleshooting

### Connection validation fails

Check:

* tenant ID, client ID, and client secret are correct
* the secret value was copied, not the secret ID
* admin consent was granted
* the app has at least `Organization.Read.All`

### A snapshot works for some controls but not others

That usually means the selected template requires additional Graph application permissions that are not yet assigned to the app registration.

Compare the template’s enabled controls to the required permissions listed in Driftmark.