> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Keycloak

Configure Keycloak as an identity provider for single sign-on in SurrealDB. Create a SAML client in a Keycloak realm and add a Keycloak connection in SurrealDB Studio.

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](/docs/manage/enterprise/single-sign-on.md#step-1-verify-an-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

1. In the Keycloak admin console, select your realm.
2. Open **Realm settings**, then **Keys**, and copy the **Certificate** of the `RS256` key.
3. 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

1. Open **Single sign-on** in your enterprise and add a new connection.
2. Select **Keycloak**.
3. Under **Name the connection**, enter a **Display name**. Members see this name on the sign-in screen.
4. 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.
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. 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>`   |

1. In your realm, open **Clients** and select **Create client**.
2. Set **Client type** to **SAML**.
3. Set **Client ID** to the entity ID.
4. Add the ACS URL under **Valid redirect URIs**.
5. Save the client.
6. 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](/docs/manage/enterprise/single-sign-on.md#step-3-route-domains-to-the-connection). Then [choose the applications](/docs/manage/enterprise/single-sign-on.md#step-4-choose-the-applications) that people can sign in to with this connection.