Connect Keycloak to SurrealDB to allow members of your organisation to sign in with the accounts in a Keycloak realm. The connection uses SAML. You create a SAML client in your realm, add a connection in SurrealDB Studio, and then finish the client with values from Studio.
Before you start, verify the email domain your company uses. You also need administrator access to the Keycloak realm.
The Keycloak client ID must be the connection's entity ID, which includes the connection's name. That name exists only after you create the connection, so the setup finishes in Keycloak.
Step 1: Collect the realm's SAML details
In the Keycloak admin console, select your realm.
Open Realm settings, then Keys, and copy the Certificate of the
RS256key.Note the realm's SAML endpoint, which has the form
https://keycloak.example.com/realms/<realm>/protocol/saml.
The certificate in Keycloak has no header or footer. Add -----BEGIN CERTIFICATE----- on the line before it and -----END CERTIFICATE----- on the line after it to make it PEM-encoded.
Step 2: Add the connection in SurrealDB
Open Single sign-on in your enterprise and add a new connection.
Select Keycloak.
Under Name the connection, enter a Display name. Members see this name on the sign-in screen.
Under Enter the Keycloak details, enter:
Sign-in URL: the realm's SAML endpoint from step 1.
Sign-out URL: optional. The realm's SAML endpoint also handles sign-out, so you can enter the same URL.
X.509 signing certificate: the PEM-encoded certificate from step 1.
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: Create the SAML client
The Set up Keycloak section of the Sign-on tab shows the values for the client, with a copy button beside each. <connection> is the connection's name.
| Value | Form |
|---|---|
| Entity ID | urn:auth0:auth0surrealdb:<connection> |
| Assertion Consumer Service (ACS) URL | https://auth.surrealdb.com/login/callback?connection=<connection> |
In your realm, open Clients and select Create client.
Set Client type to SAML.
Set Client ID to the entity ID.
Add the ACS URL under Valid redirect URIs.
Save the client.
Under Client scopes, map each person's email address to the NameID or to an email attribute. Setting Name ID format to email on the client's settings does this for the NameID.
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.