Databricks CLI 的身份验证

  • 项目

注意

此信息适用于 Databricks CLI 0.205 及更高版本，这些版本为公共预览版。 若要查找你的 Databricks CLI 的版本，请运行 databricks -v。

本文介绍如何在 Databricks CLI 与 Azure Databricks 帐户和工作区之间设置身份验证。 请参阅什么是 Databricks CLI？。

本文假定你已安装 Databricks CLI。 请参阅安装或更新 Databricks CLI。

在运行 Databricks CLI 命令之前，必须在 Databricks CLI 与 Azure Databricks 帐户、工作区或这些对象的组合之间设置身份验证，具体取决于要运行的 CLI 命令的类型。

必须在运行时对相关资源的 Databricks CLI 进行身份验证，以便在 Azure Databricks 帐户或工作区内运行 Azure Databricks 自动化命令。 必须对 Azure Databricks 工作区和/或帐户进行身份验证，具体取决于你是要调用 Azure Databricks 工作区级命令、Azure Databricks 帐户级命令，还是同时调用两者。 若要查看 Azure Databricks 工作区级和帐户级 CLI 命令组的列表，请运行命令 databricks -h。 有关 Databricks CLI 命令涵盖的 Azure Databricks 工作区级和帐户级 REST API 操作的列表，请参阅 Databricks REST API。

注意

Databricks CLI 实施 Databricks 客户端统一身份验证标准，这是一种整合且一致的体系结构和编程身份验证方法。 此方法有助于使 Azure Databricks 的身份验证设置和自动化更加集中和可预测。 借助此方法，你只需配置 Azure Databricks 身份验证一次，然后即可在多个 Azure Databricks 工具和 SDK 中使用该配置，而无需进一步更改身份验证配置。 有关此标准的详细信息，请参阅 Databricks 客户端统一身份验证。

以下部分提供有关如何在 Databricks CLI 和 Azure Databricks 之间设置身份验证的信息：

Azure Databricks 个人访问令牌身份验证

Azure Databricks 个人访问令牌身份验证使用 Azure Databricks 个人访问令牌对目标 Azure Databricks 实体（例如 Azure Databricks 用户帐户）进行身份验证。 请参阅 Azure Databricks 个人访问令牌身份验证。

注意

无法使用 Azure Databricks 个人访问令牌身份验证对 Azure Databricks 帐户进行身份验证，因为 Azure Databricks 帐户级命令不使用 Azure Databricks 个人访问令牌进行身份验证。 若要使用 Azure Databricks 帐户进行身份验证，请考虑改用以下身份验证类型之一：

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

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

注意

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

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

若要配置和使用 Azure Databricks 个人访问令牌身份验证，请执行以下操作：

注意

以下过程创建名为 DEFAULT 的 Azure Databricks 配置文件。 如果已有要使用的 DEFAULT 配置文件，请跳过此过程。 否则，此过程将覆盖现有的 DEFAULT 配置文件。 若要查看任何现有配置文件的名称和主机，请运行命令 databricks auth profiles。

要创建名称不为 DEFAULT 的配置文件，请将 --profile <configuration-profile-name> 或 -p <configuration-profile-name> 添加到以下 databricks configure 命令的末尾，以将 <configuration-profile-name> 替换为新配置文件的名称。

  1. 使用 Databricks CLI 运行以下命令：

    databricks configure

  2. 对于提示Databricks 主机，请输入 Azure Databricks 按工作区 URL，例如https://adb-1234567890123456.7.databricks.azure.cn。

  3. 对于提示“个人访问令牌”，请输入工作区的 Azure Databricks 个人访问令牌。

    输入 Azure Databricks 个人访问令牌后，相应的配置文件会添加到 .databrickscfg 文件中。 如果 Databricks CLI 在默认位置找不到此文件，它会首先创建此文件，然后将此配置文件添加到新文件中。 此文件的默认位置位于 Unix、Linux 或 macOS 上的 ~（用户主目录）文件夹中，或 Windows 上的 %USERPROFILE%（用户主目录）文件夹中。

  4. 现在可以使用 Databricks CLI 的 --profile 或 -p 选项后跟配置文件的名称，作为 Databricks CLI 命令调用的一部分，例如 databricks clusters list -p <configuration-profile-name>。

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

可以使用 OAuth 身份验证，而不是使用令牌身份验证对 Azure Databricks 进行身份验证。 OAuth 提供的令牌比 Azure Databricks 个人访问令牌的过期时间更快，并提供了更好的服务器端会话失效和范围界定。 由于 OAuth 访问令牌会在一小时内过期，因此可降低与意外将令牌签入源代码管理相关的风险。 另请参阅 OAuth 用户到计算机 (U2M) 身份验证。

若要配置和使用 OAuth U2M 身份验证，请执行以下操作：

  1. 在调用任何 Azure Databricks 帐户级命令之前，必须运行以下命令在本地启动 OAuth 令牌管理。 必须为要对其运行命令的每个帐户单独运行此命令。 如果不想调用任何帐户级操作，请跳到步骤 5。

    在以下命令中，替换以下占位符：

    databricks auth login --host <account-console-url> --account-id <account-id>

  2. Databricks CLI 会提示你在本地将帐户控制台 URL 和帐户 ID 保存为 Azure Databricks 配置文件。 按 Enter 接受建议的配置文件名称，或输入新的或现有的配置文件的名称。 任何具有相同名称的现有配置文件都会被此帐户控制台 URL 和帐户 ID 覆盖。

    若要获取任何现有配置文件的列表，请在单独的终端或命令提示符中运行 databricks auth profiles 命令。 要查看特定配置文件的现有设置，请运行命令 databricks auth env --profile <profile-name>。

  3. 在 Web 浏览器中，按照屏幕上的说明登录到 Azure Databricks 帐户。

  4. 若要查看当前的 OAuth 令牌值和即将到期的时间戳，请运行 databricks auth token --host <account-console-url> --account-id <account-id> 命令。

  5. 在调用任何 Azure Databricks 工作区级命令之前，必须运行以下命令在本地启动 OAuth 令牌管理。 必须为要对其运行命令的每个工作区单独运行此命令。

    在以下命令中，将 <workspace-url> 替换为 Azure Databricks 每工作区 URL，例如 https://adb-1234567890123456.7.databricks.azure.cn。

    databricks auth login --host <workspace-url>

  6. Databricks CLI 会提示你在本地将工作区 URL 保存为 Azure Databricks 配置文件。 按 Enter 接受建议的配置文件名称，或输入新的或现有的配置文件的名称。 任何具有相同名称的现有配置文件都会此工作区 URL 覆盖。

    若要获取任何现有配置文件的列表，请在单独的终端或命令提示符中运行 databricks auth profiles 命令。 要查看特定配置文件的现有设置，请运行命令 databricks auth env --profile <profile-name>。

  7. 在 Web 浏览器中，按照屏幕上的说明登录到 Azure Databricks 工作区。

  8. 若要查看当前的 OAuth 令牌值和即将到期的时间戳，请运行 databricks auth token --host <workspace-url> 命令。

  9. 使用 Databricks CLI 的 --profile 或 -p 选项后跟配置文件的名称，作为 Databricks CLI 命令调用的一部分，例如 databricks account groups list -p <configuration-profile-name> 或 databricks clusters list -p <configuration-profile-name>。

    提示

    可以在 --profile 或 -p 之后按 Tab 以显示可供选择的现有可用配置文件的列表，而不是手动输入配置文件名称。

Azure 托管标识身份验证

Azure 托管标识身份验证使用 Azure 资源的托管标识（以前称为托管服务标识 [MSI]）进行身份验证。 请参阅什么是 Azure 资源托管标识？。 另请参阅《Azure 托管标识身份验证》。

若要创建 Azure 用户分配的托管标识，请执行以下操作：

  1. 创建或确定 Azure VM 并在其上安装 Databricks CLI，然后将托管标识分配给你的 Azure VM 和你的目标 Azure Databricks 帐户、工作区或两者。 请参阅为 Azure Databricks 自动化设置和使用 Azure 托管标识身份验证。

  2. 在 Azure VM 上，在 .databrickscfg 文件中使用以下字段创建或标识 Azure Databricks 配置文件。 如果创建配置文件，请将占位符替换为相应值。

    对于帐户级命令，请在 .databrickscfg 文件中设置以下值：

    [<some-unique-configuration-profile-name>]
host            = <account-console-url>
account_id      = <account-id>
azure_client_id = <azure-managed-identity-application-id>
azure_use_msi   = true

    对于工作区级命令，请在 .databrickscfg 文件中设置以下值：

    [<some-unique-configuration-profile-name>]
host            = <workspace-url>
azure_client_id = <azure-managed-identity-application-id>
azure_use_msi   = true

    对于工作区级命令，如果尚未将目标标识添加到工作区，请指定 azure_workspace_resource_id 以及 Azure 资源 ID，而不是 host 和工作区 URL。 在这种情况下，目标标识必须至少对 Azure 资源具有“参与者”或“所有者”权限。

    注意

    .databrickscfg 文件的默认位置位于用户的主目录中。 对于 Linux 和 macOS 为 ~，对于 Windows 为 %USERPROFILE%。

  3. 在 Azure VM 上，使用 Databricks CLI 的 --profile 或 -p 选项后跟配置文件的名称，以设置要供 Databricks 使用的配置文件，例如 databricks account groups list -p <configuration-profile-name> 或 databricks clusters list -p <configuration-profile-name>。

    提示

    可以在 --profile 或 -p 之后按 Tab 以显示可供选择的现有可用配置文件的列表，而不是手动输入配置文件名称。

Microsoft Entra ID 服务主体身份验证

Microsoft Entra ID 服务主体身份验证使用 Microsoft Entra ID 服务主体的凭据进行授权。 要创建和管理 Azure Databricks 的服务主体，请参阅管理服务主体。 另请参阅 Microsoft Entra ID 服务主体身份验证。

若要配置和使用 Microsoft Entra ID 服务主体身份验证，必须在本地安装 Azure CLI。 还必须执行以下操作：

  1. 在 .databrickscfg 文件中使用以下字段创建或标识 Azure Databricks 配置文件。 如果创建配置文件，请将占位符替换为相应值。

    对于帐户级命令，请在 .databrickscfg 文件中设置以下值：

    [<some-unique-configuration-profile-name>]
host                = <account-console-url>
account_id          = <account-id>
azure_tenant_id     = <azure-service-principal-subscription-id>
azure_client_id     = <azure-service-principal-application-id>
azure_client_secret = <azure-service-principal-client-secret>

    对于工作区级命令，请在 .databrickscfg 文件中设置以下值：

    [<some-unique-configuration-profile-name>]
host                = <workspace-url>
azure_tenant_id     = <azure-service-principal-subscription-id>
azure_client_id     = <azure-service-principal-application-id>
azure_client_secret = <azure-service-principal-client-secret>

    对于工作区级命令，如果尚未将目标 Microsoft Entra ID 服务主体添加到工作区，请指定 azure_workspace_resource_id 以及 Azure 资源 ID，而不是 host 和工作区 URL。 在这种情况下，目标 Microsoft Entra ID 服务主体必须至少对 Azure 资源具有“参与者”或“所有者”权限。

    注意

    .databrickscfg 文件的默认位置位于用户的主目录中。 对于 Linux 和 macOS 为 ~，对于 Windows 为 %USERPROFILE%。

  2. 使用 Databricks CLI 的 --profile 或 -p 选项后跟配置文件的名称，作为 Databricks CLI 命令调用的一部分，例如 databricks account groups list -p <configuration-profile-name> 或 databricks clusters list -p <configuration-profile-name>。

    提示

    可以在 --profile 或 -p 之后按 Tab 以显示可供选择的现有可用配置文件的列表，而不是手动输入配置文件名称。

Azure CLI 身份验证

Azure CLI 身份验证使用 Azure CLI 对登录实体进行身份验证。 另请参阅 Azure CLI 身份验证。

若要配置 Azure CLI 身份验证，必须执行以下操作：

  1. 在本地安装 Azure CLI。

  2. 运行 az login 命令，使用 Azure CLI 登录到 Azure Databricks。 请参阅使用 Azure Databricks 用户帐户登录 Azure CLI。

  3. 在 .databrickscfg 文件中使用以下字段创建或标识 Azure Databricks 配置文件。 如果创建配置文件，请将占位符替换为相应值。

    对于帐户级命令，请在 .databrickscfg 文件中设置以下值：

    [<some-unique-configuration-profile-name>]
host       = <account-console-url>
account_id = <account-id>

    对于工作区级命令，请在 .databrickscfg 文件中设置以下值：

    [<some-unique-configuration-profile-name>]
host = <workspace-url>

    注意

    .databrickscfg 文件的默认位置位于用户的主目录中。 对于 Linux 和 macOS 为 ~，对于 Windows 为 %USERPROFILE%。

  4. 使用 Databricks CLI 的 --profile 或 -p 选项后跟配置文件的名称，作为 Databricks CLI 命令调用的一部分，例如 databricks account groups list -p <configuration-profile-name> 或 databricks clusters list -p <configuration-profile-name>。

    提示

    可以在 --profile 或 -p 之后按 Tab 以显示可供选择的现有可用配置文件的列表，而不是手动输入配置文件名称。

身份验证评估顺序

每当 Databricks CLI 需要收集所需的设置以尝试使用 Azure Databricks 工作区或帐户进行身份验证时，它都会按以下顺序在以下位置搜索这些设置。

  1. 对于 bundle 命令，将搜索项目捆绑包设置文件中的字段值。 （捆绑包设置文件不支持直接包含访问凭据值。）
  2. 环境变量的值，如本文和用于客户端统一身份验证的环境变量和字段中所列。
  3. .databrickscfg 文件中的配置文件字段值，本文前面已列出。

每当 Databricks CLI 找到所需的设置时，它就会停止在其他位置搜索。 例如：

  • Databricks CLI 需要 Azure Databricks 个人访问令牌的值。 已设置 DATABRICKS_TOKEN 环境变量，.databrickscfg 文件还包含多个个人访问令牌。 在此示例中，Databricks CLI 使用 DATABRICKS_TOKEN 环境变量的值并且不搜索 .databrickscfg 文件。
  • databricks bundle deploy -e development 命令需要 Azure Databricks 个人访问令牌的值。 未设置 DATABRICKS_TOKEN 环境变量，.databrickscfg 文件包含多个个人访问令牌。 项目的捆绑包设置文件包含 development 环境声明，该声明通过该文件的 profile 字段引用名为 DEV 的配置文件。 在此示例中，Databricks CLI 在 .databrickscfg 文件中搜索名为 DEV 的配置文件，并使用该配置文件的 token 字段值。
  • databricks bundle run -e development hello-job 命令需要 Azure Databricks 个人访问令牌的值。 未设置 DATABRICKS_TOKEN 环境变量，.databrickscfg 文件包含多个个人访问令牌。 项目的捆绑包设置文件包含 development 环境声明，该声明通过该文件的 host 字段引用特定的 Azure Databricks 工作区 URL。 在此示例中，Databricks CLI 在 .databrickscfg 文件内的配置文件中搜索包含 host 字段并具有匹配工作区 URL 的配置文件。 Databricks CLI 查找匹配的 host 字段，然后使用该配置文件的 token 字段值。