Databricks client unified authentication

  • Article

Databricks client unified authentication centralizes setting up and automating authentication to Azure Databricks. It enables you to configure Databricks authentication once and then use that configuration across multiple Databricks tools and SDKs without further authentication configuration changes.

Participating tools and SDKs

Participating Databricks tools and SDKs include:

All participating tools and SDKs accept special environment variables and Azure Databricks configuration profiles for authentication. The Databricks Terraform provider and the Databricks SDKs for Python, Java, and Go also accept direct configuration of authentication settings within code. For details, see Developer tools and guidance for the tool's or SDK's documentation.

Default methods for client unified authentication

Whenever a tool or SDK must authenticate to Azure Databricks, it tries the following types of authentication in the following order by default. When the tool or SDK succeeds with the type of authentication it tries, it stops trying to authenticate with the remaining authentication types. To force an SDK to authenticate with a specific authentication type, set the Config API's Databricks authentication type field.

  1. Azure Databricks personal access token authentication
  2. Authenticate access to Azure Databricks with a service principal using OAuth (OAuth M2M)
  3. Authenticate access to Azure Databricks with a user account using OAuth (OAuth U2M)
  4. Azure managed identities authentication
  5. MS Entra service principal authentication
  6. Azure CLI authentication

For each authentication type that the participating tool or SDK tries, the tool or SDK tries to find authentication credentials in the following locations, in the following order. When the tool or SDK succeeds in finding authentication credentials that can be used, the tool or SDK stops trying to find authentication credentials in the remaining locations.

  1. Credential-related Config API fields (for SDKs). To set Config fields, see the SDK's reference documentation.
  2. Credential-related environment variables.
  3. Credential-related fields in the DEFAULT configuration profile within the .databrickscfg file. To set configuration profile fields, see (/dev-tools/auth/config-profiles.md).
  4. Any related authentication credentials that are cached by the Azure CLI. See Azure CLI authentication.

To provide maximum portability for your code, Databricks recommends that you create a custom configuration profile within the .databrickscfg file, add the belowrequired fields below for your target Databricks authentication type to the custom configuration profile, and then set the DATABRICKS_CONFIG_PROFILE environment variable to the name of the custom configuration profile.

Environment variables and fields for client unified authentication

The following tables list the names and descriptions of the supported environment variables and fields for Databricks client unified authentication. In the following tables:

  • Environment variable, where applicable, is the name of the environment variable.
  • .databrickscfg field, where applicable, is the name of the field within an Azure Databricks configuration profiles file or Databricks Terraform configuration. To set .databrickscfg fields, see Azure Databricks configuration profiles.
  • Terraform field, where applicable, is the name of the field within a Databricks Terraform configuration. To set Databricks Terraform fields, see Authentication in the Databricks Terraform provider documentation.
  • Config field is the name of the field within the Config API for the specified SDK.

General host, token, and account ID environment variables and fields

Common name Description Environment variable .databrickscfg field, Terraform field Config field
Azure Databricks host (String) The Azure Databricks host URL for either the Azure Databricks workspace endpoint or the Azure Databricks accounts endpoint. DATABRICKS_HOST host host (Python),
setHost (Java),
Host (Go)
Azure Databricks token (String) The Azure Databricks personal access token or Microsoft Entra ID token. DATABRICKS_TOKEN token token (Python),
setToken (Java),
Token (Go)
Azure Databricks account ID (String) The Azure Databricks account ID for the Azure Databricks account endpoint. Only has effect when the Azure Databricks host is also set to
https://accounts.databricks.azure.cn.		 DATABRICKS_ACCOUNT_ID account_id account_id (Python),
setAccountID (Java),
AccountID (Go)

Azure-specific environment variables and fields

Common name Description Environment variable .databrickscfg field, Terraform field Config field
Azure client ID (String) The Microsoft Entra ID service principal's application ID. Use with Azure managed identities authentication and Microsoft Entra ID service principal authentication. ARM_CLIENT_ID azure_client_id azure_client_id (Python),
setAzureClientID (Java),
AzureClientID (Go)
Azure client secret (String) The Microsoft Entra ID service principal's client secret. Use with a Microsoft Entra ID service principal authentication. ARM_CLIENT_SECRET azure_client_secret azure_client_secret (Python),
setAzureClientSecret (Java),
AzureClientSecret (Go)
Client ID (String) The client ID of the Azure Databricks managed service principal or Microsoft Entra ID managed service principal. Use with OAuth M2M authentication. DATABRICKS_CLIENT_ID client_id client_id (Python),
setClientId (Java),
ClientId (Go)
Client secret (String) The client secret of the Azure Databricks managed service principal or Microsoft Entra ID managed service principal. Use with OAuth M2M authentication. DATABRICKS_CLIENT_SECRET client_secret client_secret (Python),
setClientSecret (Java),
ClientSecret (Go)
Azure environment (String) The Azure environment type. Defaults to PUBLIC. ARM_ENVIRONMENT azure_environment azure_environment (Python),
setAzureEnvironment (Java),
AzureEnvironment (Go)
Azure tenant ID (String) The Microsoft Entra ID service principal's tenant ID. ARM_TENANT_ID azure_tenant_id azure_tenant_id (Python),
setAzureTenantID (Java),
AzureTenantID (Go)
Azure use MSI (Boolean) True to use Azure Managed Service Identity passwordless authentication flow for service principals. Requires the Azure resource ID to also be set. ARM_USE_MSI azure_use_msi AzureUseMSI (Go)
Azure resource ID (String) The Azure Resource Manager ID for the Azure Databricks workspace. DATABRICKS_AZURE_RESOURCE_ID azure_workspace_resource_id azure_workspace_resource_id (Python),
setAzureResourceID (Java),
AzureResourceID (Go)

.databrickscfg-specific environment variables and fields

Use these environment variables or fields to specify non-default settings for .databrickscfg. See also Azure Databricks configuration profiles.

Common name Description Environment variable Terraform field Config field
.databrickscfg file path (String) A non-default path to the
.databrickscfg file.		 DATABRICKS_CONFIG_FILE config_file config_file (Python),
setConfigFile (Java),
ConfigFile (Go)
.databrickscfg default profile (String) The default named profile to use, other than DEFAULT. DATABRICKS_CONFIG_PROFILE profile profile (Python),
setProfile (Java),
Profile (Go)

Authentication type field

Use this environment variable or field to force an SDK to use a specific type of Databricks authentication.

Common name Description Terraform field Config field
Databricks authentication type (String) When multiple authentication attributes are available in the environment, use the authentication type specified by this argument. auth_type auth_type (Python),
setAuthType (Java),
AuthType (Go)

Supported Databricks authentication type field values include: