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

项目
08/29/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 个人访问令牌
Microsoft Entra ID 令牌
OAuth 2.0 令牌
OAuth 用户到计算机 (U2M) 身份验证
OAuth 计算机到计算机 (M2M) 身份验证

Azure Databricks 个人访问令牌

要创建 Azure Databricks 个人访问令牌，请执行以下操作：

在 Azure Databricks 工作区中，单击顶部栏中的 Azure Databricks 用户名，然后从下拉列表中选择“设置”。
单击“开发人员”。
在“访问令牌”旁边，单击“管理”。
单击“生成新令牌”。
（可选）输入有助于将来识别此令牌的注释，并将令牌的默认生存期更改为 90 天。若要创建没有生存期的令牌（不建议），请将“生存期(天)”框留空（保留空白）。
单击“生成” 。
将显示的令牌复制到安全位置，然后单击“完成”。

注意

请务必将复制的令牌保存到安全的位置。请勿与他人共享复制的令牌。如果丢失了复制的令牌，你将无法重新生成完全相同的令牌，而必须重复此过程来创建新令牌。如果丢失了复制的令牌，或者认为令牌已泄露，Databricks 强烈建议通过单击“访问令牌”页上令牌旁边的垃圾桶（撤销）图标立即从工作区中删除该令牌。

如果你无法在工作区中创建或使用令牌，可能是因为工作区管理员已禁用令牌或未授予你创建或使用令牌的权限。请与工作区管理员联系，或参阅以下内容：

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

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

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 驱动程序的计算设置。

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 访问令牌中的代码来中断连接。有关如何刷新令牌的说明，请参阅 Databricks JDBC 驱动程序指南中的 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 驱动程序的计算设置。

有关详细信息，请参阅 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 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 目前不支持将 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 个人访问令牌

Microsoft Entra ID 令牌

OAuth 2.0 令牌

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

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

反馈

其他资源