Single sign-on

Single sign-on lets people at your company sign in to SurrealDB with the credentials they already hold, instead of creating a SurrealDB account of their own.

Sign-in is routed by email domain. A person enters their email address, SurrealDB matches the domain against the connections you have configured, and sends them to your identity provider to authenticate. Your identity provider decides whether they may sign in, and returns them to SurrealDB.

Three things must be in place before anyone is routed, and each has a step below:

1. 1.

   A domain you have verified, which proves your company owns the email addresses.

2. 2.

   A connection to your identity provider, which holds the credentials and endpoints.

3. 3.

   A route from the domain to the connection, which ties the two together.

Step 1: Verify an email domain

A verified domain is what lets single sign-on recognise your company's email addresses. Add the domain your company's addresses use, then prove you own it with a DNS record.

1. 1.

   Open Domains in your enterprise.

2. 2.

   Select Add domain.

3. 3.

   Enter the domain, for example example.com.

4. 4.

   Select Add domain to save it.

Studio then shows a DNS record for the domain. Add that record to your DNS, with the name and value exactly as shown, and then:

1. 1.

   Wait for the record to propagate.

2. 2.

   Select Verify beside the domain.

The domain is marked as verified when the record is found. If it is not found yet, Studio says so and you can try again. DNS changes can take a while to reach every resolver, so a verification that fails immediately after you add the record is worth repeating later.

Removing a domain stops any connection routing it from matching that domain and people will no longer be routed to your identity provider.

Step 2: Add a connection

A connection holds the credentials and endpoints of your identity provider. Select your identity provider from the grid below for detailed instructions on how to set it up.

Google Workspace

Google Apps

Microsoft Entra ID

Azure Active Directory

Okta

Okta Workforce

ADFS

Active Directory Federation Services

PingFederate

Ping Identity

Keycloak

Keycloak SAML

SAML

Generic SAML 2.0

OpenID Connect

Generic OIDC

Use SAML or OpenID Connect when your identity provider is not listed by name. Most identity providers speak one of the two, and a generic connection reaches the same result as a named one. The named entries exist to label the fields in the words your provider uses.

Step 3: Route domains to the connection

Routing decides who is sent to the connection.

1. 1.

   Open the connection from the Single sign-on list.

2. 2.

   Under Sign-in domains on the Sign-on tab, select the verified domains to route.

3. 3.

   Select Save changes.

People with an email address at those domains are then sent to this connection when they sign in. Only verified domains can be selected, so complete step 1 first.

You can route more than one domain to each connection, which suits a company that holds several email domains. Route each domain to the connection that authenticates it.

Step 4: Choose the applications

A connection can be limited per SurrealDB application rather than all of them. Trying to sign in to an application that doesn't have any identity providers enabled for their domain will push them to sign in with a normal SurrealDB account and will not be redirected to your identity provider.

After single sign-on is working

People at a routed domain are sent to your identity provider whenever they sign in. Their membership then comes from your identity provider, and you grant their access inside SurrealDB with roles.

The Members page will automatically show members that have signed in through an identity provider that you own but will not have any permissions unless they are granted to them. To prevent users from being added automatically, you must manage access externally via your identity provider.

Related pages

• •

  Members: Who belongs to the enterprise, and how they get there.

• •

  Roles: What a member may administer once they have signed in.

• •

  Accounts and sign-in: Signing in without an enterprise.