SSO to Databricks with Keycloak

This page shows how to configure Keycloak as the identity provider for single sign-on (SSO) in your Databricks account. Keycloak supports both OpenID Connect (OIDC) and SAML 2.0. Keycloak does not support SCIM to sync users and groups to Databricks.

warning

To prevent getting locked out of Databricks during single sign-on testing, keep the account console open in a different browser window. You can also configure emergency access with security keys to prevent lockout. See Emergency access to prevent lockouts.

Enable Keycloak single sign-on

Choose your identity protocol:

OIDC

1. As an account admin, log in to the account console and click Security.

2. Click the Authentication tab.

3. Next to Authentication, click Manage.

4. Choose Single sign-on with my identity provider.

5. Click Continue.

6. Under Identity protocol, select OpenID Connect.

7. On the Authentication tab, make note of the Databricks Redirect URL value.

8. In a new browser tab, log in to your Keycloak admin console.

9. Select the realm for Databricks integration or create a new one.

10. Create a new client:

    1. Click Clients and click Create client.

    2. In Client type, select OpenID Connect.

    3. Enter a Client ID and Name.

    4. Click Next and Save.

       

11. Configure the Databricks client:

    1. In Access Settings, set Home URL to your Databricks account URL.
    2. Set Valid redirect URIs to the Databricks Redirect URL you copied above.
    3. In Capability config, set Client authentication to On for confidential access.

    

12. Set up group membership mapping:

    1. Click Client scopes and select the dedicated scope for your client.
    2. In the Mappers tab, click Configure a new mapper.
    3. In Mapper type, select Group Membership.
    4. Set both Name and Token Claim Name to groups.
    5. Toggle Full group path to On or Off based on your preference.

    

13. Return to the Databricks account console Authentication tab and enter values you copied from Keycloak:

    1. Client ID: The Client ID from Keycloak.
    2. Client secret: Found in the Credentials tab of your Keycloak client.
    3. OpenID issuer URL: Your Keycloak URL with realm (For example, https://keycloak.example.com/realms/your-realm).

14. Click Save.

15. Click Test SSO to validate that your SSO configuration is working properly.

16. Click Enable SSO to enable single sign-on for your account.

17. Test account console login with SSO.

SAML 2.0

1. As an account admin, log in to the account console and click Security.

2. Click the Authentication tab.

3. Next to Authentication, click Manage.

4. Choose Single sign-on with my identity provider.

5. Click Continue.

6. Under Identity protocol, select SAML 2.0.

7. On the Authentication tab, make note of the Databricks Redirect URL value.

   

8. In a new browser tab, log in to your Keycloak admin console.

9. Select the realm for Databricks integration or create a new one.

10. Create a new client:

    1. Click Clients and click Create client.
    2. In Client type, select SAML.
    3. Enter a Client ID and Name.
    4. Click Next and Save.
    5. In login settings, set Valid redirect URIs to the Databricks Redirect URL you copied above.

    

11. Configure the client:

    1. In the Settings tab under SAML capabilities, set Name ID format to email.
    2. Turn on Force name ID format.
    3. Click Save.

    

12. Set up SAML attribute mapping:

    1. Click Client scopes and select the dedicated scope for your client.
    2. On the Mappers tab, click Add predefined mapper.
    3. Select X500 email, X500 givenName, and X500 surname and click Add.

    

13. Retrieve SAML metadata:

    1. Click Realm settings and General.
    2. Click on SAML 2.0 Identity Provider Metadata.
    3. From the metadata, save the following values:
    • The Location attribute in the SingleSignOnService element (For example, https://my-idp.example.com/realms/DatabricksRealm/protocol/saml). This is the Single Sign-On URL in Databricks
    • The entityID attribute in the EntityDescriptor element (For example, https://my-idp.example.com/realms/DatabricksRealm).
    • The X509Certificate tag.

14. Return to the Databricks account console Authentication tab and enter values you copied from Keycloak:

    • Single Sign-On URL: The Location attribute in the SingleSignOnService element
    • Identity Provider Entity ID: The entityID attribute in the EntityDescriptor element
    • x.509 Certificate: The X509Certificate tag

15. Click Save.

16. Click Test SSO to validate that your SSO configuration is working properly.

17. Click Enable SSO to enable single sign-on for your account.

18. Test account console login with SSO.

Configure unified login and add users to Databricks

After you configure SSO, Databricks recommends that you configure unified login and add users to your account using SCIM provisioning.

1. Configure unified login

   Unified login allows you to use the account console SSO configuration in your Databricks workspaces. If your account was created after June 21, 2023 or you did not configure SSO before December 12, 2024, unified login is enabled on your account for all workspaces and it cannot be disabled. To configure unified login, see Enable unified login.

2. Add users to Databricks

   1. Enable JIT provisioning

      Databricks recommends enabling JIT to automatically add users to Databricks when they first log in using SSO. JIT provisioning is on by default for accounts created after May 1, 2025 when SSO is configured. See Automatically provision users (JIT).

   2. Configure SCIM provisioning

      Databricks recommends using SCIM provisioning to sync users and groups automatically from your identity provider to your Databricks account. SCIM streamlines onboarding a new employee or team by using your identity provider to create users and groups in Databricks and give them the proper level of access. See Sync users and groups from your identity provider using SCIM.