使用 OAuth 授权用户访问 Azure Databricks

2025-09-19

本文介绍如何在使用 Azure Databricks CLI 或 Azure Databricks REST API 时授权用户访问 Azure Databricks 资源。

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

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

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

授权访问 Azure Databricks 资源的方法

Azure Databricks 支持使用 OAuth 授权用户帐户的两种方法：

自动（建议）： 如果使用受支持的工具和 SDK（例如 Azure Databricks Terraform SDK），请使用统一身份验证。此方法会自动处理令牌生成和刷新。
手动： 生成代码验证程序并质询，然后将其交换为 OAuth 令牌。如果工具不支持统一身份验证，请使用此方法。有关详细信息，请参阅手动生成 OAuth U2M 访问令牌。

使用统一身份验证进行自动授权

注意

在配置授权之前，请查看计划执行的工作区作类型的 ACL 权限，并确认帐户具有所需的访问级别。有关详细信息，请参阅访问控制列表。

若要使用支持统一身份验证的 Azure Databricks SDK 和工具执行 OAuth 授权，请在代码中集成以下内容：

环境

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

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

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

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

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

配置文件

在文件中使用以下字段创建或标识 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>

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

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

CLI

对于 Azure Databricks CLI，请使用以下选项运行 databricks auth login 命令：

对于帐户级作， --host https://accounts.cloud.databricks.com --account-id <account-id>
对于工作区级作， --host <workspace-url>

然后，按照 Web 浏览器中的说明登录到 Azure Databricks 帐户或工作区。

有关详细信息，请参阅使用 Databricks CLI 时的 OAuth 授权。

VS Code

对于 Visual Studio Code 的 Databricks 扩展，请按照为 Visual Studio Code 的 Databricks 扩展设置授权中的步骤作。

连接

Databricks Connect 支持从 Databricks Runtime 13.1 开始的用于 Python 的 OAuth U2M 身份验证，以及从 Databricks Runtime 13.3 LTS 开始的 Scala 身份验证。

对于 Databricks Connect，您可以选择以下操作之一：

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

.databrickscfg值优先于环境变量。

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

Terraform

在应用 Terraform 配置之前，必须在 databricks auth login 选项卡上运行其中一个命令，具体取决于配置是使用工作区还是帐户作。这些命令会在用户的主文件夹中生成并缓存所需的 OAuth 令牌 .databricks/token-cache.json 。

帐户级作

对于默认身份验证：

provider "databricks" {
  alias = "account"
}

对于直接配置：

provider "databricks" {
  alias      = "account"
  host       = <retrieve-account-console-url>
  account_id = <retrieve-account-id>
}

将 retrieve- 占位符替换为你自己的实现，以从控制台或某个其他配置存储（例如 HashiCorp Vault）来检索值。另请参阅保管库提供程序。在此示例中，可以设置为 account_id Azure Databricks 帐户控制台 URL。

工作区级作

对于默认身份验证：

  provider "databricks" {
  alias = "workspace"
}

对于直接配置：

provider "databricks" {
  alias = "workspace"
  host  = <retrieve-workspace-url>
}

Python

在运行代码之前，必须使用工作区或帐户作选项在 databricks auth login 选项卡上运行命令。这些命令会在用户的主文件夹中生成并缓存所需的 OAuth 令牌 .databricks/token-cache.json 。

帐户级作

对于默认身份验证：

from databricks.sdk import AccountClient

a = AccountClient()
# ...

对于直接配置：

from databricks.sdk import AccountClient

a = AccountClient(
  host       = retrieveAccountConsoleUrl(),
  account_id = retrieveAccountId()
)
# ...

将 retrieve 占位符替换为你自己的实现，以从控制台或其他一些配置存储（例如 Azure KeyVault）检索值。

工作区级作

对于默认身份验证：

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...

对于直接配置：

from databricks.sdk import WorkspaceClient

w = WorkspaceClient(host = retrieveWorkspaceUrl())
# ...

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

Java

帐户级作

对于默认身份验证：

import com.databricks.sdk.AccountClient;
// ...
AccountClient a = new AccountClient();
// ...

对于直接配置：

import com.databricks.sdk.AccountClient;
import com.databricks.sdk.core.DatabricksConfig;
// ...
DatabricksConfig cfg = new DatabricksConfig()
  .setHost(retrieveAccountConsoleUrl())
  .setAccountId(retrieveAccountId());
AccountClient a = new AccountClient(cfg);
// ...

将 retrieve 占位符替换为你自己的实现，以从控制台或其他一些配置存储（例如 Azure KeyVault）检索值。

工作区级作

对于默认身份验证：

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())
WorkspaceClient w = new WorkspaceClient(cfg);
// ...

有关使用 Java 和实现 Databricks 统一身份验证的 Azure Databricks 工具和 SDK 进行授权和身份验证的详细信息，请参阅：

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

Go

帐户级作

对于默认身份验证：

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:      retrieveAccountConsoleUrl(),
  AccountId: retrieveAccountId(),
}))
// ...

将 retrieve 占位符替换为你自己的实现，以从控制台或其他一些配置存储（例如 Azure KeyVault）检索值。

工作区级作

对于默认身份验证：

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: retrieveWorkspaceUrl(),
}))
// ...

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

手动生成 OAuth U2M 访问令牌

本部分适用于使用不支持 Databricks 统一身份验证标准的第三方工具或服务的用户。如果需要手动生成、刷新或使用用于 OAuth U2M 身份验证的 Azure Databricks OAuth 令牌，请按照本节中的步骤作。

步骤 1：生成代码验证器和质询

若要手动生成 OAuth U2M 访问令牌，请先创建 代码验证器和 匹配 的代码质询。你将使用步骤 2 中的质询来获取授权代码，步骤 3 中的验证程序将代码交换为访问令牌。

注意

遵循 OAuth PKCE 标准：

代码验证程序是一个使用字符（43-128 个字符）的加密随机字符串（A-Za-z0-943-128 个字符）。-._~
代码质询是验证程序 Base64 URL 编码的 SHA256 哈希。

有关详细信息，请参阅授权请求。

以下 Python 脚本生成验证者和质询。尽管可以多次使用它们，但 Azure Databricks 建议每次手动生成访问令牌时生成一个新对。

import hashlib, base64, secrets, string

# Allowed characters for the code verifier, per PKCE spec
allowed_chars = string.ascii_letters + string.digits + "-._~"

# Generate a secure code verifier (43-128 characters)
code_verifier = ''.join(secrets.choice(allowed_chars) for _ in range(64))

# Create the SHA256 hash of the code verifier
sha256_hash = hashlib.sha256(code_verifier.encode()).digest()

# Base64-url-encode the hash and strip any trailing '=' padding
code_challenge = base64.urlsafe_b64encode(sha256_hash).decode().rstrip("=")

# Output values
print(f"code_verifier:  {code_verifier}")
print(f"code_challenge: {code_challenge}")

步骤 2：生成授权代码

若要获取 Azure Databricks OAuth 访问令牌，必须先生成 OAuth 授权代码。此代码在使用后立即过期。可以在帐户或工作区级别生成代码：

帐户级别： 用于跨用户可访问的所有工作区调用帐户级和工作区级 REST API。
工作区级别： 用于在单个工作区中调用 REST API。

注意

这些示例用作 databricks-cli 客户端 ID。如果不使用内置的 Azure Databricks 工具（如 CLI 或 SDK），则必须启用自定义 OAuth 应用程序并在请求中使用它 client_id 。请参阅启用或禁用合作伙伴 OAuth 应用程序。

生成帐户级授权代码

找到帐户 ID。
在浏览器中，使用以下替换项导航到 URL：
- <account-id>：Azure Databricks 帐户 ID
- <redirect-url>：本地重定向 URI（例如 http://localhost:8020）
- <state>：用于验证响应的任何纯文本字符串
- <code-challenge>：步骤 1 中的代码质询
```
https://accounts.databricks.azure.cn/oidc/accounts/<account-id>/v1/authorize
?client_id=databricks-cli
&redirect_uri=<redirect-url>
&response_type=code
&state=<state>
&code_challenge=<code-challenge>
&code_challenge_method=S256
&scope=all-apis+offline_access
```
当系统提示访问 Azure Databricks 帐户时登录。
从浏览器的地址栏中复制授权代码。它是重定向 URL 之后 code= 和之前 & 的值：
```
http://localhost:8020/?code=dcod...7fe6&state=<state>
```
验证该值是否 state 与最初提供的值匹配。如果没有，请放弃代码。
继续生成帐户级访问令牌。

生成工作区级授权代码

在浏览器中，使用以下替换项导航到 URL：
- <databricks-instance>：使用 <databricks-instance> Azure Databricks 工作区实例名称，例如 adb-1234567890123456.7.databricks.azure.cn
- <redirect-url>：本地重定向（例如 http://localhost:8020）
- <state>：响应验证的任何纯文本值
- <code-challenge>：步骤 1 中的质询字符串
```
https://<databricks-instance>/oidc/v1/authorize
?client_id=databricks-cli
&redirect_uri=<redirect-url>
&response_type=code
&state=<state>
&code_challenge=<code-challenge>
&code_challenge_method=S256
&scope=all-apis+offline_access
```
当系统提示访问 Azure Databricks 帐户时登录。
从浏览器的地址栏中复制授权代码。它是重定向 URL 之后 code= 和之前 & 的值：
```
http://localhost:8020/?code=dcod...7fe6&state=<state>
```
验证该值是否 state 与最初提供的值匹配。如果没有，请放弃代码。
继续生成工作区级访问令牌。

步骤 3：交换访问令牌的授权代码

若要交换 Azure Databricks OAuth 访问令牌的授权代码，请选择适当的级别：

帐户级别： 用于跨用户可以访问的所有工作区调用帐户级和工作区级 REST API。
工作区级别： 用于在单个工作区中调用 REST API。

生成帐户级访问令牌

用于 curl 交换 OAuth 访问令牌的帐户级授权代码。

替换请求中的以下内容：

<account-id>：Azure Databricks 帐户 ID
<redirect-url>：上一步中的重定向 URL
<code-verifier>：前面生成的验证程序
<authorization-code>：上一步中的授权代码

curl --request POST \
https://accounts.databricks.azure.cn/oidc/accounts/<account-id>/v1/token \
--data "client_id=databricks-cli" \
--data "grant_type=authorization_code" \
--data "scope=all-apis offline_access" \
--data "redirect_uri=<redirect-url>" \
--data "code_verifier=<code-verifier>" \
--data "code=<authorization-code>"

复制响应中的 access_token 值。例如：

{
  "access_token": "eyJr...Dkag",
  "refresh_token": "doau...f26e",
  "scope": "all-apis offline_access",
  "token_type": "Bearer",
  "expires_in": 3600
}

令牌有效期为一小时。

继续执行步骤 4：调用 Azure Databricks REST API。

生成工作区级访问令牌

用于 curl 交换 OAuth 访问令牌的工作区级授权代码。

替换请求中的以下内容：
- <databricks-instance>：使用 <databricks-instance> Azure Databricks 工作区实例名称，例如 adb-1234567890123456.7.databricks.azure.cn
- <redirect-url>：上一步中的重定向 URL
- <code-verifier>：前面生成的验证程序
- <authorization-code>：工作区级授权代码
```
curl --request POST \
https://<databricks-instance>/oidc/v1/token \
--data "client_id=databricks-cli" \
--data "grant_type=authorization_code" \
--data "scope=all-apis offline_access" \
--data "redirect_uri=<redirect-url>" \
--data "code_verifier=<code-verifier>" \
--data "code=<authorization-code>"
```

复制响应中的 access_token 值。例如：

{
  "access_token": "eyJr...Dkag",
  "refresh_token": "doau...f26e",
  "scope": "all-apis offline_access",
  "token_type": "Bearer",
  "expires_in": 3600
}

令牌有效期为一小时。

步骤 4：调用 Azure Databricks REST API

根据访问令牌的范围，使用访问令牌调用帐户级或工作区级 REST API。若要调用帐户级 API，Azure Databricks 用户必须是帐户管理员。

帐户级 REST API 请求示例

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

将 <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 请求示例

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

将 <oauth-access-token> 替换为帐户级或工作区级 OAuth 访问令牌。
将 <databricks-instance> 替换为 Azure Databricks <databricks-instance>（例如 adb-1234567890123456.7.databricks.azure.cn）。

export OAUTH_TOKEN=<oauth-access-token>

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

共用方式為

使用 OAuth 授权用户访问 Azure Databricks

授权访问 Azure Databricks 资源的方法

使用统一身份验证进行自动授权

环境

配置文件

CLI

VS Code

连接

Terraform

帐户级作

工作区级作

Python

帐户级作

工作区级作

Java

帐户级作

工作区级作

Go

帐户级作

工作区级作

手动生成 OAuth U2M 访问令牌

步骤 1：生成代码验证器和质询

步骤 2：生成授权代码

生成帐户级授权代码

生成工作区级授权代码

步骤 3：交换访问令牌的授权代码

生成帐户级访问令牌

生成工作区级访问令牌

步骤 4：调用 Azure Databricks REST API

帐户级 REST API 请求示例

工作区级 REST API 请求示例

其他資源