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

注意

本文适用于 Databricks JDBC Simba 驱动程序。 有关 Databricks 开发的 JDBC 驱动程序,请参阅 Databricks JDBC 驱动程序(OSS)。

本文介绍了如何配置 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>]

由 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_HOSTNAMEDATABRICKS_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 身份验证类型:

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 令牌。 Microsoft Entra ID 令牌不支持 OAuth 2.0 令牌直通身份验证。
  • 若要获取 <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 客户端凭据身份验证,请执行以下操作:

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

    重要

    JDBC 驱动程序 2.6.36 及更高版本支持用于 OAuth M2M 或 OAuth 2.0 客户端凭据身份验证的 Azure Databricks OAuth 机密。 不支持 Microsoft Entra ID 密钥。

  2. 为服务主体创建 Azure Databricks OAuth 机密。 为此,请参阅 手动生成和使用访问令牌进行 OAuth 服务主体身份验证

  3. 授予服务主体对群集或仓库的访问权限。 请参阅计算权限管理 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中的 部分。