Authentication settings for the Databricks JDBC Driver

Article
12/20/2024

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

To configure an Azure Databricks connection for the Databricks JDBC Driver, you must combine your compute resource settings, any driver capability settings, and the following authentication settings, into a JDBC connection URL or programmatic collection of JDBC connection properties.

JDBC connection URLs use the following format:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>[;<setting1>=<value1>;<setting2>=<value2>;<settingN>=<valueN>]

To get the values for <server-hostname> and <http-path>, see Compute settings for the Databricks JDBC Driver.
Replace <setting>=<value> as needed for each of the connection properties as listed in the following sections.
You can also add special or advanced driver capability settings.

Programmatic collections of JDBC connection properties can be used in Java code such as the following example:

package org.example;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.Statement;
import java.util.Properties;

public class Main {
  public static void main(String[] args) throws Exception {
    Class.forName("com.databricks.client.jdbc.Driver");
    String url = "jdbc:databricks://" + System.getenv("DATABRICKS_SERVER_HOSTNAME") + ":443";
    Properties p = new java.util.Properties();
    p.put("httpPath", System.getenv("DATABRICKS_HTTP_PATH"));
    p.put("<setting1>", "<value1");
    p.put("<setting2>", "<value2");
    p.put("<settingN>", "<valueN");
    try (Connection conn = DriverManager.getConnection(url, p)) {
      Statement stmt = conn.createStatement();
      try (ResultSet rs = stmt.executeQuery("<query>")) {
        ResultSetMetaData md = rs.getMetaData();
        String[] columns = new String[md.getColumnCount()];
        for (int i = 0; i < columns.length; i++) {
          columns[i] = md.getColumnName(i + 1);
        }
        while (rs.next()) {
          System.out.print("Row " + rs.getRow() + "=[");
          for (int i = 0; i < columns.length; i++) {
            if (i != 0) {
              System.out.print(", ");
            }
            System.out.print(columns[i] + "='" + rs.getObject(i + 1) + "'");
          }
          System.out.println(")]");
        }
      }
    }
    System.exit(0);
  }
}

Set the DATABRICKS_SERVER_HOSTNAME and DATABRICKS_HTTP_PATH environment values to the target Azure Databricks compute resource's Server Hostname and HTTP Path values, respectively. To get these values, see Compute settings for the Databricks JDBC Driver. To set environment variables, see your operating system's documentation.
Replace <setting> and <value> as needed for each of the connection properties as listed in the following sections.
You can also add special or advanced driver capability settings, typically as additional <setting> and <value> pairs.
For this example, replace <query> with a SQL SELECT query string.

Whether you use a connection URL or a collection of connection properties will depend on the requirements of your target app, tool, client, SDK, or API. Examples of JDBC connection URLs and programmatic collections of JDBC connection properties are provided in this article for each supported Azure Databricks authentication type.

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

Azure Databricks personal access token
OAuth 2.0 tokens
OAuth user-to-machine (U2M) authentication
OAuth machine-to-machine (M2M) authentication

Azure Databricks personal access token

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

To authenticate using an Azure Databricks personal access token, set the following configuration.

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

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

For a complete Java code example that you can adapt the preceding code snippet to you own needs, see the code example at the beginning of this article.
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 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 M2M authentication. Make a note of the service principal's OAuth access_token value.
To create a Microsoft Entra ID managed service principal, see Manage service principals.

Important

JDBC driver 2.6.36 and above supports 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, 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);
// ...

For a complete Java code example that you can adapt the preceding code snippet to you own needs, see the code example at the beginning of this article.
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.

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:

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

For a complete Java code example that you can adapt the preceding code snippet to you own needs, see the code example at the beginning of this article.
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.

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:

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

Important

JDBC driver 2.6.36 and above supports Azure Databricks OAuth secrets for OAuth M2M or OAuth 2.0 client credentials authentication. Microsoft Entra ID secrets are not supported.
Create an Azure Databricks OAuth secret for the service principal. To do this, see Manually generate and use access tokens for OAuth M2M authentication.
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);
// ...

For a complete Java code example that you can adapt the preceding code snippet to you own needs, see the code example at the beginning of this article.
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.

Authentication settings for the Databricks JDBC Driver

Azure Databricks personal access token

OAuth 2.0 tokens

OAuth user-to-machine (U2M) authentication

OAuth machine-to-machine (M2M) authentication

Additional resources