Skip to content

auth-types-reference.md

Latest commit

 

History

History
271 lines (221 loc) · 11 KB

auth-types-reference.md

File metadata and controls

271 lines (221 loc) · 11 KB
Raw

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:

  1. pat - Personal Access Token
  2. basic - Username/Password
  3. metadata-service - Metadata Service (if URL provided)
  4. oauth-m2m - OAuth Service Principal
  5. env-oidc - Environment OIDC token
  6. file-oidc - File-based OIDC token
  7. github-oidc - GitHub OIDC
  8. azure-client-secret - Azure Service Principal
  9. github-oidc-azure - GitHub OIDC for Azure
  10. azure-cli - Azure CLI
  11. azure-devops-oidc - Azure DevOps OIDC
  12. external-browser - Browser-based OAuth
  13. databricks-cli - Databricks CLI
  14. runtime-oauth - Databricks Runtime OAuth
  15. runtime - Databricks Runtime native
  16. google-credentials - Google Cloud credentials
  17. google-id - Google Cloud ID
  18. 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").

See Also