---
title: "Microsoft Entra ID"
description: "Configure Microsoft Entra ID (Azure Active Directory) as an identity provider for single sign-on in SurrealDB. Register an application in Entra and add a Microsoft Entra ID connection in SurrealDB Studio."
canonical_url: "https://surrealdb.com/docs/operate/enterprise/single-sign-on/microsoft-entra-id"
section: "Single sign-on"
surrealdb_version: "4.x"
last_modified: "2026-11-18T02:09:16Z"
---

> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Microsoft Entra ID

Configure Microsoft Entra ID (Azure Active Directory) as an identity provider for single sign-on in SurrealDB. Register an application in Entra and add a Microsoft Entra ID connection in SurrealDB Studio.

Connect Microsoft Entra ID (formerly Azure Active Directory) to SurrealDB to allow members of your organisation to sign in with their Microsoft accounts. You register an application in the Microsoft Entra admin center, then enter its details in a new connection in SurrealDB Studio.

Before you start, [verify the email domain](/docs/operate/enterprise/single-sign-on.md#step-1-verify-an-email-domain) your company uses. You also need an Entra account that can register applications.

If your company buys software through Azure, SurrealDB Cloud can be billed on your Azure account as well. See [Azure Marketplace](/docs/operate/organisations/azure-marketplace.md).

## Step 1: Register an application

1. In the Microsoft Entra admin center, open **Entra ID**, then **App registrations**.
2. Select **New registration**.

![The App registrations page in the Microsoft Entra admin center, with App registrations and New registration highlighted.](~/assets/img/surrealdb/manage/enterprise-sso-entra-1.webp)

3. Enter a **Name**, for example `SurrealDB`.
4. Under **Supported account types**, select **Single tenant only**, so that only accounts in your directory can sign in.
5. Under **Redirect URI**, select **Web** as the platform and enter `https://auth.surrealdb.com/login/callback`.
6. Select **Register**.

![The Register an application form in Entra, with the Web redirect URI and the Register button highlighted.](~/assets/img/surrealdb/manage/enterprise-sso-entra-2.webp)

## Step 2: Copy the application ID

Entra opens the **Overview** of the new application. Copy the **Application (client) ID**.

![The Overview page of the SurrealDB application in Entra, with the application (client) ID highlighted.](~/assets/img/surrealdb/manage/enterprise-sso-entra-3.webp)

## Step 3: Check the API permissions

Open **API permissions** and make sure the application has the delegated Microsoft Graph permission `User.Read`. A new registration usually has it already. If it is missing, select **Add a permission**, then **Microsoft Graph**, then **Delegated permissions**, and add `User.Read`.

## Step 4: Create a client secret

1. Open **Certificates & secrets**.
2. On the **Client secrets** tab, select **New client secret**.
3. Enter a **Description**, for example `SurrealDB`, and choose when it **Expires**.
4. Select **Add**.

![The Certificates & secrets page in Entra, with the Add a client secret panel open and the steps numbered.](~/assets/img/surrealdb/manage/enterprise-sso-entra-4.webp)

Copy the secret's **Value**, not its **Secret ID**. Entra shows the value only once, while you are still on the page.

> [!WARNING]
> Sign-in through this connection stops working on the date the client secret expires. Note the date, and create a new secret and update the connection in SurrealDB before then.

## Step 5: Add the connection in SurrealDB

1. Open **Single sign-on** in your enterprise and add a new connection.
2. Select **Microsoft Entra ID**.
3. Under **Name the connection**, enter a **Display name**. Members see this name on the sign-in screen.
4. Under **Enter the Microsoft Entra ID details**, enter:
    - **Directory domain**: a domain of your directory, for example `example.onmicrosoft.com`.
    - **Client ID**: the application (client) ID from step 2.
    - **Client secret**: the secret value from step 4.
5. Under **Route sign-in domains**, select the verified domains to send to this connection. This is optional, and you can change it later.
6. Select **Create connection**.

The **Set up Microsoft Entra ID** section of the form shows the redirect URI, with a copy button beside it, if you need it again.

![The New Microsoft Entra ID connection form in SurrealDB Studio, with the display name, directory domain, client ID, client secret and a routed domain filled in.](~/assets/img/surrealdb/manage/enterprise-sso-entra-5.webp)

SurrealDB stores the client secret securely and does not show it again.

## Step 6: Provision users with SCIM

With SCIM, Entra ID creates, updates and deactivates people's SurrealDB accounts. Skip this step if you do not want Entra ID to manage accounts.

Entra ID provisions users through an enterprise application. This is separate from the app registration that you made in step 1.

In Studio, [turn on SCIM and create a token](/docs/operate/enterprise/scim-provisioning.md) for this connection. Keep the **SCIM base URL** and the token ready.

1. In the Microsoft Entra admin center, open **Enterprise applications**, then select **New application**.
2. Select **Create your own application**.
3. Enter a name, for example `SurrealDB provisioning`.
4. Choose **Integrate any other application you don't find in the gallery**, then select **Create**.
5. Open **Provisioning**, and set **Provisioning Mode** to **Automatic**.
6. Set **Tenant URL** to the SCIM base URL, followed by `?aadOptscim062020`.
7. Set **Secret Token** to the token.
8. Select **Test Connection**, then **Save**.
9. Under **Mappings**, open the mapping for users.
10. Change the source attribute of `externalId` to `objectId`, then save.
11. Assign the same people or groups as the app registration.
12. Set **Provisioning Status** to **On**, then save.

> [!IMPORTANT]
> Map `objectId` to `externalId` before you turn provisioning on. SurrealDB identifies an Entra ID user by their object ID at sign-in. The default mapping sends a different value, and each person then gets a second account the first time they sign in.

The `?aadOptscim062020` suffix makes Entra ID follow the SCIM 2.0 standard for updates. Without it, some changes do not reach SurrealDB.

To try one person before everyone, open **Provisioning** and select **Provision on demand**.

## Next steps

- If you did not route a domain when you created the connection, [route one now](/docs/operate/enterprise/single-sign-on.md#step-3-route-domains-to-the-connection).
- [Choose the applications](/docs/operate/enterprise/single-sign-on.md#step-4-choose-the-applications) that people can sign in to with this connection.
- Read [what SurrealDB does with each SCIM change](/docs/operate/enterprise/scim-provisioning.md#what-surrealdb-does-with-each-change), and how to rotate a token.
