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

项目
12/18/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 身份验证类型：

Microsoft Entra ID 令牌
OAuth 2.0 令牌
OAuth 用户到计算机 (U2M) 身份验证
OAuth 计算机到计算机 (M2M) 身份验证

Microsoft Entra ID 令牌

ODBC 和 JDBC 驱动程序 2.6.15 及更高版本支持 Azure Databricks 用户或 Microsoft Entra ID 服务主体的 Microsoft Entra ID 令牌。

若要创建 Microsoft Entra ID 访问令牌，请执行以下操作：

对于 Azure Databricks 用户，可以使用 Azure CLI。请参阅使用 Azure CLI 获取用户的 Microsoft Entra ID 令牌。
有关 Microsoft Entra ID 服务主体，请参阅使用 Azure CLI 获取 Microsoft Entra ID 访问令牌。若要创建 Microsoft Entra ID 托管服务主体，请参阅管理服务主体。

Microsoft Entra ID 访问令牌的默认生存期约为 1 小时。可以通过编程方式刷新现有会话的访问令牌，而无需通过运行刷新 Microsoft Entra ID 访问令牌中的代码来中断连接。有关如何刷新令牌的说明，请参阅 Configuring Authentication > Using OAuth 2.0中的部分。

要使用 Microsoft Entra ID 令牌进行身份验证，请设置以下配置。

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

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=0;Auth_AccessToken=<microsoft-entra-id-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", "<microsoft-entra-id-token>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

有关可以根据需要调整上述代码片段获得的完整 Java 代码示例，请参阅本文开头的代码示例。
在前面的 URL 或 Java 代码中，将 <microsoft-entra-id-token> 替换为 Microsoft Entra ID 令牌。
若要获取 <server-hostname> 和 <http-path> 的值，请参阅 Databricks JDBC 驱动程序的计算设置。

有关详细信息，请参阅 Token Pass-through中的部分。

OAuth 2.0 令牌

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

若要为Microsoft Entra ID 服务主体创建用于令牌直通身份验证的 OAuth 2.0 令牌，请参阅手动生成和使用 OAuth 服务主体身份验证的访问令牌。记下服务主体的 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 驱动程序的计算设置。

有关详细信息，请参阅 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 驱动程序的计算设置。

有关详细信息，请参阅 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 服务主体身份验证。
授予服务主体对群集或仓库的访问权限。请参阅计算权限或管理 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 驱动程序的计算设置。

有关详细信息，请参阅 Using M2M Based Authentication中的部分。

通过

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

Microsoft Entra ID 令牌

OAuth 2.0 令牌

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

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

反馈

其他资源