Authentication settings for the Databricks ODBC Driver

This page describes how to configure Databricks authentication settings for the Databricks ODBC Driver.

The Databricks ODBC Driver supports the following Databricks authentication types:

• OAuth 2.0 tokens
• Databricks OAuth user-to-machine (U2M) authentication
• OAuth machine-to-machine (M2M) authentication
• Databricks personal access token (legacy)

OAuth 2.0 tokens

ODBC driver 2.7.5 and above supports an OAuth 2.0 token for a Databricks user or service principal. This is also known as OAuth 2.0 token pass-through authentication.

To create an OAuth 2.0 token for token pass-through authentication, do the following:

• For a user, use the Databricks CLI to initiate OAuth U2M, then run the databricks auth token command. See OAuth user-to-machine (U2M) authentication.
• For a service principal, follow the steps in Manually generate OAuth M2M access tokens and note the access_token value.

OAuth 2.0 tokens have a default lifetime of 1 hour. To generate a new token, repeat this process.

To authenticate using OAuth 2.0 token pass-through authentication, add the following configurations to your compute settings and any special or advanced driver capability settings:

Setting	Value
AuthMech	11
Auth_Flow	0
Auth_AccessToken	The OAuth 2.0 token

To create a DSN for non-Windows systems, use the following format:

ini

[Databricks]
Driver=<path-to-driver>
Host=<server-hostname>
Port=443
HTTPPath=<http-path>
SSL=1
ThriftTransport=2
AuthMech=11
Auth_Flow=0
Auth_AccessToken=<oauth-token>

To create a DSN-less connection string, use the following format. This example includes line breaks for readability. Don't include these line breaks in your connection string:

Driver=<path-to-driver>;
Host=<server-hostname>;
Port=443;
HTTPPath=<http-path>;
SSL=1;
ThriftTransport=2;
AuthMech=11;
Auth_Flow=0;
Auth_AccessToken=<oauth-token>

• To get the value for <path-to-driver>, see Download and install the Databricks ODBC Driver.
• To get the values for <server-hostname> and <http-path>, see Compute settings for the Databricks ODBC Driver.
• Optionally, add special or advanced driver capability settings.

For more information, see the Token Pass-through sections in the Databricks ODBC Driver Guide.

Databricks OAuth user-to-machine (U2M) authentication

ODBC driver 2.8.2 and above supports OAuth user-to-machine (U2M) authentication for a Databricks user. This is also known as OAuth 2.0 browser-based authentication.

OAuth U2M or OAuth 2.0 browser-based authentication has no prerequisites. OAuth 2.0 tokens have a default lifetime of 1 hour. OAuth U2M or OAuth 2.0 browser-based authentication automatically refreshes expired OAuth 2.0 tokens.

note

OAuth U2M or OAuth 2.0 browser-based authentication works only with applications that run locally. It doesn't work with server-based or cloud-based applications.

To authenticate using OAuth user-to-machine (U2M) or OAuth 2.0 browser-based authentication, add the following configurations to your compute settings and any special or advanced driver capability settings:

Setting	Value
AuthMech	11
Auth_Flow	2
PWD	A password of your choice. The driver uses this key for refresh token encryption.
Auth_Client_ID (optional)	databricks-sql-odbc (default). For all available applications, see App connections settings in the account console.
Auth_Scope (optional)	sql offline_access (default)
OAuth2RedirectUrlPort (optional)	8020 (default)

To create a DSN for non-Windows systems, use the following format:

ini

[Databricks]
Driver=<path-to-driver>
Host=<server-hostname>
Port=443
HTTPPath=<http-path>
SSL=1
ThriftTransport=2
AuthMech=11
Auth_Flow=2
PWD=<password>

To create a DSN-less connection string, use the following format. This example includes line breaks for readability. Don't include these line breaks in your connection string:

Driver=<path-to-driver>;
Host=<server-hostname>;
Port=443;
HTTPPath=<http-path>;
SSL=1;
ThriftTransport=2;
AuthMech=11;
Auth_Flow=2;
PWD=<password>

• To get the value for <path-to-driver>, see Download and install the Databricks ODBC Driver.
• To get the values for <server-hostname> and <http-path>, see Compute settings for the Databricks ODBC Driver.
• Optionally, add special or advanced driver capability settings.

For more information, see the Browser Based sections in the Databricks ODBC Driver Guide.

OAuth machine-to-machine (M2M) authentication

ODBC driver supports OAuth machine-to-machine (M2M) authentication for a Databricks service principal. This is also known as OAuth 2.0 client credentials authentication.

To configure OAuth M2M or OAuth 2.0 client credentials authentication, do the following:

1. Create a Databricks service principal in your Databricks workspace, and create an OAuth secret for that service principal.

   To create the service principal and its OAuth secret, see Authorize service principal access to Databricks with OAuth. Make a note of the service principal's UUID or Application ID value, and the Secret value for the service principal's OAuth secret.

2. Give the service principal access to your cluster or warehouse. See Compute permissions or Manage a SQL warehouse.

To authenticate using OAuth machine-to-machine (M2M) or OAuth 2.0 client credentials authentication, add the following configurations to your compute settings and any special or advanced driver capability settings:

Setting	Value
AuthMech	11
Auth_Flow	1
Auth_Client_ID	The service principal's UUID/Application ID value.
Auth_Client_Secret	The service principal's OAuth Secret value.
Auth_Scope (optional)	all-apis (default)

To create a DSN for non-Windows systems, use the following format:

ini

[Databricks]
Driver=<path-to-driver>
Host=<server-hostname>
Port=443
HTTPPath=<http-path>
SSL=1
ThriftTransport=2
AuthMech=11
Auth_Flow=1
Auth_Client_ID=<service-principal-application-ID>
Auth_Client_Secret=<service-principal-secret>
Auth_Scope=all-apis

To create a DSN-less connection string, use the following format. This example includes line breaks for readability. Don't include these line breaks in your connection string:

Driver=<path-to-driver>;
Host=<server-hostname>;
Port=443;
HTTPPath=<http-path>;
SSL=1;
ThriftTransport=2;
AuthMech=11;
Auth_Flow=1;
Auth_Client_ID=<service-principal-application-ID>;
Auth_Client_Secret=<service-principal-secret>;
Auth_Scope=all-apis

• To get the value for <path-to-driver>, see Download and install the Databricks ODBC Driver.
• To get the values for <server-hostname> and <http-path>, see Compute settings for the Databricks ODBC Driver.
• Optionally, add special or advanced driver capability settings.

For more information, see the Client Credentials sections in the Databricks ODBC Driver Guide.

Databricks personal access token (legacy)

To create a Databricks personal access token, follow the steps in Create personal access tokens for workspace users.

To authenticate using a Databricks personal access token, add the following configurations to your compute settings and any special or advanced driver capability settings:

Setting	Value
AuthMech	3
UID	token
PWD	The Databricks personal access token for your workspace user

To create a DSN for non-Windows systems, use the following format:

ini

[Databricks]
Driver=<path-to-driver>
Host=<server-hostname>
Port=443
HTTPPath=<http-path>
SSL=1
ThriftTransport=2
AuthMech=3
UID=token
PWD=<personal-access-token>

To create a DSN-less connection string, use the following format. This example includes line breaks for readability. Don't include these line breaks in your connection string:

Driver=<path-to-driver>;
Host=<server-hostname>;
Port=443;
HTTPPath=<http-path>;
SSL=1;
ThriftTransport=2;
AuthMech=3;
UID=token;
PWD=<personal-access-token>

• To get the value for <path-to-driver>, see Download and install the Databricks ODBC Driver.
• To get the values for <server-hostname> and <http-path>, see Compute settings for the Databricks ODBC Driver.
• Optionally, add special or advanced driver capability settings.