Use SCIM provisioning to let your identity provider create, update and deactivate the SurrealDB accounts of a single sign-on connection. SCIM (System for Cross-domain Identity Management) is a standard protocol that identity providers use to keep user accounts in other apps up to date.
Without SCIM, SurrealDB makes an account the first time a person signs in, and the account stays until you disable it. With SCIM, your identity provider tells SurrealDB when a person joins, changes or leaves, so an account that you disable in your identity provider stops working in SurrealDB too.
Before you start
You need:
A single sign-on connection that works.
Permission to update identity providers in your enterprise.
An identity provider that supports SCIM 2.0, and access to its admin console.
SCIM is available for these connection types:
| Connection type | SCIM |
|---|---|
| Okta | Available |
| Microsoft Entra ID | Available |
| SAML | Available |
| OpenID Connect | Available |
| Google Workspace, ADFS, PingFederate, Keycloak | Not available |
Step 1: Turn on SCIM for the connection
Open Single sign-on in your enterprise.
Open the connection.
Open the Provisioning tab.
Turn on SCIM provisioning.
Studio then shows the SCIM base URL for the connection. Each connection has its own URL.
Step 2: Create a token
Your identity provider uses a bearer token to prove that it may change accounts.
On the Provisioning tab, select Create token.
Copy the token.
Select Done.
Studio shows the token one time only. Copy it before you select Done or leave the page. Anyone who has the token can create and deactivate accounts on this connection, so keep it in a secure place.
Step 3: Connect your identity provider
Each identity provider sets up SCIM in its own way, and each one must send the user ID that matches the identity people sign in with. Follow the instructions for your provider:
| Identity provider | Instructions |
|---|---|
| Okta | Provision users from Okta |
| Microsoft Entra ID | Provision users from Entra ID |
| Another SAML provider | Provision users over a SAML connection |
| Another OpenID Connect provider | Provision users over an OpenID Connect connection |
If the user ID that your identity provider sends over SCIM is different from the one it sends at sign-in, the person gets a second account the first time they sign in. Each provider's instructions say which attribute to send.
What SurrealDB does with each change
| Change in your identity provider | Result in SurrealDB |
|---|---|
| A person is assigned to the app | SurrealDB makes their account. They join the enterprise the first time they sign in. |
| A person's name or email changes | SurrealDB updates their account. |
| A person is deactivated or unassigned | SurrealDB disables their login and ends their sessions. The Members page shows them as Disabled. |
| A person is activated again | SurrealDB enables their login again. |
| A person is deleted | SurrealDB deletes their account. |
SCIM does not assign roles. A new member holds no roles until you grant them.
Rotate a token
A connection holds up to two tokens at a time. To replace a token without a gap in provisioning:
Create a new token.
Give the new token to your identity provider.
Beside the old token, select Revoke token.
The Provisioning tab shows when each token was last used, which helps you find a token that nothing uses any more.
Turn off SCIM
Turn off SCIM provisioning on the Provisioning tab. SurrealDB revokes every token of the connection, and your identity provider can no longer change accounts. The accounts that SCIM made stay, and people can still sign in through the connection.
Related pages
Single sign-on: Connect your identity provider and route people to it.
Members: Who belongs to the enterprise, and how to disable a login.
Roles: What a member may administer once they have signed in.