Skip to main content

Authentication settings for the Databricks JDBC Driver

note

This article applies to the Databricks JDBC Simba driver. For the Databricks-developed JDBC driver, see Databricks JDBC Driver (OSS).

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

The Databricks JDBC Driver supports the following Databricks authentication types:

Databricks personal access token​

note

Personal access tokens are provided for testing scenarios. Databricks recommends more secure authentication types for production scenarios.

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

To configure the authentication for a JDBC connection URL with embedded general configuration properties and sensitive credential properties using your PAT:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=3;UID=token;PWD=<personal-access-token>

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

Java
// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "3");
p.put("UID", "token");
p.put("PWD", "<personal-access-token>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...
  • In the preceding URL or Java code, replace <personal-access-token> with the Databricks personal access token for your workspace user.
  • To get the values for <server-hostname> and <http-path>, see Compute settings for the Databricks JDBC Driver.

OAuth 2.0 tokens​

JDBC driver 2.6.36 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, 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:

Java
// ...
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);
// ...

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 a Databricks user. This is also known as OAuth 2.0 browser-based authentication.

note

JDBC 2.6.40.1071 resolves the issue in older versions that connecting using M2M for private link workspaces was not supported.

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

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

OAuth machine-to-machine (M2M) authentication​

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

note

JDBC 2.6.40.1071 resolves the issue in older versions that connecting using M2M for private link workspaces was not supported.

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 unattended access to Databricks resources with a service principal using 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, 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:

Java
// ...
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 UUID/Application ID value.
    • Replace <service-principal-oauth-secret> with the service principal's OAuth Secret value.
    • 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.

Last updated on