Connect any identity provider that supports SAML 2.0 to SurrealDB. Use this connection when your provider is not listed by name. You create a SAML application in your identity provider, add a connection in SurrealDB Studio, and then finish the application with values from the connection.
Before you start, verify the email domain your company uses.
A SAML connection is set up in this order because the values your identity provider needs from SurrealDB include the connection's name, which exists only after you create the connection.
Step 1: Create a SAML application
In your identity provider, create a SAML 2.0 application.
Send each person's email address as the NameID, or as an email attribute.
Copy the provider's single sign-on URL and its X.509 signing certificate.
Some providers ask for an ACS URL and an entity ID before they save the application. If yours does, enter a temporary value such as https://auth.surrealdb.com/login/callback and replace it in step 3.
Step 2: Add the connection in SurrealDB
Open Single sign-on in your enterprise and add a new connection.
Select SAML.
Under Name the connection, enter a Display name. Members see this name on the sign-in screen.
Under Enter the SAML details, enter:
Sign-in URL: the provider's single sign-on URL, for example
https://idp.example.com/sso/saml.Sign-out URL: optional. The provider's single logout URL.
X.509 signing certificate: the PEM-encoded certificate, starting with
-----BEGIN CERTIFICATE-----.
Under Route sign-in domains, select the verified domains to send to this connection. This is optional, and you can change it later.
Select Create connection.
Studio opens the Sign-on tab of the new connection.
Step 3: Finish the SAML application
The Set up SAML section of the Sign-on tab shows three values, with a copy button beside each. <connection> is the connection's name, which is also shown on the General tab.
| Value | Also called | Form |
|---|---|---|
| Assertion Consumer Service (ACS) URL | Reply URL, single sign-on URL | https://auth.surrealdb.com/login/callback?connection=<connection> |
| Entity ID | Audience, SP entity ID | urn:auth0:auth0surrealdb:<connection> |
| Metadata URL | https://auth.surrealdb.com/samlp/metadata?connection=<connection> |
Enter the ACS URL and the entity ID in the SAML application. If your provider can import service provider metadata, give it the metadata URL instead, which contains both.
Copy the values from Studio rather than building them by hand, so the connection name is exact.
Step 4: Provision users with SCIM
If your identity provider supports SCIM 2.0, it can create, update and deactivate people's SurrealDB accounts. Skip this step if you do not want it to manage accounts.
In Studio, turn on SCIM and create a token for this connection. Keep the SCIM base URL and the token ready.
Most providers set up SCIM on the same app as SAML, in a section called Provisioning. Give it these values:
| Setting | Value |
|---|---|
| Base URL, or tenant URL | The SCIM base URL |
| Authentication | Bearer token |
| Token | The token from Studio |
| Objects to manage | Users |
userName | The same value that your provider sends as the name ID in the SAML assertion |
SurrealDB identifies a person on a SAML connection by the SCIM userName. It must be the same as the name ID that your provider sends at sign-in. If the two are different, the person gets a second account the first time they sign in.
Next steps
If you did not route a domain when you created the connection, route one now. Then choose the applications that people can sign in to with this connection.