Microsoft Entra ID

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

Step 1: Register an application

1. 1.

   In the Microsoft Entra admin center, open Entra ID, then App registrations.

2. 2.

   Select New registration.

3. 3.

   Enter a Name, for example SurrealDB.

4. 4.

   Under Supported account types, select Single tenant only, so that only accounts in your directory can sign in.

5. 5.

   Under Redirect URI, select Web as the platform and enter https://auth.surrealdb.com/login/callback.

6. 6.

   Select Register.

Step 2: Copy the application ID

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

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

   Open Certificates & secrets.

2. 2.

   On the Client secrets tab, select New client secret.

3. 3.

   Enter a Description, for example SurrealDB, and choose when it Expires.

4. 4.

   Select Add.

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

Step 5: Add the connection in SurrealDB

1. 1.

   Open Single sign-on in your enterprise and add a new connection.

2. 2.

   Select Microsoft Entra ID.

3. 3.

   Under Name the connection, enter a Display name. Members see this name on the sign-in screen.

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

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 for this connection. Keep the SCIM base URL and the token ready.

1. 1.

   In the Microsoft Entra admin center, open Enterprise applications, then select New application.

2. 2.

   Select Create your own application.

3. 3.

   Enter a name, for example SurrealDB provisioning.

4. 4.

   Choose Integrate any other application you don't find in the gallery, then select Create.

5. 5.

   Open Provisioning, and set Provisioning Mode to Automatic.

6. 6.

   Set Tenant URL to the SCIM base URL, followed by ?aadOptscim062020.

7. 7.

   Set Secret Token to the token.

8. 8.

   Select Test Connection, then Save.

9. 9.

   Under Mappings, open the mapping for users.

10. 10.

    Change the source attribute of externalId to objectId, then save.

11. 11.

    Assign the same people or groups as the app registration.

12. 12.

    Set Provisioning Status to On, then save.

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.

• •

  Choose the applications that people can sign in to with this connection.

• •

  Read what SurrealDB does with each SCIM change, and how to rotate a token.