使用 OAuth 通过服务主体授权对 Azure Databricks 资源的无人参与的访问

项目
02/09/2025

本主题提供了在自动执行 Azure Databricks CLI 命令或从将从无人参与进程运行的代码调用 Azure Databricks REST API 时授权访问 Azure Databricks 资源的步骤和详细信息。

在 UI 外部与 Azure Databricks 资源交互时，Azure Databricks 使用 OAuth 作为用户授权和身份验证的首选协议。 Azure Databricks 还提供统一的客户端身份验证工具，以自动刷新作为 OAuth 身份验证方法的一部分生成的访问令牌。这适用于服务主体和用户帐户，但您必须为服务主体配置适当的权限和特权，以便其能在操作过程中访问必要的 Azure Databricks 资源。

有关更多的高级别详细信息，请参阅授权访问 Azure Databricks 资源。

使用 Azure Databricks 服务主体时，我的授权和身份验证选项有哪些？

在本主题中，授权是指用于通过委托来协商访问特定 Azure Databricks 资源的协议 (OAuth)。 身份验证 是指凭据表示、传输和验证的机制，在本例中，访问令牌。

Azure Databricks 使用基于 OAuth 2.0 的授权，允许代表有权访问 Azure Databricks 帐户和工作区资源的服务主体从命令行或代码访问这些资源。配置 Azure Databricks 服务主体并在运行 CLI 命令或调用 REST API 时验证其凭据后，会向参与的工具或 SDK 提供 OAuth 令牌，以便从该时间起代表服务主体执行基于令牌的身份验证。 OAuth 访问令牌的生存期为 1 小时，之后所涉及的工具或 SDK 将进行自动后台尝试，以获取同样有效的一小时的新令牌。

Azure Databricks 支持使用 OAuth 为服务主体授予访问权限的两种方法：

大多数情况下，使用 Databricks 统一客户端身份验证支持。如果使用特定的 Azure Databricks SDK（例如 Databricks Terraform SDK）和工具，请使用这种简化的方法。 Databricks 统一客户端身份验证中列出了支持的工具和 SDK。此方法非常适合自动化或其他无人参与的进程方案。
手动，通过直接生成 OAuth 代码验证器/质询对和授权码，并使用它们创建你将在配置中提供的初始 OAuth 令牌。当不使用 Databricks 统一客户端身份验证支持的 API 时，请使用此方法。在这种情况下，你可能需要开发自己的机制来应对你使用的第三方工具或 API 特定的访问令牌的刷新。有关详细信息，请参阅：手动生成和使用访问令牌进行 OAuth 服务主体身份验证。

在开始之前，必须配置 Azure Databricks 服务主体，并为其分配适当的权限，以访问在自动化代码或命令请求资源时必须使用的资源。

先决条件：创建服务主体

帐户管理员和工作区管理员可以创建服务主体。此步骤介绍如何在 Azure Databricks 工作区中创建服务主体。有关 Azure Databricks 帐户控制台本身的详细信息，请参阅管理帐户中的服务主体。

还可以创建Microsoft Entra ID 托管服务主体并将其添加到 Azure Databricks。有关详细信息，请参阅 Databricks 和 Microsoft Entra ID 服务主体。

以工作区管理员身份登录到 Azure Databricks 工作区。
单击 Azure Databricks 工作区顶部栏中的用户名，然后选择“设置”。
单击“身份验证和访问控制”选项卡。
单击“服务主体”旁的“管理”。
单击“添加服务主体”。
单击搜索框中的下拉箭头，然后单击“添加新”。
在“管理”下，选择“Databricks 托管”。
为服务主体输入名称。
单击“添加” 。

服务主体同时添加到工作区和 Azure Databricks 帐户。

步骤 1：向服务主体分配权限

单击服务主体的名称以打开其详细信息页。
在“配置”选项卡上，勾选你希望服务主体在此工作区拥有的每项权利旁边的框，然后单击“更新”。
在“权限”选项卡上，对你想要其管理和使用此服务主体的任何 Azure Databricks 用户、服务主体和组授予访问权限。请参阅管理服务主体上的角色。

步骤 2：为服务主体创建 OAuth 机密

在使用 OAuth 授权访问 Azure Databricks 资源之前，必须先创建 OAuth 机密，该机密可用于生成 OAuth 访问令牌进行身份验证。服务主体最多可以有五个 OAuth 机密。帐户管理员和工作区管理员可以为服务主体创建 OAuth 机密。

在服务主体的详细信息页上，单击“ 机密 ”选项卡。
在 OAuth 机密下，单击“生成机密”。
复制显示的机密和 客户端 ID，然后单击“ 完成”。

机密在创建过程中只显示一次。客户端 ID 与服务主体的应用程序 ID 相同。

帐户管理员还可以从帐户控制台中的服务主体详细信息页生成 OAuth 机密。

作为帐户管理员，登录到帐户控制台。
单击“ 用户管理”。
在 “服务主体 ”选项卡上，选择服务主体。
在 OAuth 机密下，单击“生成机密”。
复制显示的机密和 客户端 ID，然后单击“ 完成”。

注意

若要使服务主体能够使用群集或 SQL 仓库，必须向其授予服务主体访问权限。请参阅计算权限或管理 SQL 仓库。

步骤 3：使用 OAuth 授权

若要将 OAuth 授权与统一客户端身份验证工具配合使用，必须设置以下关联的环境变量、.databrickscfg 字段、Terraform 字段或 Config 字段：

Azure Databricks 主机，指定为 https://accounts.azuredatabricks.net（对于帐户操作）或指定为目标每工作区 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net（对于工作区操作）。
Azure Databricks 帐户 ID（对于 Azure Databricks 帐户操作）。
服务主体客户端 ID。
服务主体机密。

若要执行 OAuth 服务主体身份验证，请根据参与的工具或 SDK 在代码中集成以下内容：

环境

若要将环境变量用于工具或 SDK 的特定 Azure Databricks 身份验证类型，请参阅授权访问 Azure Databricks 资源或工具或 SDK 的文档。另请参阅客户端统一身份验证的环境变量和字段和客户端统一身份验证的默认方法。

对于帐户级操作，请设置以下环境变量：

DATABRICKS_HOST，设置为 Azure Databricks 帐户控制台 URL，https://accounts.azuredatabricks.net。
DATABRICKS_ACCOUNT_ID
DATABRICKS_CLIENT_ID
DATABRICKS_CLIENT_SECRET

对于工作区级操作，请设置以下环境变量：

DATABRICKS_HOST，设置为 Azure Databricks 每工作区 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。
DATABRICKS_CLIENT_ID
DATABRICKS_CLIENT_SECRET

配置文件

在文件中使用以下字段创建或标识 Azure Databricks .databrickscfg。如果创建配置文件，请将占位符替换为相应值。若要将配置文件与工具或 SDK 配合使用，请参阅授权访问 Azure Databricks 资源或参阅工具或 SDK 的文档。另请参阅客户端统一身份验证的环境变量和字段和客户端统一身份验证的默认方法。

对于帐户级操作，请在 .databrickscfg 文件中设置以下值。在本例中，Azure Databricks 帐户控制台 URL 为 https://accounts.azuredatabricks.net：

[<some-unique-configuration-profile-name>]
host          = <account-console-url>
account_id    = <account-id>
client_id     = <service-principal-client-id>
client_secret = <service-principal-secret>

对于工作区级操作，请在 .databrickscfg 文件中设置以下值。在本例中，主机是 Azure Databricks 每工作区 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net：

[<some-unique-configuration-profile-name>]
host          = <workspace-url>
client_id     = <service-principal-client-id>
client_secret = <service-principal-secret>

CLI

对于 Databricks CLI，请执行以下操作之一：

按照本文“环境”部分中所述，设置环境变量。
按照本文“配置文件”部分所述，设置 .databrickscfg 文件中的值。

环境变量始终优先于 .databrickscfg 文件中的值。

另请参阅 OAuth 计算机到计算机 (M2M) 身份验证。

“连接”

注意

以下 Databricks Connect 版本支持 OAuth 服务主体身份验证：

对于 Python，Databricks Connect for Databricks Runtime 14.0 及更高版本。
对于 Scala，为 Databricks Connect for Databricks Runtime 13.3 LTS 及更高版本。 Databricks Connect for Databricks Runtime 13.3 LTS 及更高版本随附的 Databricks SDK for Java 必须升级到 Databricks SDK for Java 0.17.0 或更高版本。

对于 Databricks Connect，可以执行以下操作之一：

按照本文“配置文件”部分所述为 Azure Databricks .databrickscfg设置文件中的值。此外，将配置文件中的 cluster_id 环境变量设置为每工作区 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。
按照本文“环境”部分所述为 Azure Databricks 工作区级操作设置环境变量。此外，将 DATABRICKS_CLUSTER_ID 环境变量设置为每工作区 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。

.databrickscfg 文件中的值始终优先于环境变量。

若要使用文件中的这些环境变量或值 .databrickscfg 初始化 Databricks Connect 客户端，请参阅 Databricks Connect 的计算配置。

VS Code

对于 Visual Studio Code 的 Databricks 扩展，请执行以下操作：

按照本文“配置文件”部分所述为 Azure Databricks .databrickscfg设置文件中的值。
在 Visual Studio Code 的 Databricks 扩展中，单击“配置”窗格中的“配置 Databricks”。
在“命令面板”中，对于“Databricks 主机”，请输入每工作区 URL，例如，然后按。https://adb-1234567890123456.7.azuredatabricks.netEnter
在“命令面板”中，选择 URL 列表中的目标配置文件名称。

有关更多详细信息，请参阅为适用于 Visual Studio Code 的 Databricks 扩展设置身份验证。

Terraform

对于帐户级操作，对于默认身份验证：

provider "databricks" {
  alias = "accounts"
}

对于直接配置（将 retrieve 占位符替换为你自己的实现，以从控制台或 HashiCorp Vault 等其他某个配置存储检索值）。另请参阅保管库提供程序）。在本例中，Azure Databricks 帐户控制台 URL 为 https://accounts.azuredatabricks.net：

provider "databricks" {
  alias         = "accounts"
  host          = <retrieve-account-console-url>
  account_id    = <retrieve-account-id>
  client_id     = <retrieve-client-id>
  client_secret = <retrieve-client-secret>
}

对于工作区级操作，对于默认身份验证：

provider "databricks" {
  alias = "workspace"
}

对于直接配置（将 retrieve 占位符替换为你自己的实现，以从控制台或 HashiCorp Vault 等其他某个配置存储检索值）。另请参阅保管库提供程序）。在本例中，主机是 Azure Databricks 每工作区 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net：

provider "databricks" {
  alias         = "workspace"
  host          = <retrieve-workspace-url>
  client_id     = <retrieve-client-id>
  client_secret = <retrieve-client-secret>
}

有关使用 Databricks Terraform 提供程序进行身份验证的详细信息，请参阅身份验证。

Python

对于帐户级别操作，请将以下内容用于默认身份验证：

from databricks.sdk import AccountClient

a = AccountClient()
# ...

对于直接配置，使用以下内容，将 retrieve 占位符替换为你自己的实现，以从控制台或 Azure KeyVault 等其他配置存储区检索值。在本例中，Azure Databricks 帐户控制台 URL 为 https://accounts.azuredatabricks.net：

from databricks.sdk import AccountClient

a = AccountClient(
  host          = retrieve_account_console_url(),
  account_id    = retrieve_account_id(),
  client_id     = retrieve_client_id(),
  client_secret = retrieve_client_secret()
)
# ...

对于工作区级别操作，特别是默认身份验证，请执行以下代码：

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...

对于直接配置（将 retrieve 占位符替换为你自己的实现，以从控制台或 Azure KeyVault 等其他配置存储区检索值）。在本例中，主机是 Azure Databricks 每工作区 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net：

from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
  host          = retrieve_workspace_url(),
  client_id     = retrieve_client_id(),
  client_secret = retrieve_client_secret()
)
# ...

有关借助使用 Python 并实现 Databricks 客户端统一身份验证的 Databricks 工具和 SDK 进行身份验证的详细信息，请参阅：

注意

Visual Studio Code 的 Databricks 扩展使用 Python，但尚未实现 OAuth 服务主体身份验证。

Java

对于使用默认身份验证的工作区级操作：

import com.databricks.sdk.WorkspaceClient;
// ...
WorkspaceClient w = new WorkspaceClient();
// ...

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.core.DatabricksConfig;
// ...
DatabricksConfig cfg = new DatabricksConfig()
  .setHost(retrieveWorkspaceUrl())
  .setClientId(retrieveClientId())
  .setClientSecret(retrieveClientSecret());
WorkspaceClient w = new WorkspaceClient(cfg);
// ...

有关借助使用 Java 并实现 Databricks 客户端统一身份验证的 Databricks 工具和 SDK 进行身份验证的详细信息，请参阅：

设置适用于 Scala 的 Databricks Connect 客户端（适用于 Scala 的 Databricks Connect 客户端使用随附的 Databricks SDK for Java 进行身份验证）
使用 Azure Databricks 帐户或工作区对 Databricks SDK for Java 进行身份验证

Go

对于使用默认身份验证的帐户级操作：

import (
"github.com/databricks/databricks-sdk-go"
)
// ...
w := databricks.Must(databricks.NewWorkspaceClient())
// ...

对于直接配置（将 retrieve 占位符替换为你自己的实现，以从控制台或 Azure KeyVault 等其他配置存储区检索值）。在本例中，Azure Databricks 帐户控制台 URL 为 https://accounts.azuredatabricks.net：

import (
  "github.com/databricks/databricks-sdk-go"
)
// ...
w := databricks.Must(databricks.NewWorkspaceClient(&databricks.Config{
    Host:         retrieveAccountConsoleUrl(),
    AccountId:    retrieveAccountId(),
    ClientId:     retrieveClientId(),
    ClientSecret: retrieveClientSecret(),
}))
// ...

对于使用默认身份验证的工作区级操作：

import (
  "github.com/databricks/databricks-sdk-go"
)
// ...
a := databricks.Must(databricks.NewAccountClient())
// ...

import (
  "github.com/databricks/databricks-sdk-go"
)
// ...
a := databricks.Must(databricks.NewAccountClient(&databricks.Config{
  Host:         retrieveWorkspaceUrl(),
  ClientId:     retrieveClientId(),
  ClientSecret: retrieveClientSecret(),
}))
// ...

有关借助使用 Go 并实现 Databricks 客户端统一身份验证的 Databricks 工具和 SDK 进行身份验证的详细信息，请参阅使用 Azure Databricks 帐户或工作区对 Databricks SDK for Go 进行身份验证。

手动生成和使用访问令牌进行 OAuth 服务主体身份验证

实现 Databricks 客户端统一身份验证标准的 Azure Databricks 工具和 SDK 将根据需要自动代表您生成、刷新和使用 Azure Databricks OAuth 访问令牌，用于 OAuth 服务主体身份验证。

Databricks 建议使用客户端统一身份验证，但是，如果必须手动生成、刷新或使用 Azure Databricks OAuth 访问令牌，请按照本部分中的说明进行操作。

使用服务主体的客户端 ID 和 OAuth 机密请求 OAuth 访问令牌，以向帐户级 REST API 和工作区级 REST API 进行身份验证。访问令牌将在一小时内过期。必须在过期后请求新的 OAuth 访问令牌。 OAuth 访问令牌的范围取决于你创建令牌处的级别。可在帐户级别或工作区级别创建令牌，如下所示：

若要在服务主体有权访问的帐户和工作区中调用帐户级和工作区级别的 REST API，请在帐户级别手动生成访问令牌。
若要仅在服务主体有权访问的某个工作区中调用 REST API，请仅在工作区级别为该工作区手动生成访问令牌。

手动生成帐户级访问令牌

从帐户级别创建的 OAuth 访问令牌可用于帐户中的 Databricks REST API，并在服务主体有权访问的任何工作区中使用。

作为帐户管理员，登录到帐户控制台。
单击右上角用户名旁边的向下箭头。
复制你的帐户 ID。
通过将以下 URL 中的 <my-account-id> 替换为你复制的帐户 ID 来构造令牌终结点 URL。
```
https://accounts.azuredatabricks.net/oidc/accounts/<my-account-id>/v1/token
```
使用客户端（例如 curl ，使用令牌终结点 URL 请求 OAuth 访问令牌、服务主体的客户端 ID（也称为应用程序 ID）和服务主体创建的 OAuth 机密。范围 all-apis 请求 OAuth 访问令牌，该令牌可用于访问服务主体有权访问的所有 Databricks REST API。
- 将 <token-endpoint-URL> 替换为前面的令牌终结点 URL。
- 将 <client-id> 替换为服务主体的客户端 ID（也称为应用程序 ID）。
- 将 <client-secret> 替换为你创建的服务主体的 OAuth 机密。
```
export CLIENT_ID=<client-id>
export CLIENT_SECRET=<client-secret>

  curl --request POST \
  --url <token-endpoint-URL> \
  --user "$CLIENT_ID:$CLIENT_SECRET" \
  --data 'grant_type=client_credentials&scope=all-apis'
```
这会生成类似于下例的响应：
```
  {
    "access_token": "eyJraWQiOiJkYTA4ZTVjZ…",
    "token_type": "Bearer",
    "expires_in": 3600
  }
```
从响应复制 access_token。

手动生成工作区级访问令牌

从工作区级别创建的 OAuth 访问令牌只能访问该工作区中的 REST API，即使服务主体是帐户管理员还是其他工作区的成员。

通过将 https://<databricks-instance> 替换为你的 Azure Databricks 部署的工作区 URL 来构造令牌终结点 URL：
```
https://<databricks-instance>/oidc/v1/token
```
使用客户端（例如 curl ，使用令牌终结点 URL 请求 OAuth 访问令牌、服务主体的客户端 ID（也称为应用程序 ID）和服务主体创建的 OAuth 机密。范围 all-apis 请求一个 OAuth 访问令牌，该令牌可用于访问服务主体在请求令牌的工作区中访问的所有 Databricks REST API。
- 将 <token-endpoint-URL> 替换为前面的令牌终结点 URL。
- 将 <client-id> 替换为服务主体的客户端 ID（也称为应用程序 ID）。
- 将 <client-secret> 替换为你创建的服务主体的 OAuth 机密。
```
export CLIENT_ID=<client-id>
export CLIENT_SECRET=<client-secret>

curl --request POST \
--url <token-endpoint-URL> \
--user "$CLIENT_ID:$CLIENT_SECRET" \
--data 'grant_type=client_credentials&scope=all-apis'
```
这会生成类似于下例的响应：
```
{
  "access_token": "eyJraWQiOiJkYTA4ZTVjZ…",
  "token_type": "Bearer",
  "expires_in": 3600
}
```
从响应复制 access_token。

调用 Databricks REST API

可以使用 OAuth 访问令牌向 Azure Databricks 帐户级别 REST API 进行身份验证，以及工作区级 REST API。服务主体必须具有帐户管理员权限才能调用帐户级 REST API。

在使用 Bearer 身份验证的授权标头中，请包含访问令牌。也可将此方法用于 curl 或你构建的任何客户端。

帐户级 REST API 请求示例

此示例使用 Bearer 身份验证来获取与帐户关联的所有工作区的列表。

替换为 <oauth-access-token> 在上一步中复制的服务主体的 OAuth 访问令牌。
将 <account-id> 替换为你的帐户 ID。

export OAUTH_TOKEN=<oauth-access-token>

curl --request GET --header "Authorization: Bearer $OAUTH_TOKEN" \
'https://accounts.azuredatabricks.net/api/2.0/accounts/<account-id>/workspaces'

工作区级 REST API 请求示例

此示例使用 Bearer 身份验证列出指定工作区中的所有可用群集。

替换为 <oauth-access-token> 在上一步中复制的服务主体的 OAuth 访问令牌。
将 <workspace-URL> 替换为你的基本工作区 URL，其格式类似于 dbc-a1b2345c-d6e7.cloud.databricks.com。

export OAUTH_TOKEN=<oauth-access-token>

curl --request GET --header "Authorization: Bearer $OAUTH_TOKEN" \
'https://<workspace-URL>/api/2.0/clusters/list'

通过