Databricks unified authentication

Databricks unified authentication provides a consistent way to configure and automate authentication as part of OAuth authorization. You define authentication once and reuse the same configuration across supported Databricks tools and SDKs. This avoids maintaining separate credentials for each tool and ensures consistent authentication behavior across environments.

When you use OAuth U2M with these tools, you can authenticate as your own user identity or act as a service principal you manage with OAuth OBO — for example, to run a tool with the service principal's identity without configuring a secret. See Authenticate as a service principal using OAuth OBO.

Participating tools and SDKs

Participating Databricks tools and SDKs include:

• Databricks CLI
• Databricks Terraform provider
• Databricks Connect
• Databricks extension for Visual Studio Code
• Databricks SDK for Python
• Databricks SDK for Java
• Databricks SDK for Go

All tools and SDKs support authentication through environment variables and Databricks configuration profiles. The Databricks Terraform provider and the Python, Java, and Go SDKs also let you configure authentication directly in code. For details, see the tool or SDK’s documentation.

Authentication method priority

This section explains how tools and SDKs prioritize authentication methods and where they look for credentials.

Default authentication order

Tools and SDKs attempt authentication methods in this order and stop after the first success:

1. Personal access tokens (legacy)
2. OAuth machine-to-machine (M2M)
3. OAuth user-to-machine (U2M)

note

To force an SDK to use a specific method, set the Databricks authentication type field in the Config API.

Credential lookup order

For each authentication method, tools and SDKs search for credentials in this order:

1. SDK Config fields: Direct configuration in code (SDKs only)
2. Environment variables: Platform-specific variables
3. Configuration profile: .databrickscfg file DEFAULT profile

Best practices

For maximum portability across environments, do the following:

1. Create a custom configuration profile in your .databrickscfg file
2. Add required fields for your chosen authentication type
3. Set the DATABRICKS_CONFIG_PROFILE environment variable to your profile name

For a complete list of supported environment variables and configuration fields, see Environment variables and fields for unified authentication.