Share via

Authentication settings for the Databricks ODBC Driver

  • Article

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

The Databricks ODBC Driver supports the following Azure Databricks authentication types:

Azure Databricks personal access token

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

  1. In your Azure Databricks workspace, click your Azure Databricks username in the top bar, and then select 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 an Azure 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, 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>

Microsoft Entra ID (formerly Azure Active Directory) token

ODBC driver 2.6.15 and above supports Microsoft Entra ID (formerly Azure Active Directory) tokens for an Azure Databricks user or a Microsoft Entra ID service principal.

To create a Microsoft Entra ID access token, do the following:

Microsoft Entra ID access tokens have a default lifetime of about 1 hour. An access token can be refreshed programmatically for an existing session without breaking the connection by running the code in Refresh a Microsoft Entra ID access token. For instructions about how to refresh the token, see the section Configuring Authentication on Windows > Providing a New Access Token in the Databricks ODBC Driver Guide.

To authenticate using a Microsoft Entra ID token, 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 Microsoft Entra ID 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=<microsoft-entra-id-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=<microsoft-entra-id-token>

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

OAuth 2.0 tokens

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

Important

ODBC driver 2.7.5 and above support using Azure Databricks OAuth secrets to create OAuth 2.0 tokens. Microsoft Entra ID secrets are not supported.

OAuth 2.0 tokens have a default lifetime of 1 hour. To generate a new OAuth 2.0 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 Azure Databricks OAuth token

(Microsoft Entra ID tokens are not supported for OAuth 2.0 token pass-through authentication.)

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=<databricks-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=<databricks-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 an Azure 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:

Setting 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 Microsoft Entra ID 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 Microsoft Entra ID managed service principal. To do this, see Manage service principals.

  2. Generate an Azure Databricks OAuth secret for the service principal. See Manually generate and use access tokens for OAuth machine-to-machine (M2M) authentication.

    Important

    ODBC driver 2.7.5 and above supports Azure Databricks OAuth secrets for OAuth M2M or OAuth 2.0 client credentials authentication. Microsoft Entra ID secrets are not supported.

  3. Create an Azure Databricks OAuth secret for the service principal. To do this, see Manually generate and use access tokens for OAuth machine-to-machine (M2M) authentication.

  4. 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 Application (client) ID value.
Auth_Client_Secret The service principal’s Azure Databricks OAuth secret.

(Microsoft Entra ID secrets are not supported for OAuth M2M or OAuth 2.0 client credentials authentication.)
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

Azure managed identities authentication

ODBC driver 2.7.7 and above supports Azure managed identities authentication, which uses managed identities for Azure resources (formerly Managed Service Identities (MSI)) to authenticate with Azure Databricks. Programmatic calls to Azure Databricks workspace operations use these managed identities when working with Azure resources that support managed identities, such as Azure VMs.

To authenticate using Azure managed identities authentication, add the following configurations to your compute settings and any special or advanced driver capability settings:

Setting Value
AuthMech 11
Auth_Flow 3
Auth_Client_Id The Azure managed identity’s ID.
Azure_workspace_resource_id The Azure resource ID for your Azure Databricks workspace.

To get this ID, in your Azure Databricks workspace’s top navigation bar, click your username and then click
Azure Portal. On the Azure Databricks workspace resource page that appears, click Properties under Settings in the sidebar. The ID is in Id under Essentials.

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=3
Auth_Client_Id=<azure-managed-identity-ID>
Azure_workspace_resource_id=<azure-workspace-resource-ID>

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=3;
Auth_Client_Id=<azure-managed-identity-ID>;
Azure_workspace_resource_id=<azure-workspace-resource-ID>