使用 OAuth 授权服务主体访问 Azure Databricks

2025-09-05

本文介绍如何授权从无人参与的进程（如从脚本或应用程序进行的自动化 CLI 命令或 REST API 调用）访问 Azure Databricks 资源。

Azure Databricks 使用 OAuth 2.0 作为 UI 外部的服务主体授权和身份验证的首选协议。统一客户端身份验证可自动生成和刷新令牌。当服务主体登录并授予许可时，OAuth 会为其颁发 CLI、SDK 或其他工具的访问令牌，以代表其使用。每个访问令牌的有效期为一小时，之后会自动请求一个新令牌。

在本文中，授权是指使用 OAuth 向服务主体授予对 Azure Databricks 资源的访问权限，而 身份验证 是指通过访问令牌验证凭据。

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

授权服务主体的方法

Azure Databricks 支持两种方法来授权服务主体：

自动（建议）： 将统一客户端身份验证与受支持的工具和 SDK（例如 Azure Databricks Terraform SDK）配合使用。此方法会自动处理令牌生成和刷新，非常适合自动化或其他无人参与的工作负荷。
手动： 生成代码验证程序并质询，然后将其交换为 OAuth 令牌。如果工具或 API 不支持统一客户端身份验证，请使用此方法。可能需要为应用程序生成自己的令牌刷新机制。有关详细信息，请参阅手动生成 OAuth M2M 访问令牌。

先决条件

在配置 OAuth 之前，请执行以下步骤：

创建 Azure Databricks 服务主体。请参阅向帐户添加服务主体。
转到服务主体的 “配置 ”选项卡，并选择它对此工作区应具有的权利。
转到 “权限 ”选项卡，授予对想要管理和使用此服务主体的任何 Azure Databricks 用户、服务主体和组的访问权限。请参阅谁可以管理和使用服务主体？

步骤 1：创建 OAuth 机密

若要使用 OAuth 授权访问 Azure Databricks 资源，必须创建 OAuth 机密。机密用于生成用于身份验证的 OAuth 访问令牌。服务主体最多可以有五个 OAuth 机密，每个机密最多可以有效两年。

帐户管理员和工作区管理员可以创建服务主体的 OAuth 机密。

在服务主体的详细信息页中，打开“ 机密 ”选项卡。
在 OAuth 机密下，单击“生成机密”。
设置机密的生存期（最长为 730 天）。
复制显示的机密和客户端 ID，然后单击“ 完成”。机密仅显示一次。客户端 ID 与服务主体的应用程序 ID 相同。

帐户管理员还可以从帐户控制台创建 OAuth 机密。从“ 用户管理 ”选项卡中，选择服务主体，然后转到“ 凭据和机密 ”选项卡。

注意

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

步骤 2：使用 OAuth 授权

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

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

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

环境

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

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

DATABRICKS_HOST，设置为 Azure Databricks 帐户控制台 URL 的值 (https://accounts.databricks.azure.cn)。
DATABRICKS_ACCOUNT_ID
DATABRICKS_CLIENT_ID
DATABRICKS_CLIENT_SECRET

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

DATABRICKS_HOST，设置为 Azure Databricks 每工作区 URL 的值，例如 https://adb-1234567890123456.7.databricks.azure.cn。
DATABRICKS_CLIENT_ID
DATABRICKS_CLIENT_SECRET

配置文件

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

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

[<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.databricks.azure.cn：

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

使用 Azure AD 服务主体进行授权时，配置密钥不同于 Azure Databricks 托管服务主体：

host = https://<workspace-url>
azure_client_id = <azure-service-principal-client-id>
azure_client_secret = <azure-service-principal-secret>
azure_tenant_id = <azure-tenant-id>

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，您可以选择以下操作之一：

使用配置文件：如.databrickscfg”选项卡上所述，在文件中设置工作区级别值。此外，将cluster_id工作区实例 URL 设置为工作区实例 URL。
使用环境变量： 设置与“ 环境 ”选项卡上显示的相同值。此外，将 DATABRICKS_CLUSTER_ID 工作区实例 URL 设置为工作区实例 URL。

.databrickscfg值优先于环境变量。

若要使用这些设置初始化 Databricks Connect，请参阅 Databricks Connect 的计算配置。

VS Code

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

为“.databrickscfg”选项卡上指定的 Azure Databricks 工作区级别作设置文件中的值。
在 Visual Studio Code 的 Databricks 扩展中，单击“配置”窗格中的“配置 Databricks”。
在“命令面板”中，对于“Databricks 主机”，请输入每工作区 URL，例如，然后按。https://adb-1234567890123456.7.databricks.azure.cnEnter
在命令面板中，在 URL 列表中选择目标配置文件的名称。

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

Terraform

帐户级作

对于默认身份验证：

provider "databricks" {
  alias = "accounts"
}

对于直接配置：

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

将 retrieve 占位符替换为你自己的实现，以从控制台或某个其他配置存储（例如 HashiCorp Vault）来检索值。另请参阅保管库提供程序。在这种情况下，Azure Databricks 帐户控制台 URL 为 https://accounts.databricks.azure.cn。

工作区级作

对于默认配置：

provider "databricks" {
  alias = "workspace"
}

对于直接配置：

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

将 retrieve 占位符替换为你自己的实现，以从控制台或某个其他配置存储（例如 HashiCorp Vault）来检索值。另请参阅保管库提供程序。在这种情况下，主机是 Azure Databricks 每工作区 URL，例如 https://adb-1234567890123456.7.databricks.azure.cn。

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

Python

帐户级作

对于默认配置：

from databricks.sdk import AccountClient

a = AccountClient()
# ...

对于直接配置：

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()
)
# ...

将 retrieve 占位符替换为你自己的实现，以从控制台或其他配置存储（例如 Azure KeyVault）检索值。在这种情况下，Azure Databricks 帐户控制台 URL 为 https://accounts.databricks.azure.cn。

工作区级作

对于默认配置：

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...

对于直接配置：

from databricks.sdk import WorkspaceClient

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

将 retrieve 占位符替换为你自己的实现，以从控制台或其他配置存储（例如 Azure KeyVault）检索值。在这种情况下，主机是 Azure Databricks 每工作区 URL，例如 https://adb-1234567890123456.7.databricks.azure.cn。

有关使用 Python 实现客户端统一身份验证的 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 工具和 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())
// ...

对于直接配置：

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 M2M 访问令牌

本部分适用于不支持 Databricks 统一客户端身份验证的工具或服务。如果需要手动生成、刷新或使用 Azure Databricks OAuth 令牌进行 M2M 身份验证，请执行以下步骤。

若要生成 OAuth M2M 访问令牌，请使用服务主体的客户端 ID 和 OAuth 机密。每个访问令牌有效期为一小时。过期后，请求新的令牌。可以在帐户或工作区级别生成令牌：

帐户级别： 用于在服务主体可以访问的帐户和工作区中调用帐户级别和工作区级别的 REST API。请参阅 “生成帐户级访问令牌”。
工作区级别： 用于在单个工作区中调用 REST API。请参阅 “生成工作区级访问令牌”。

生成帐户级访问令牌

使用帐户级令牌为帐户调用 REST API，服务主体可以访问的任何工作区。

找到帐户 ID。
通过将以下 URL 替换为 <account-id> 帐户 ID 来构造令牌终结点 URL。
```
https://accounts.databricks.azure.cn/oidc/accounts/<my-account-id>/v1/token
```
用于 curl 请求 OAuth 访问令牌。进行以下替换：
- <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
}
```
范围 all-apis 请求 OAuth 访问令牌，该令牌允许服务主体调用它有权访问的任何 Databricks REST API。
复制响应中的 access_token 值。

生成工作区级访问令牌

仅对工作区中的 REST API 使用工作区级令牌。

通过 <databricks-instance> 替换为 <databricks-instance> Azure Databricks 工作区实例名称来构造令牌终结点 URL，例如 adb-1234567890123456.7.databricks.azure.cn：
```
https://<databricks-instance>/oidc/v1/token
```

用于 curl 请求 OAuth 访问令牌。进行以下替换：

<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 值。

注意

若要为服务终结点生成令牌，请在请求中包含终结点 ID 和作。请参阅手动提取 OAuth 令牌。

调用 Azure Databricks REST API

使用 OAuth 访问令牌调用帐户级或工作区级 REST API。若要调用帐户级 API，服务主体必须是帐户管理员。

使用身份验证将令牌包含在授权标头 Bearer 中。

帐户级 REST API 请求示例

此示例列出帐户的所有工作区。进行以下替换：

<oauth-access-token> 使用服务主体的 OAuth 访问令牌。
<account-id> 使用帐户 ID。

export OAUTH_TOKEN=<oauth-access-token>

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

工作区级 REST API 请求示例

此示例列出工作区中的所有可用群集。进行以下替换：

<oauth-access-token> 使用服务主体的 OAuth 访问令牌。
<databricks-instance> 使用 Azure Databricks 工作区实例名称，例如 adb-1234567890123456.7.databricks.azure.cn。

export OAUTH_TOKEN=<oauth-access-token>

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

Compartir a través de

使用 OAuth 授权服务主体访问 Azure Databricks

授权服务主体的方法

先决条件

步骤 1：创建 OAuth 机密

步骤 2：使用 OAuth 授权

环境

配置文件

CLI

“连接”

VS Code

Terraform

帐户级作

工作区级作

Python

帐户级作

工作区级作

Java

工作区级作

Go

帐户级作

工作区级作

手动生成 OAuth M2M 访问令牌

生成帐户级访问令牌

生成工作区级访问令牌

调用 Azure Databricks REST API

帐户级 REST API 请求示例

工作区级 REST API 请求示例

其他资源

Recursos adicionales