Authentication settings for the Databricks ODBC Driver

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

This article assumes that you have already gathered the following additional settings to add to the authentication settings as described in this article:

To configure a Databricks connection for the Databricks ODBC Driver, you must combine your compute resource settings, any driver capability settings, and the following authentication settings, into an ODBC Data Source Name (DSN) or a DSN-less connection string.

Whether you use a DSN or DSN-less connection string will depend on the requirements for your target app, tool, client, SDK, or API. Examples of DSNs and DSN-less connection strings are provided in this article for each supported Databricks authentication type.

The Databricks ODBC Driver supports the following Databricks authentication types:

Databricks personal access token

To create a Databricks personal access token, do the following:

  1. In your Databricks workspace, click your Databricks username in the top bar, and then select User Settings from the drop down.

  2. Click Developer.

  3. Next to Access tokens, click Manage.

  4. Click Generate new token.

  5. (Optional) Enter a comment that helps you to identify this token in the future, and change the token’s default lifetime of 90 days. To create a token with no lifetime (not recommended), leave the Lifetime (days) box empty (blank).

  6. Click Generate.

  7. Copy the displayed token to a secure location, and then click Done.

Note

Be sure to save the copied token in a secure location. Do not share your copied token with others. If you lose the copied token, you cannot regenerate that exact same token. Instead, you must repeat this procedure to create a new token. If you lose the copied token, or you believe that the token has been compromised, Databricks strongly recommends that you immediately delete that token from your workspace by clicking the trash can (Revoke) icon next to the token on the Access tokens page.

If you are not able to create or use tokens in your workspace, this might be because your workspace administrator has disabled tokens or has not given you permission to create or use tokens. See your workspace administrator or the following:

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:

[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. Line breaks have been added for readability. The string must not contain these line breaks:

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

Databricks username and password

Databricks username and password authentication is also known as Databricks basic authentication.

Username and password authentication is possible only if single sign-on is disabled.

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

Setting

Value

AuthMech

3

UID

The username.

PWD

The password.

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

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

To create a DSN-less connection string, use the following format. Line breaks have been added for readability. The string must not contain these line breaks:

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

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:

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:

[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. Line breaks have been added for readability. The string must not contain these line breaks:

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>

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

OAuth user-to-machine (U2M) authentication

ODBC driver 2.7.5 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 should refresh expired OAuth 2.0 tokens for you automatically.

Note

OAuth U2M or OAuth 2.0 browser-based authentication works only with applications that run locally. It does not 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:

Configuration

Value

AuthMech

11

Auth_Flow

2

PWD

A password of your choice. The driver uses this key for refresh token encryption.

OAuth2ClientId (optional)

power-bi,tableau-desktop,databricks-cli, databricks-sql-python,databricks-sql-jdbc, databricks-sql-odbc,databricks-dbt-adapter, databricks-sql-connector (default)

Auth_Scope (optional)

sql,offline_access (default)

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

[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. Line breaks have been added for readability. The string must not contain these line breaks:

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

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

OAuth machine-to-machine (M2M) authentication

ODBC driver 2.7.5 and above 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 OAuth machine-to-machine (M2M) authentication. 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 Cluster permissions or SQL warehouse access control.

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.

OAuth2ClientId (optional)

power-bi,tableau-desktop,databricks-cli, databricks-sql-python,databricks-sql-jdbc, databricks-sql-odbc,databricks-dbt-adapter, databricks-sql-connector (default)

Auth_Scope (optional)

all-apis (default)

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

[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. Line breaks have been added for readability. The string must not contain these line breaks:

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

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