OAuth M2M implementation

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

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:

   • AWS: accounts.cloud.databricks.com
   • Azure: accounts.azuredatabricks.net
   • GCP: accounts.gcp.databricks.com

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

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

• Review OAuth U2M implementation for user-interactive authentication
• See OAuth reference for endpoints, driver support, and sample code
• Return to Authentication best practices for method comparison