Skip to main content

OAuth M2M implementation

This guide covers implementing OAuth Machine-to-Machine (M2M) authentication for cloud-based partner applications connecting to Databricks.

Accelerate your build with the Partner AI Dev-Kit

AI coding assistant skills that generate PWAF-compliant Databricks connectors.
Learn more · Skills on GitHub

Overview​

OAuth M2M (Machine-to-Machine) uses the client credentials flow where the partner application authenticates directly with Databricks using a service principal. This flow is recommended for backend services, automated processes, and scenarios where no user interaction is required.

Key characteristics:

  • No user interaction required
  • Application authenticates with service principal credentials
  • Tokens are scoped to the service principal's permissions
  • Suitable for backend services and automation

Prerequisites​

Before implementing OAuth M2M:

  1. A Databricks account with admin access
  2. Databricks SQL driver supporting OAuth M2M (see SQL warehouse drivers)
  3. Unity Catalog permissions for the target catalogs/schemas/tables

Create service principal​

Create a Databricks service principal for M2M authentication:

  1. Log in to the Databricks Account Console:

  2. Select User Management from the left navigation panel

  3. From the Service Principals tab, click Add service principal

  4. (Azure only) Select Databricks managed under the Management section

  5. Enter a name for the service principal and click Add

  6. Select the service principal you just created

  7. Click Generate Secret

  8. Copy the Client ID and Secret from the popup window

    note

    Save the secret securely. You cannot view it again after closing the popup.

  9. Assign the service principal to the workspace. See Assign a service principal to a workspace

  10. Grant Unity Catalog privileges for the catalogs, schemas, and tables the application needs to access

Create DBSQL connection​

Custom URLs

The OAuth token endpoint used by M2M is also served on an account custom URL when one is enabled; the per-workspace host continues to work unchanged. For workspace-scoped API calls over a custom URL, append the ?o=<workspaceId> selector to the standard path.

All Databricks SQL drivers support OAuth M2M. Create a connection by passing the service principal credentials:

Connection string format:

AuthMech=11;Auth_Flow=1;OAuth2ClientId=<client_id>;OAuth2Secret=<secret>;Auth_Scope=<scope>

JDBC Driver (2.6.22+):

jdbc:databricks://<workspace-host>:443/<http-path>;AuthMech=11;Auth_Flow=1;OAuth2ClientId=<client_id>;OAuth2Secret=<secret>

ODBC Driver (2.8.2+):

Host=<server-hostname>;Port=443;HTTPPath=<http-path>;AuthMech=11;Auth_Flow=1;OAuth2ClientId=<client_id>;OAuth2Secret=<secret>

Python Driver (2.5.0+):

from databricks import sql

connection = sql.connect(
    server_hostname="<workspace-host>",
    http_path="<http-path>",
    client_id="<client_id>",
    client_secret="<secret>"
)

Customer integration​

To enable OAuth M2M in customer Databricks accounts:

Customer admin steps:

  1. Create a service principal for the partner application (same process as Create service principal)
  2. Grant the required permissions to the service principal
  3. Store the service principal client ID and secret in the partner application via UI or API

Partner application requirements:

  1. Expose UI/API for customers to store their service principal credentials
  2. Store mappings between service principal credentials and customer tenant/account
  3. Dynamically pass the correct credentials to the DBSQL driver based on session context

Security considerations​

  • Secret storage: Store service principal secrets securely using a secrets manager or encrypted storage
  • Secret rotation: Implement a process for rotating secrets before expiration
  • Least privilege: Grant only the minimum required permissions to service principals
  • Audit logging: Monitor service principal activity through Databricks audit logs

What's next​