SSO to Databricks with Keycloak

This article 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, Databricks recommends keeping 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 SSO using OIDC

1. As an account owner or account admin, log in to the account console and click the Settings icon in the sidebar.

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. (For example, https://accounts.cloud.databricks.com/).

    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/auth/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.

18. 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, unified login is enabled on your account by default for all workspaces, new and existing, and it cannot be disabled. To configure unified login, see Enable unified login.

Enable Keycloak SSO using SAML

1. As an account owner or account admin, log in to the account console and click the Settings icon in the sidebar.

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 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:

    1. Single Sign-On URL: The Location attribute in the SingleSignOnService element that you copied above.

    2. Entity ID: The entityID attribute in the EntityDescriptor element that you copied above.

    3. X509Certificate: The X509Certificate tag that you copied above.

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.

19. 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, unified login is enabled on your account by default for all workspaces, new and existing, and it cannot be disabled. To configure unified login, see Enable unified login.