Configure SSO using OIDC

This article shows how to generally configure single sign-on (SSO) to authenticate to the account console and Databricks workspaces using OIDC. For a demo of configuring OIDC SSO with Okta, see Secure Your Databricks Access with OIDC SSO.

For an overview of single sign-on in the account, see Configure SSO in Databricks.

Enable SSO using OIDC

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.

1. As an 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. Copy the value in the Databricks Redirect URL field.

   

8. Go to your identity provider and create a new client application (web), entering the Databricks Redirect URL value in the appropriate field in the identity provider configuration interface.

   Your identity provider should have documentation to guide you through this process.

9. Copy the client ID, client secret, and OpenID issuer URL generated by the identity provider for the application.

   • Client ID is the unique identifier for the Databricks application you created in your identity provider. This is sometimes referred to as the Application ID.

   • Client secret is a secret or password generated for the Databricks application that you created. It is used to authorize Databricks with your identity provider.

   • Issuer URL is the prefix of the URL at which your identity-provider's OpenID Configuration Document can be found. That OpenID Configuration Document must found be in {issuer-url}/.well-known/openid-configuration.

     Remove the /.well-known/openid-configuration ending from the URL. You can specify query parameters by appending them to the issuer URL, for example {issuer-url}?appid=123.

10. Return to the Databricks account console Authentication tab and enter values you copied from the identity provider application to the Client ID, Client secret, and OpenID issuer URL fields.

11. Optionally, enter a Username claim if you want to use a claim other than email as users' Databricks usernames. See your identity provider's documentation for specific information on claim values.

    

12. Click Save.

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

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

15. Test account console login with SSO.

16. Grant all account users access to the Databricks application in your identity provider. You might need to modify the access permissions for the application.

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

   You must add users to Databricks in order for them to log in. 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.

Troubleshooting OIDC SSO

The following table lists OIDC error codes that might be encountered during SSO authentication. Each entry provides the error code, machine-readable error name, a detailed explanation, and recommended next steps for troubleshooting. Use this information to quickly identify and resolve OIDC authentication issues in your workspace.

Error Code	Explanation	Next steps
oidc_login_error	A generic login error occurred.	Obtain the request ID to identify which requests failed.
oidc_state_missing	The state parameter is missing in the IdP's response or does not match what Databricks sent. This can also occur if you configure an IdP-initiated OIDC flow, which is not supported. The state parameter helps prevent cross-site request forgery (CSRF).	Check the IdP configuration to ensure the state parameter is returned and matches the request.
oidc_nonce_missing	The nonce parameter is missing from the Databricks request. This might happen the nonce cookie expired, or if the cookie is missing entirely. The nonce parameter prevents replay attacks by ensuring the token from the IdP matches the request initiated by Databricks.	Inspect your network traffic to verify if the nonce expired or if the cookie missing.
oidc_metadata_fetch_failure	Databricks could not retrieve metadata from the OIDC configuration. The IdP's issuer URL is used to look up endpoints required for the OIDC flow.	Ensure that {issuer-url}/.well-known/openid-configuration is valid and publicly accessible. Each endpoint URL must be reachable.
oidc_received_no_code_or_token_failure	The IdP did not return an authorization code. Databricks needs this code to redeem for an ID token in the next step.	Check that your IdP supports the OIDC authorization code flow (response_type=code) and is set up to return an authorization code. Confirm that the redirect URI and required scopes are correctly configured. If you need further assistance, contact Databricks support.
oidc_code_exchange_failure	This typically occurs when the client secret is incorrect or expired. It might also happen if the IdP returns any non-200 response.	Ensure the client secret is valid.
oidc_code_exchange_token_missing	The authorization code was received from the IdP, but the subsequent token exchange did not return the expected ID token. After receiving the authorization code, the next step in the OIDC flow is to obtain the ID token.	Check the IdP configuration. You also can manually test the OIDC flow to verify that codes and tokens are returned.
oidc_generic_token_failure	Similar to oidc_code_exchange_token_missing, but this might also occur if the authorization code is invalid, expired, or if there is a claim mismatch (issuer, audience, or nonce). Errors in validating or decoding the code due to claim mismatches can also cause this.	Check the IdP configuration. You also can manually test the OIDC flow to verify that codes and tokens are returned.
oidc_missing_email_claim	The IdP did not send the email claim in the ID token. This might be due to the use of a custom claim.	Verify if a custom claim is used, and ensure it is properly configured.
oidc_auth_error	A generic login error occurred.	Obtain the request ID to identify which requests failed.