Authentication settings for the Databricks JDBC Driver

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

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

• Microsoft Entra ID token
• OAuth 2.0 tokens
• OAuth user-to-machine (U2M) authentication
• Microsoft Entra ID OAuth user-to-machine (U2M) authentication
• OAuth machine-to-machine (M2M) authentication
• Microsoft Entra ID OAuth machine-to-machine (M2M) authentication

Microsoft Entra ID token

ODBC and JDBC drivers 2.6.15 and above support 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:

• For an Azure Databricks user, you can use the Azure CLI. See Get Microsoft Entra ID tokens for users by using the Azure CLI.
• For a Microsoft Entra ID service principal, see Get a Microsoft Entra ID access token with the Azure CLI. To create a Microsoft Entra ID managed service principal, see Service principals.

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 > Using OAuth 2.0 in the Databricks JDBC Driver Guide.

To authenticate using a Microsoft Entra ID token, set the following configuration.

For a JDBC connection URL with embedded general configuration properties and sensitive credential properties:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=0;Auth_AccessToken=<microsoft-entra-id-token>

For Java code with general configuration properties and sensitive credential properties set outside of the JDBC connection URL:

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "0");
p.put("Auth_AccessToken", "<microsoft-entra-id-token>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

• In the preceding URL or Java code, replace <microsoft-entra-id-token> with the Microsoft Entra ID token.
• To get the values for <server-hostname> and <http-path>, see Compute settings for the Databricks JDBC Driver.

For more information, see the Token Pass-through section in the Databricks JDBC Driver Guide.

OAuth 2.0 tokens

JDBC driver 2.6.36 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 and use access tokens for OAuth service principal authentication. Make a note of the service principal's OAuth access_token value.
• To create a Microsoft Entra ID managed service principal, see Service principals.

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, set the following configuration.

For a JDBC connection URL with embedded general configuration properties and sensitive credential properties:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=0;Auth_AccessToken=<oauth-token>

For Java code with general configuration properties and sensitive credential properties set outside of the JDBC connection URL:

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "0");
p.put("Auth_AccessToken", "<oauth-token>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

• In the preceding URL or Java code, replace <oauth-token> with the Azure Databricks OAuth token. (Microsoft Entra ID tokens are not supported for OAuth 2.0 token pass-through authentication.)
• To get the values for <server-hostname> and <http-path>, see Compute settings for the Databricks JDBC Driver.

For more information, see the Token Pass-through section in the Databricks JDBC Driver Guide.

OAuth user-to-machine (U2M) authentication

JDBC driver 2.6.36 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.

To authenticate using OAuth user-to-machine (U2M) or OAuth 2.0 browser-based authentication, set the following configuration.

For a JDBC connection URL with embedded general configuration properties and sensitive credential properties:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=2;TokenCachePassPhrase=<passphrase>;EnableTokenCache=0

For Java code with general configuration properties and sensitive credential properties set outside of the JDBC connection URL:

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "2")
p.put("TokenCachePassPhrase", "<passphrase>");
p.put("EnableTokenCache", "0");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

• In the preceding URL or Java code, replace <passphrase> with a passphrase of your choice. The driver uses this key for refresh token encryption.
• To get the values for <server-hostname> and <http-path>, see Compute settings for the Databricks JDBC Driver.

For more information, see the Using Browser Based Authentication section in the Databricks JDBC Driver Guide.

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

JDBC driver 2.7.1 and above supports Microsoft Entra ID 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.

To authenticate using Microsoft Entra ID OAuth user-to-machine (U2M), the OAuth client (application) must be registered in Microsoft Entra ID, see Register a client application in Microsoft Entra ID. Then set the following configuration:

For a JDBC connection URL with embedded general configuration properties and sensitive credential properties:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=2;TokenCachePassPhrase=<passphrase>;EnableTokenCache=0;OIDCDiscoveryEndpoint=<endpoint>;EnableOIDCDiscovery=true

For Java code with general configuration properties and sensitive credential properties set outside of the JDBC connection URL:

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "2")
p.put("TokenCachePassPhrase", "<passphrase>");
p.put("EnableTokenCache", "0");
p.put("OIDCDiscoveryEndpoint", "https://login.microsoftonline.com/<azureTenantId>/v2.0/.well-known/openid-configuration");
p.put("EnableOIDCDiscovery", "true");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

• In the preceding URL or Java code, replace <passphrase> with a passphrase of your choice. The driver uses this key for refresh token encryption.
• To get the values for <server-hostname> and <http-path>, see Compute settings for the Databricks JDBC Driver.

For more information, see the Using Browser Based Authentication section in the Databricks JDBC Driver Guide.

OAuth machine-to-machine (M2M) authentication

JDBC driver 2.6.36 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 and then assign it to Azure Databricks accounts and workspaces. To do this, see Service principals.

2. Create an Azure Databricks OAuth secret for the service principal. To do this, see Manually generate and use access tokens for OAuth service principal authentication.

3. 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, set the following configuration.

For a JDBC connection URL with embedded general configuration properties and sensitive credential properties:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=1;OAuth2ClientId=<service-principal-application-id>;OAuth2Secret=<service-principal-oauth-secret>

For Java code with general configuration properties and sensitive credential properties set outside of the JDBC connection URL:

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "1");
p.put("OAuth2ClientId", "<service-principal-application-id>");
p.put("OAuth2Secret", "<service-principal-oauth-secret>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

• In the preceding URL or Java code, replace the following placeholders:
  • Replace <service-principal-application-id> with the service principal's Application (client) ID value.
  • Replace <service-principal-oauth-secret> with 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.)
  • To get the values for <server-hostname> and <http-path>, see Compute settings for the Databricks JDBC Driver.

For more information, see the Using M2M Based Authentication section in the Databricks JDBC Driver Guide.

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

JDBC driver 2.7.1 and above supports Microsoft Entra ID 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 Entra ID OAuth M2M authentication, do the following:

1. Create a Microsoft Entra ID managed service principal and then assign it to Azure Databricks accounts and workspaces. To do this, see Service principals.

2. Create an Entra ID OAuth secret for the service principal. To do this, see Manually generate and use access tokens for OAuth service principal authentication.

3. 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), set the following configuration.

For a JDBC connection URL with embedded general configuration properties and sensitive credential properties:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=1;OAuth2ClientId=<service-principal-application-id>;OAuth2Secret=<service-principal-oauth-secret>;OIDCDiscoveryEndpoint=<endpoint>;EnableOIDCDiscovery=true

For Java code with general configuration properties and sensitive credential properties set outside of the JDBC connection URL:

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "1");
p.put("OAuth2ClientId", "<entra-id-service-principal-application-id>");
p.put("OAuth2Secret", "<entra-id-service-principal-client-secret>");
p.put("OIDCDiscoveryEndpoint", "https://login.microsoftonline.com/<AzureTenantId>/v2.0/.well-known/openid-configuration");
p.put("EnableOIDCDiscovery", "true");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

• In the preceding URL or Java code, replace the following placeholders:
  • Replace <entra-id-service-principal-application-id> with the service principal's application ID value in Entra.
  • Replace <entra-id-service-principal-client-secret> with the service principal's secret in Entra. This is the client secret you create in Certificates & secrets in Microsoft Entra ID.
  • To get the values for <server-hostname> and <http-path>, see Compute settings for the Databricks JDBC Driver.