Authentication Types Reference¶

This document lists all authentication types (auth_type) supported by the Databricks SDK for Python.

Authentication Types Table¶

Auth Type	Description	Required Parameters	Optional Parameters	Environment Variables
`pat`	Personal Access Token authentication - the most common method for programmatic access	`host`, `token`	-	`DATABRICKS_HOST`, `DATABRICKS_TOKEN`
`basic`	Basic HTTP authentication using username and password (primarily for AWS)	`host`, `username`, `password`	`account_id` (for account-level operations)	`DATABRICKS_HOST`, `DATABRICKS_USERNAME`, `DATABRICKS_PASSWORD`, `DATABRICKS_ACCOUNT_ID`
`oauth-m2m`	OAuth 2.0 Machine-to-Machine (service principal) authentication	`host`, `client_id`, `client_secret`	`scopes`, `authorization_details`	`DATABRICKS_HOST`, `DATABRICKS_CLIENT_ID`, `DATABRICKS_CLIENT_SECRET`
`external-browser`	OAuth 2.0 authentication flow using local browser for user login	`host`, `auth_type='external-browser'`	`client_id`, `client_secret`	`DATABRICKS_HOST`, `DATABRICKS_AUTH_TYPE`, `DATABRICKS_CLIENT_ID`
`databricks-cli`	Uses tokens from the Databricks CLI (`databricks auth login`)	`host`	`account_id` (for account-level), `databricks_cli_path`	`DATABRICKS_HOST`, `DATABRICKS_ACCOUNT_ID`, `DATABRICKS_CLI_PATH`
`azure-client-secret`	Azure Active Directory (AAD) Service Principal authentication	`azure_client_id`, `azure_client_secret`	`azure_tenant_id` (auto-detected from `host` if not set), `host`, `azure_workspace_resource_id`, `azure_environment`	`ARM_CLIENT_ID`, `ARM_CLIENT_SECRET`, `ARM_TENANT_ID`, `DATABRICKS_HOST`, `DATABRICKS_AZURE_RESOURCE_ID`, `ARM_ENVIRONMENT`
`azure-cli`	Uses credentials from Azure CLI (`az login`)	`host` (or `azure_workspace_resource_id`)	`azure_tenant_id`	`DATABRICKS_HOST`, `DATABRICKS_AZURE_RESOURCE_ID`, `ARM_TENANT_ID`
`github-oidc`	GitHub Actions OIDC authentication (workload identity federation)	`host`, `client_id`	`token_audience`, `account_id`	`DATABRICKS_HOST`, `DATABRICKS_CLIENT_ID`, `DATABRICKS_TOKEN_AUDIENCE`, `DATABRICKS_ACCOUNT_ID`
`github-oidc-azure`	GitHub Actions OIDC for Azure Databricks workspaces	`host`, `azure_client_id`	`azure_tenant_id`	`DATABRICKS_HOST`, `ARM_CLIENT_ID`, `ARM_TENANT_ID`
`azure-devops-oidc`	Azure DevOps Pipelines OIDC authentication	`host`, `client_id`	`token_audience`, `account_id`	`DATABRICKS_HOST`, `DATABRICKS_CLIENT_ID`, `SYSTEM_ACCESSTOKEN`
`google-credentials`	Google Cloud service account authentication using credentials JSON	`host`, `google_credentials`	-	`DATABRICKS_HOST`, `GOOGLE_CREDENTIALS`
`google-id`	Google Cloud authentication using service account impersonation	`host`, `google_service_account`	-	`DATABRICKS_HOST`, `DATABRICKS_GOOGLE_SERVICE_ACCOUNT`
`metadata-service`	Authentication using Databricks-hosted metadata service	`host`, `metadata_service_url`	-	`DATABRICKS_HOST`, `DATABRICKS_METADATA_SERVICE_URL`
`runtime`	Auto-detected authentication when running in Databricks Runtime (notebooks, jobs)	(auto-detected)	-	`DATABRICKS_RUNTIME_VERSION` (auto-set)
`runtime-oauth`	OAuth authentication for Databricks Runtime with fine-grained permissions	`scopes`	`authorization_details`	`DATABRICKS_RUNTIME_VERSION` (auto-set)
`model-serving`	Auto-detected authentication when running in Databricks Model Serving environment	(auto-detected)	-	`IS_IN_DB_MODEL_SERVING_ENV` or `IS_IN_DATABRICKS_MODEL_SERVING_ENV` (auto-set)
`env-oidc`	OIDC token from environment variable	`host`	`oidc_token_env`, `client_id`	`DATABRICKS_HOST`, `DATABRICKS_OIDC_TOKEN`, `DATABRICKS_OIDC_TOKEN_ENV`, `DATABRICKS_CLIENT_ID`
`file-oidc`	OIDC token from file path	`host`, `oidc_token_filepath`	`client_id`	`DATABRICKS_HOST`, `DATABRICKS_OIDC_TOKEN_FILEPATH` (alias: `DATABRICKS_OIDC_TOKEN_FILE`), `DATABRICKS_CLIENT_ID`

For configuration options that apply to all authentication types (timeouts, debug settings, rate limits), see Authentication.

Usage Examples¶

When you explicitly set auth_type, the SDK only attempts that authentication method, skipping the automatic detection of other methods. This is useful when you have multiple credentials configured but want to use a specific one.

Personal Access Token (PAT)¶

from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
    host="https://your-workspace.cloud.databricks.com",
    token="dapi1234567890abcdef",
    auth_type="pat"
)

Basic Authentication (Username/Password)¶

from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
    host="https://your-workspace.cloud.databricks.com",
    username="your-username",
    password="your-password",
    auth_type="basic"
)

OAuth Machine-to-Machine (Service Principal)¶

from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
    host="https://your-workspace.cloud.databricks.com",
    client_id="your-client-id",
    client_secret="your-client-secret",
    auth_type="oauth-m2m"
)

External Browser (OAuth for Users)¶

from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
    host="https://your-workspace.cloud.databricks.com",
    auth_type="external-browser"
)

Databricks CLI¶

from databricks.sdk import WorkspaceClient

# Assumes you've run: databricks auth login --host https://your-workspace.cloud.databricks.com
w = WorkspaceClient(
    host="https://your-workspace.cloud.databricks.com",
    auth_type="databricks-cli"
)

Azure Service Principal¶

from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
    host="https://adb-1234567890.azuredatabricks.net",
    azure_client_id="your-azure-client-id",
    azure_client_secret="your-azure-client-secret",
    azure_tenant_id="your-azure-tenant-id",
    auth_type="azure-client-secret"
)

Azure CLI¶

from databricks.sdk import WorkspaceClient

# Assumes you've run: az login
w = WorkspaceClient(
    host="https://adb-1234567890.azuredatabricks.net",
    auth_type="azure-cli"
)

GitHub Actions OIDC¶

from databricks.sdk import WorkspaceClient

# In GitHub Actions with OIDC configured
w = WorkspaceClient(
    host="https://your-workspace.cloud.databricks.com",
    client_id="your-databricks-oauth-client-id",
    auth_type="github-oidc"
)

GitHub Actions OIDC for Azure¶

from databricks.sdk import WorkspaceClient

# In GitHub Actions with Azure OIDC configured
w = WorkspaceClient(
    host="https://adb-1234567890.azuredatabricks.net",
    azure_client_id="your-azure-client-id",
    auth_type="github-oidc-azure"
)

Azure DevOps OIDC¶

from databricks.sdk import WorkspaceClient

# In Azure DevOps with OIDC configured
# Note: SYSTEM_ACCESSTOKEN must be exposed as an environment variable
w = WorkspaceClient(
    host="https://your-workspace.cloud.databricks.com",
    client_id="your-databricks-oauth-client-id",
    auth_type="azure-devops-oidc"
)

Google Cloud Credentials¶

from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
    host="https://your-workspace.gcp.databricks.com",
    google_credentials="/path/to/service-account-key.json",
    auth_type="google-credentials"
)

Google Cloud ID (Service Account Impersonation)¶

from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
    host="https://your-workspace.gcp.databricks.com",
    google_service_account="your-service-account@project.iam.gserviceaccount.com",
    auth_type="google-id"
)

Metadata Service¶

from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
    host="https://your-workspace.cloud.databricks.com",
    metadata_service_url="http://localhost:8080/metadata",
    auth_type="metadata-service"
)

Runtime (in Databricks Notebooks)¶

from databricks.sdk import WorkspaceClient

# No credentials needed when running in Databricks Runtime
# The runtime auth type is auto-detected
w = WorkspaceClient(auth_type="runtime")

Runtime OAuth (in Databricks Notebooks with scoped access)¶

from databricks.sdk import WorkspaceClient

# For fine-grained access control in notebooks
w = WorkspaceClient(
    scopes="clusters sql",
    auth_type="runtime-oauth"
)

Environment Variable OIDC¶

from databricks.sdk import WorkspaceClient

# OIDC token from DATABRICKS_OIDC_TOKEN environment variable
w = WorkspaceClient(
    host="https://your-workspace.cloud.databricks.com",
    auth_type="env-oidc"
)

File-based OIDC¶

from databricks.sdk import WorkspaceClient

# OIDC token from a file
w = WorkspaceClient(
    host="https://your-workspace.cloud.databricks.com",
    oidc_token_filepath="/path/to/oidc-token",
    auth_type="file-oidc"
)

Model Serving Environment¶

from databricks.sdk import WorkspaceClient

# Auto-detected when running in Databricks Model Serving
w = WorkspaceClient(auth_type="model-serving")

Authentication Priority Order¶

When no auth_type is explicitly specified, the SDK attempts authentication methods in this order:

pat - Personal Access Token
basic - Username/Password
metadata-service - Metadata Service (if URL provided)
oauth-m2m - OAuth Service Principal
env-oidc - Environment OIDC token
file-oidc - File-based OIDC token
github-oidc - GitHub OIDC
azure-client-secret - Azure Service Principal
github-oidc-azure - GitHub OIDC for Azure
azure-cli - Azure CLI
azure-devops-oidc - Azure DevOps OIDC
external-browser - Browser-based OAuth
databricks-cli - Databricks CLI
runtime-oauth - Databricks Runtime OAuth
runtime - Databricks Runtime native
google-credentials - Google Cloud credentials
google-id - Google Cloud ID
model-serving - Model Serving environment

You can override this order by explicitly setting the auth_type parameter.

Notes¶

Auto-detected auth types (runtime, runtime-oauth, model-serving): These are automatically detected based on environment variables and don’t require explicit configuration.
Azure authentication: When using Azure-specific auth types, if host is not provided but azure_workspace_resource_id is, the SDK will automatically resolve the workspace URL.
OIDC authentication: OIDC-based methods (github-oidc, azure-devops-oidc, env-oidc, file-oidc) use token exchange to obtain Databricks tokens from external identity providers.
Scopes: OAuth-based methods support the scopes parameter for fine-grained access control (e.g., scopes="clusters sql").

Navigation

Related Topics