Share via

Authentication settings for the Databricks ODBC Driver

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

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

Microsoft Entra ID token

ODBC driver 2.6.15 and above supports Microsoft Entra ID 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. To refresh a token, see Refresh tokens or the Configuring Authentication on Windows > Providing a New Access Token section 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. 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=<microsoft-entra-id-token>

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

Service principals with Azure roles

If your Microsoft Entra ID service principal has an Azure role on the workspace resource in Azure but isn't in the Azure Databricks workspace, you must set additional HTTP headers in your ODBC connection. The Simba Spark ODBC Driver supports adding headers using the format http.header.[HeaderKey]=[HeaderValue].

Set the following required headers from Service principals with Azure role in your DSN or DSN-less connection string:

  • http.header.X-Databricks-Azure-SP-Management-Token=<management-access-token>
  • http.header.X-Databricks-Azure-Workspace-Resource-Id=<workspace-resource-id>

To get the management token, see Service principals with Azure role. To get the workspace resource ID, see Azure managed identities authentication.

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.

  • To create an OAuth 2.0 token for token pass-through authentication for a Microsoft Entra ID service principal, see Manually generate OAuth M2M access tokens. Make a note of the service principal's OAuth access_token value.
  • To create a Microsoft Entra ID managed service principal, see Service principals.

Important

ODBC driver 2.7.5 and above support using Azure Databricks OAuth secrets to create OAuth 2.0 tokens. Microsoft Entra ID secrets aren't 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
(OAuth 2.0 token pass-through authentication doesn't support Microsoft Entra ID tokens.)

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. 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=<databricks-oauth-token>

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 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 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:

[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>

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

Microsoft Entra ID OAuth user-to-machine (U2M) authentication

ODBC driver 2.8.2 and above supports Microsoft Entra ID OAuth user-to-machine (U2M) authentication for an Azure Databricks user.

To use Microsoft Entra ID OAuth user-to-machine (U2M), you must register the OAuth client (application) in Microsoft Entra ID, see Register a client application in Microsoft Entra ID.

To authenticate using Microsoft Entra ID OAuth user-to-machine (U2M), 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 Application (client) ID of the Azure application
Auth_Scope 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/user_impersonation offline_access
OIDCDiscoveryEndpoint https://login.microsoftonline.com/<azureTenantId>/v2.0/.well-known/openid-configuration
OAuth2RedirectUrlPort Redirect port of the Azure application

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=<application-id-azure-application>
Auth_Scope=2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/user_impersonation offline_access
OIDCDiscoveryEndpoint=https://login.microsoftonline.com/<azureTenantId>/v2.0/.well-known/openid-configuration
OAuth2RedirectUrlPort=<redirect port of the Azure application>

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=<application-id-azure-application>;
Auth_Scope=2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/user_impersonation offline_access;
OIDCDiscoveryEndpoint=https://login.microsoftonline.com/<azureTenantId>/v2.0/.well-known/openid-configuration;
OAuth2RedirectUrlPort=<redirect port of the Azure application>;

OAuth machine-to-machine (M2M) authentication

ODBC driver supports OAuth machine-to-machine (M2M) authentication for an Azure 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 an Azure Databricks service principal in your Azure 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 Azure 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:

[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

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

Microsoft Entra ID OAuth machine-to-machine (M2M) authentication

ODBC driver 2.8.2 and above supports Microsoft Entra ID OAuth machine-to-machine (M2M) authentication for a Microsoft Entra ID service principal.

To configure Entra ID OAuth machine-to-machine (M2M) authentication, do the following:

  1. Create a Microsoft Entra ID managed service principal. To do this, see Service principals.
  2. Give the service principal access to your cluster or warehouse. See Compute permissions or Manage a SQL warehouse.

To authenticate using Entra ID OAuth machine-to-machine (M2M), 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 ID in Entra ID
Auth_Client_Secret The service principal's client secret in Entra ID. This is the client secret you create in Certificates & secrets in Microsoft Entra ID.
Auth_Scope 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default
OIDCDiscoveryEndpoint https://login.microsoftonline.com/<AzureTenantId>/v2.0/.well-known/openid-configuration

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=<entra-id-service-principal-application-ID>
Auth_Client_Secret=<entra-id-service-principal-client-secret>
Auth_Scope=2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default
OIDCDiscoveryEndpoint=https://login.microsoftonline.com/<AzureTenantId>/v2.0/.well-known/openid-configuration

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=<entra-id-service-principal-application-ID>>;
Auth_Client_Secret=<entra-id-service-principal-client-secret>;
Auth_Scope=2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default;
OIDCDiscoveryEndpoint=https://login.microsoftonline.com/<AzureTenantId>/v2.0/.well-known/openid-configuration

Azure managed identities authentication

ODBC driver 2.7.7 and above supports Azure managed identities authentication. Use this authentication method 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. 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=3;
Auth_Client_ID=<azure-managed-identity-ID>;
Azure_workspace_resource_id=<azure-workspace-resource-ID>

Azure Databricks personal access token (legacy)

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

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 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. 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>