Skip to main content

​
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:

​
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. 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
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.