Configure SSO using OIDC

This page 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 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. 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. Databricks opens a new browser window and attempts to authenticate using your identity provider. Complete the sign-in flow and review the test results.

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.

For detailed post-setup testing guidance, including workspace login testing, see Test your SSO configuration.

Add users to Databricks

After you configure SSO, add users to your account. Databricks recommends syncing users from your identity provider using automatic identity management, which syncs users and groups automatically from your identity provider to your Databricks account. See Configure Microsoft Entra ID for automatic identity management. Alternatively, if your identity provider does not support automatic identity management, you can configure SCIM provisioning. See Sync users and groups from your identity provider using SCIM.

Just-in-time (JIT) provisioning, which automatically adds users to Databricks when they first log in using SSO, is on by default for accounts created after May 1, 2025. See Automatically provision users (JIT).

Enable unified login

For most accounts, unified login is already enabled, which means the account-level SSO configuration applies to all workspaces. If your account was created before June 21, 2023, you might need to enable it. See Enable unified login.

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.