Skip to main content

OAuth U2M implementation

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

Overview​

OAuth U2M (User-to-Machine) is the standard OAuth authorization code flow where a user interactively authorizes the partner application to access Databricks on their behalf. This flow is recommended for user-facing applications where end users authenticate with their Databricks credentials.

Key characteristics:

  • User interactively authenticates with Databricks
  • Partner application receives delegated access tokens
  • Tokens are scoped to the user's permissions
  • Supports token refresh for long-running sessions

Prerequisites​

Before implementing OAuth U2M:

  1. A Databricks account with workspace access
  2. Partner application capable of handling OAuth callbacks
  3. HTTPS endpoint for the redirect URI
  4. Databricks SQL driver supporting OAuth tokens (see SQL warehouse drivers)

Register OAuth application​

Register your OAuth application in Databricks:

  1. Log in to the Databricks Account Console:

  2. Navigate to Settings > App connections > Add connection

  3. Configure the application:

    • Name: Partner application name
    • Redirect URI: Your callback endpoint URL
    • Generate client secret: Enable if using confidential client flow
    • Scopes: Select sql for SQL warehouse access

  4. Save the Client ID and Client Secret (if generated)

Implement authorization code flow​

Step 1: Initiate authorization​

Redirect the user to the Databricks authorization endpoint:

GET https://<databricks-workspace-host>/oidc/v1/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=sql
  &state=RANDOM_STATE_VALUE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256

Parameters:

  • response_type: code
  • client_id: Client ID from registration
  • redirect_uri: Your callback endpoint
  • scope: sql (add openid email profile for ID tokens)
  • state: Random value for CSRF protection
  • code_challenge: PKCE code challenge (recommended)
  • code_challenge_method: S256

Step 2: Handle callback​

When the user authorizes, Databricks redirects to your callback with an authorization code:

GET YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=STATE_VALUE

Implement the callback handler:

  1. Validate the state parameter matches the value from step 1
  2. Exchange the authorization code for tokens

Step 3: Exchange code for tokens​

Send a POST request to the token endpoint:

POST https://<databricks-workspace-host>/oidc/v1/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=YOUR_REDIRECT_URI
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code_verifier=YOUR_CODE_VERIFIER

Parameters:

  • grant_type: authorization_code
  • code: Authorization code from callback
  • redirect_uri: Same URI used in authorization request
  • client_id: Client ID from registration
  • client_secret: Client secret from registration
  • code_verifier: PKCE code verifier (if using PKCE)

Response:

{
  "access_token": "<OAuth access token>",
  "refresh_token": "<OAuth refresh token>",
  "token_type": "Bearer",
  "scope": "sql",
  "expires_in": 3600
}

If openid email profile scopes were included, the response also contains an id_token field.

Create DBSQL connection​

Pass the access token to the Databricks SQL driver:

JDBC Driver (2.6.22+):

jdbc:databricks://<workspace-host>:443/<http-path>;AuthMech=11;Auth_Flow=0;Auth_AccessToken=YOUR_OAUTH_ACCESS_TOKEN

ODBC Driver (2.7.5+):

Host=<server-hostname>;Port=443;HTTPPath=<http-path>;AuthMech=11;Auth_Flow=0;Auth_AccessToken=YOUR_OAUTH_ACCESS_TOKEN

Refresh tokens​

OAuth access tokens expire after a limited time (default: 1 hour). For long-running sessions, refresh the token before expiration.

Refresh token request​

POST https://<databricks-workspace-host>/oidc/v1/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID

Update driver connection​

JDBC Driver:

connection.setClientInfo("Auth_AccessToken", "YOUR_NEW_ACCESS_TOKEN");
note

JDBC driver APIs are blocking. Invoke setClientInfo() on a separate thread. If the token is valid for time t, refresh at t/2 to ensure continuous operation.

ODBC Driver:

// Update the access token
char *credentials = "Auth_AccessToken=$(new token)";
SQLSetConnectAttr(dbc, 122, credentials, SQL_NTS); // 122 = SQL_ATTR_CREDENTIALS

// Refresh current connection
__int32 refreshMode = -1; // Refresh now
SQLSetConnectAttr(dbc, 123, reinterpret_cast<SQLPOINTER>(refreshMode), SQL_IS_SMALLINT); // 123 = SQL_ATTR_REFRESH_CONNECTION

Customer integration​

To enable OAuth U2M in customer Databricks accounts:

Customer admin steps:

  1. Register an OAuth application for the partner application (same process as Register OAuth application)
  2. Store the client ID, secret, and redirect URI in the partner application via UI or API

Partner application requirements:

  1. Expose UI/API for customers to store their OAuth credentials
  2. Store mappings between client ID/secret and customer tenant/account
  3. When initiating the OAuth flow, retrieve the correct credentials for the current session context

What's next​