This guide walks you through creating an Entra ID application and service principal, and gathering the configuration needed to create an Entra ID integration.

## Create an Entra ID Application and Service Principal

Before you begin, please make sure your [Entra ID tenant](https://learn.microsoft.com/en-us/entra/fundamentals/create-new-tenant) has a [P1 or P2 premium subscription](https://learn.microsoft.com/en-us/entra/fundamentals/get-started-premium). If your tenant does not support [advanced query capabilities](https://learn.microsoft.com/en-us/graph/aad-advanced-queries?tabs=http#query-scenarios-that-require-advanced-query-capabilities) (i.e. Azure AD B2C tenants), filtering related functionality may not work correctly.

The Query Risk Events and Query Risky Users operations surface [Microsoft Entra ID Protection](https://learn.microsoft.com/en-us/entra/id-protection/overview-identity-protection) data, which requires an [Entra ID P2](https://learn.microsoft.com/en-us/entra/fundamentals/licensing) license on the tenant. Tenants without P2 can still use the rest of this integration; only Query Risk Events and Query Risky Users will return no data.

### 1. Create an application and service principal

Follow the microsoft documentation to [create a Microsoft Entra application and service principal that can access resources](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal). Since there is no need for users to sign in to this application directly, you can choose ‘Single-page application (SPA)’ for the redirect URI and leave it blank.

Once your Entra ID Application is created you will see your ‘Application (client) ID’ and the ‘Directory (tenant) ID’ on the Overview tab. Copy these values to a safe location.

### 2. Create an application client secret

Navigate to **Manage** > **Certificates and secrets** and [add a new client secret](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#option-3-create-a-new-client-secret).

Copy the secret to a safe location beside your client ID and tenant ID. You will not have access the secret value again.

### 3. Assign application permissions

Follow the Microsoft documentation to [assign app roles to the application](https://learn.microsoft.com/en-us/entra/identity-platform/howto-add-app-roles-in-apps#assign-app-roles-to-applications). You will need to grant admin consent before these roles are fully available for use.

Assign these **Application** permissions in the **Microsoft Graph** API section. All of the names below are Application permissions (not Delegated).

| Permission | Required for | Notes |
|  --- | --- | --- |
| `Directory.Read.All` | Query Users, Get User, Query Groups, Get Group, Query Group Members | Read users, groups, group members, and directory roles. Prefer this over separate `User.Read.All` / `Group.Read.All` / `GroupMember.Read.All` unless you need least-privilege splitting. |
| `AuditLog.Read.All` | Query Audit Log, Query Users, Get User | Covers directory audit logs and sign-in logs. Also required for the Graph `signInActivity` property returned on Query Users and Get User. |
| `UserAuthenticationMethod.Read.All` | Get User | Read authentication methods returned with the user. Read is enough; write is not used. |
| `User.ReadWrite.All` | Disable User, Enable User, Expire All User Sessions | Account write actions. Sensitive session updates may also require an Entra admin role (for example User Administrator) on the service principal. |
| `IdentityRiskEvent.Read.All` | Query Risk Events | Optional. Requires an Entra ID **P2** tenant. Without P2 this operation returns no data. |
| `IdentityRiskyUser.Read.All` | Query Risky Users | Optional. Also used for risk enrichment on Get User. Requires an Entra ID **P2** tenant. Without P2 these fields are omitted / return no data. |


Do **not** assign:

- `User.Read` — that is a Delegated permission and is not valid for this client-credentials integration.
- `Group.ReadWrite.All` / `GroupMember.ReadWrite.All` — the connector only reads groups and members; it does not create, update, or change membership.
- `UserAuthenticationMethod.ReadWrite.All` — the connector only reads authentication methods.
- `RoleManagementPolicy.Read` — this permission does not exist in Microsoft Graph.


Query Users also requests the Graph `signInActivity` property, which requires an Entra ID **P1 or P2** license on the tenant (see the prerequisites above).

## Configure the Integration

Create your integration by supplying the following configuration values.

| Integration Parameter | Description |
|  --- | --- |
| Region | Government cloud selector. Defaults to `global` (commercial Microsoft Graph). Use `gcc_high` for US Government GCC High or `dod` for US Government DoD. Do **not** use `us` for government cloud—that value maps to commercial Graph endpoints. See [Government cloud regions](#government-cloud-regions) below. |
| Tenant ID | This is the 'Directory (tenant) ID' gathered in step 1. |
| URL (Optional) | Advanced override for the Graph API base URL. Leave blank to use the URL derived from **Region** (recommended). Only set this when you need a custom Graph endpoint that `region` does not cover. This is the root URL without paths, for example `https://graph.microsoft.com/`. |
| Token URL (Optional) | Advanced override for the OAuth token endpoint. Leave blank to use the login URL derived from **Region** (recommended). Only set this for custom deployments. When set, use the full token endpoint URL with your tenant ID, for example `https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/oauth2/v2.0/token`. |
| Client ID | This is the 'Application (client) ID' gathered in step 1. |
| Client Secret | This is the client secret gathered in step 2. |


### Government cloud regions

| Region value | Use for | Graph base URL | Login |
|  --- | --- | --- | --- |
| `global` | Commercial tenants (default) | `https://graph.microsoft.com` | `login.microsoftonline.com` |
| `us`, `uk`, `eu`, `gcc` | Commercial Graph (same endpoints as `global` for this integration) | `https://graph.microsoft.com` | `login.microsoftonline.com` |
| `gcc_high` | US Government GCC High (L4) | `https://graph.microsoft.us` | `login.microsoftonline.us` |
| `dod` | US Government DoD (L5) | `https://dod-graph.microsoft.us` | `login.microsoftonline.us` |


For US Government tenants, set `region` to `gcc_high` (GCC High) or `dod` (Department of Defense). When either value is used, Synqly derives the Graph URL, OAuth scope, and login endpoint automatically. You normally do **not** need to set **URL** or **Token URL** manually.

Example integration config for GCC High:


```json
{
  "provider_config": {
    "type": "identity_entra_id",
    "tenant_id": "<tenant-id>",
    "region": "gcc_high",
    "credential": {
      "type": "o_auth_client",
      "client_id": "<client-id>",
      "client_secret": "<client-secret>"
    }
  }
}
```

See [Microsoft national cloud deployments](https://learn.microsoft.com/en-us/graph/deployments) for more on Graph endpoints per cloud.