Databricks ODBC 驱动程序的身份验证设置

项目
12/20/2024

本文介绍了如何配置 Databricks JDBC 驱动程序的 Azure Databricks 身份验证设置。

若要为 Databricks JDBC 驱动程序配置 Azure Databricks 连接，必须将计算资源设置、任何驱动程序功能设置以及以下身份验证设置合并到一个 JDBC 连接 URL 或由 JDBC 连接属性组成的编程集合中。

JDBC 连接 URL 使用以下格式：

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

若要获取 <server-hostname> 和 <http-path> 的值，请参阅 Databricks JDBC 驱动程序的计算设置。
按照以下各部分中所列，根据需要为每个连接属性替换 <setting>=<value>。
还可以添加特殊或高级驱动程序功能设置。

由 JDBC 连接属性组成的编程集合可使用 Java 代码的形式，例如以下示例：

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);
  }
}

将 DATABRICKS_SERVER_HOSTNAME 和 DATABRICKS_HTTP_PATH 环境值分别设置为目标 Azure Databricks 计算资源的“服务器主机名”和“HTTP 路径”值。若要获取这些值，请参阅 Databricks JDBC 驱动程序的计算设置。若要设置环境变量，请参阅操作系统的文档。
按照以下各节中所列，根据需要为每个连接属性替换 <setting> 和 <value>。
还可以添加特殊或高级驱动程序功能设置（通常是作为附加 <setting> 和 <value> 对）。
对于此示例，请将 <query> 替换为 SQL SELECT 查询字符串。

是使用连接 URL 还是连接属性集合将取决于目标应用、工具、客户端、SDK 或 API 的要求。本文为每个受支持的 Azure Databricks 身份验证类型提供了 JDBC 连接 URL 和由 JDBC 连接属性组成的编程集合的示例。

Databricks JDBC 驱动程序支持以下 Azure Databricks 身份验证类型：

Azure Databricks 个人访问令牌
OAuth 2.0 令牌
OAuth 用户到计算机 (U2M) 身份验证
OAuth 计算机到计算机 (M2M) 身份验证

Azure Databricks 个人访问令牌

要创建 Azure Databricks 个人访问令牌，请遵循适用于工作区用户的 Azure Databricks 个人访问令牌中的步骤。

要使用 Azure Databricks 个人访问令牌进行身份验证，请设置以下配置。

要配置带有嵌入式常规配置属性和敏感凭据属性的 JDBC 连接 URL，请使用 PAT：

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

对于在 JDBC 连接 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);
// ...

有关可以根据需要调整上述代码片段获得的完整 Java 代码示例，请参阅本文开头的代码示例。
在前面的 URL 或 Java 代码中，将 <personal-access-token> 替换为你的工作区用户的 Databricks 个人访问令牌。
若要获取 <server-hostname> 和 <http-path> 的值，请参阅 Databricks JDBC 驱动程序的计算设置。

OAuth 2.0 令牌

JDBC 驱动程序 2.6.36 及更高版本支持针对 Microsoft Entra ID 服务主体的 OAuth 2.0 令牌。这也称为 OAuth 2.0 令牌直通身份验证。

若要为 Microsoft Entra ID 服务主体的令牌直通身份验证创建 OAuth 2.0 令牌，请参阅手动生成和使用 OAuth M2M 身份验证的访问令牌。记下服务主体的 OAuth access_token 值。
若要创建 Microsoft Entra ID 托管服务主体，请参阅管理服务主体。

重要

JDBC 驱动程序 2.6.36 及更高版本支持使用 Azure Databricks OAuth 机密创建 OAuth 2.0 令牌。不支持 Microsoft Entra ID 机密。

OAuth 2.0 令牌的默认生存期为 1 小时。若要生成新的 OAuth 2.0 令牌，请重复此过程。

要使用 OAuth 2.0 令牌直通身份验证进行身份验证，请设置以下配置。

对于带有嵌入式常规配置属性和敏感凭据属性的 JDBC 连接 URL：

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

对于在 JDBC 连接 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);
// ...

有关可以根据需要调整上述代码片段获得的完整 Java 代码示例，请参阅本文开头的代码示例。
在前面的 URL 或 Java 代码中，将 <oauth-token> 替换为 Azure Databricks OAuth 令牌。（OAuth 2.0 令牌直通身份验证不支持 Microsoft Entra ID 令牌。）
若要获取 <server-hostname> 和 <http-path> 的值，请参阅 Databricks JDBC 驱动程序的计算设置。

有关详细信息，请参阅 Databricks JDBC 驱动程序指南中的 Token Pass-through 部分。

OAuth 用户到计算机 (U2M) 身份验证

JDBC 驱动程序 2.6.36 及更高版本支持针对 Azure Databricks 用户的 OAuth 用户到计算机 (U2M) 身份验证。这也称为 OAuth 2.0 基于浏览器的身份验证。

OAuth U2M 或基于 OAuth 2.0 浏览器的身份验证没有先决条件。 OAuth 2.0 令牌的默认生存期为 1 小时。 OAuth U2M 或基于 OAuth 2.0 浏览器的身份验证应自动刷新过期的 OAuth 2.0 令牌。

注意

OAuth U2M 或基于 OAuth 2.0 浏览器的身份验证仅适用于在本地运行的应用程序。它不适用于基于服务器的或基于云的应用程序。

要使用 OAuth 用户到计算机 (U2M) 或基于 OAuth 2.0 浏览器的身份验证进行身份验证，请设置以下配置。

对于带有嵌入式常规配置属性和敏感凭据属性的 JDBC 连接 URL：

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

对于在 JDBC 连接 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);
// ...

有关可以根据需要调整上述代码片段获得的完整 Java 代码示例，请参阅本文开头的代码示例。
在前面的 URL 或 Java 代码中，将 <passphrase> 替换为你选择的通行短语。驱动程序使用此密钥进行刷新令牌加密。
若要获取 <server-hostname> 和 <http-path> 的值，请参阅 Databricks JDBC 驱动程序的计算设置。

有关详细信息，请参阅 Databricks JDBC 驱动程序指南中的 Using Browser Based Authentication 部分。

OAuth 计算机到计算机 (M2M) 身份验证

JDBC 驱动程序 2.6.36 及更高版本支持针对 Microsoft Entra ID 服务主体的 OAuth 计算机到计算机 (M2M) 身份验证。这也称为 OAuth 2.0 客户端凭据身份验证。

注意

JDBC 2.6.40.1071 解决了旧版本中不支持使用 M2M 连接专用链接工作区的问题。

要配置 OAuth M2M 或 OAuth 2.0 客户端凭据身份验证，请执行以下操作：

创建 Microsoft Entra ID 托管服务主体，然后将其分配给 Azure Databricks 帐户和工作区。为此，请参阅管理服务主体。

重要

JDBC 驱动程序 2.6.36 及更高版本支持用于 OAuth M2M 或 OAuth 2.0 客户端凭据身份验证的 Azure Databricks OAuth 机密。不支持 Microsoft Entra ID 机密。
为服务主体创建 Azure Databricks OAuth 机密。若要执行此操作，请参阅手动生成和使用 OAuth M2M 身份验证的访问令牌。
授予服务主体对群集或仓库的访问权限。请参阅计算权限或管理 SQL 仓库。

要使用 OAuth 计算机到计算机 (M2M) 或 OAuth 2.0 客户端凭据身份验证进行身份验证，请设置以下配置。

对于带有嵌入式常规配置属性和敏感凭据属性的 JDBC 连接 URL：

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

对于在 JDBC 连接 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);
// ...

有关可以根据需要调整上述代码片段获得的完整 Java 代码示例，请参阅本文开头的代码示例。
在前面的 URL 或 Java 代码中，替换以下占位符：
- 将 <service-principal-application-id> 替换为服务主体的“应用程序(客户端) ID”值。
- 将 <service-principal-oauth-secret> 替换为服务主体的 Azure Databricks OAuth 机密。（OAuth M2M 或 OAuth 2.0 客户端凭据身份验证不支持 Microsoft Entra ID 机密。）
- 若要获取 <server-hostname> 和 <http-path> 的值，请参阅 Databricks JDBC 驱动程序的计算设置。

有关详细信息，请参阅 Databricks JDBC 驱动程序指南中的 Using M2M Based Authentication 部分。

通过

Databricks ODBC 驱动程序的身份验证设置

Azure Databricks 个人访问令牌

OAuth 2.0 令牌

OAuth 用户到计算机 (U2M) 身份验证

OAuth 计算机到计算机 (M2M) 身份验证

其他资源