使用标识提供者令牌进行身份验证

本页介绍如何使用组织标识提供者颁发的令牌向 Azure Databricks 进行身份验证。

Azure Databricks 支持 OAuth 2.0 令牌交换，以便为 Databricks OAuth 令牌交换联合标识令牌。通过令牌联合，Databricks CLI、SDK 和其他工具可以自动处理此交换并管理访问令牌。

每个访问令牌的生存期派生自你提供的联合令牌的生存期，这通常是一个小时，但可能会有所不同。这些工具会根据需要自动刷新令牌，因此无需手动请求或轮换凭据。

身份验证过程

若要使用联合标识提供者的令牌对 Azure Databricks API 访问进行身份验证，请先设置所需的环境变量或配置字段。首选工具或 SDK 从指定的位置检索联合 JSON Web 令牌（JWT），将其交换为 Azure Databricks OAuth 令牌，并使用 OAuth 令牌对 Azure Databricks REST API 调用进行身份验证。

先决条件

在开始之前，请执行以下步骤：

为帐户或服务主体创建联合策略。
从与策略匹配的标识提供者获取有效的 JWT。必须使用 RS256 或 ES256 对令牌进行签名。这些步骤因提供商而异，因此请参阅提供商的文档或询问管理员。

配置您的环境

根据联合令牌的来源配置环境。设置以下环境变量、 .databrickscfg 字段、Terraform 字段或 Config 字段：

Databricks 主机：https://accounts.databricks.azure.cn 用于帐户作或每个工作区的目标 URL，例如 https://adb-1234567890123456.7.databricks.azure.cn 工作区作。
Databricks 帐户 ID： 仅当主机是帐户控制台 URL 时才是必需的。
服务主体客户端 ID： 只有工作负荷标识联合才需要。如果使用帐户范围的令牌联合策略进行身份验证，则不得设置。
Databricks 身份验证类型：如果令牌来自环境变量，则为。如果令牌来自文件，则为。
OIDC 令牌环境变量： 包含令牌的环境变量的名称。仅当身份验证方法为 env-oidc.. 默认为 DATABRICKS_OIDC_TOKEN。
OIDC 令牌文件路径： 包含联合令牌的文件的路径。仅当身份验证方法为 file-oidc..

有关所有统一身份验证环境变量和配置字段的完整参考，请参阅用于统一身份验证的环境变量和字段。

选择首选配置方法以设置身份验证环境：

环境

设置以下环境变量：

export DATABRICKS_HOST=<workspace-url-or-account-console-url>
export DATABRICKS_ACCOUNT_ID=<account-id>  # If DATABRICKS_HOST is the account console URL
export DATABRICKS_CLIENT_ID=<client-id>    # Only for workload identity federation
export DATABRICKS_AUTH_TYPE=<auth-method> # env-oidc or file-oidc
export DATABRICKS_OIDC_TOKEN_ENV=<token-env-name>  # If auth type is env-oidc
export DATABRICKS_OIDC_TOKEN_FILEPATH=<token-filepath-name> # If auth type is file-oidc

个人资料

使用以下字段创建或标识 .databrickscfg配置文件：

[<profile-name>]
host = <workspace-url-or-account-console-url>
account_id = <account-id>  # If host is the account console URL
client_id = <client-id>    # Only for workload identity federation
auth_type = <auth-method>  # env-oidc or file-oidc
oidc_token_env = <token-env-name>  # If auth type is env-oidc
oidc_token_filepath = <token-filepath-name> # If auth type is file-oidc

CLI

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

设置“ 环境 ”选项卡上指定的环境变量。
根据.databrickscfg”选项卡上指定的设置文件中的值。

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

Connect

对于 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.cn，然后按 Enter。
在命令面板中，在 URL 列表中选择目标配置文件的名称。

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

Terraform

对于帐户级作

provider "databricks" {
  alias = "accounts"
}

对于工作区级作：

provider "databricks" {
  alias = "workspace"
}

Python

对于工作区级作：

from databricks.sdk import WorkspaceClient

# Uses environment configuration automatically
w = WorkspaceClient()

对于帐户级作：

from databricks.sdk import AccountClient

# Uses environment configuration automatically
a = AccountClient()

Java

对于工作区级作：

import com.databricks.sdk.WorkspaceClient;

// Uses environment configuration automatically
WorkspaceClient w = new WorkspaceClient();

对于帐户级作：

import com.databricks.sdk.AccountClient;

// Uses environment configuration automatically
AccountClient a = new AccountClient();

Go

对于工作区级作：

import "github.com/databricks/databricks-sdk-go"

// Uses environment configuration automatically
w := databricks.Must(databricks.NewWorkspaceClient())

对于帐户级作：

import "github.com/databricks/databricks-sdk-go"

// Uses environment configuration automatically
a := databricks.Must(databricks.NewAccountClient())

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

访问 Databricks API

配置环境后，可以正常使用 Databricks CLI 和 SDK。它们会自动处理令牌交换，并使用生成的 OAuth 令牌进行 API 身份验证。

CLI

databricks clusters list

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()  # Uses environment configuration
clusters = w.clusters.list()

Java

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();
List<ClusterDetails> clusters = w.clusters().list();

Go

import "github.com/databricks/databricks-sdk-go"

w := databricks.Must(databricks.NewWorkspaceClient())
clusters := w.Clusters.ListAll(context.Background(), compute.List{})

实现自定义授权提供程序

如果联合令牌来自环境变量或文件以外的源，则可以使用其中一个 Azure Databricks SDK 编写自定义实现来检索联合令牌。

Python

from databricks.sdk import oidc
from databricks.sdk.core import (Config, CredentialsProvider, credentials_strategy, oidc_credentials_provider)

class MyCustomIdTokenSource(oidc.IdTokenSource):
    def id_token(self) -> oidc.IdToken:
        token = ...  # Implement logic to return the ID token here
        return oidc.IdToken(jwt=token)

@credentials_strategy("my-custom-oidc", "")
def my_custom_oidc_strategy(cfg: Config) -> CredentialsProvider:
    return oidc_credentials_provider(cfg, MyCustomIdTokenSource())

if __name__ == "__main__":
    cfg = Config(
        host="https://my-workspace.cloud.databricks.com",
        credentials_strategy=my_custom_oidc_strategy
    )
    from databricks.sdk import WorkspaceClient
    w = WorkspaceClient(config=cfg)
    # Use the client...

Java

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.core.DatabricksConfig;
import com.databricks.sdk.core.TokenProvider;
import com.databricks.sdk.core.Token;
import java.time.Instant;

public class CustomOIDCExample {

    // Custom TokenProvider that returns an OIDC ID token
    static class MyCustomIdTokenSource implements TokenProvider {
        @Override
        public Token getToken() {
            // TODO: Implement logic to fetch or generate the ID token
            String jwt = "...";  // your OIDC token here
            return new Token(jwt, Instant.now().plusSeconds(3600)); // token with expiry
        }
    }

    public static void main(String[] args) {
        // Configure with workspace host
        DatabricksConfig cfg = new DatabricksConfig()
            .setHost("https://my-workspace.cloud.databricks.com")
            .setTokenProvider(new MyCustomIdTokenSource()); // plug in custom OIDC provider

        // Initialize the workspace client
        WorkspaceClient w = new WorkspaceClient(cfg);

        System.out.println("Databricks client initialized: " + w);

        // Use the client...
    }
}

Go

package main

import (
    "context"
    "fmt"

    "github.com/databricks/databricks-sdk-go"
    "github.com/databricks/databricks-sdk-go/config"
    "github.com/databricks/databricks-sdk-go/credentials"
)

// MyCustomIdTokenSource implements a custom OIDC token source
type MyCustomIdTokenSource struct{}

func (s *MyCustomIdTokenSource) IDToken(ctx context.Context) (*credentials.IDToken, error) {
    // TODO: Implement logic to return the ID token
    token := "..."
    return &credentials.IDToken{JWT: token}, nil
}

// myCustomOIDCStrategy is a custom credentials strategy
func myCustomOIDCStrategy(cfg *config.Config) (credentials.CredentialsProvider, error) {
    return credentials.NewOIDCCredentialsProvider(cfg, &MyCustomIdTokenSource{}), nil
}

func main() {
    cfg := &config.Config{
        Host: "https://my-workspace.cloud.databricks.com",
    }

    // Register the custom credentials strategy
    credentials.Register("my-custom-oidc", myCustomOIDCStrategy)

    // Initialize the Databricks workspace client with custom auth
    w, err := databricks.NewWorkspaceClientWithConfig(cfg)
    if err != nil {
        panic(err)
    }

    fmt.Println("Databricks client initialized:", w)
    // Use the client...
}

手动交换令牌

如果不使用 Azure Databricks SDK、CLI 或其他支持统一身份验证的工具，则可以从标识提供者手动交换 JWT 以获取 Databricks OAuth 令牌。为此，请使用 OAuth 2.0 令牌交换（RFC 8693）将请求发送到 Azure Databricks 令牌终结点。

首先从标识提供者获取联合 JWT，并遵循其文档。然后交换 JWT 以获取 Databricks OAuth 令牌，并使用该令牌访问 Databricks REST API：

OAuth 令牌联合过程

交换联合 JWT 以获取 Databricks OAuth 令牌

对于帐户范围的联合策略，此命令交换联合 JWT 作为 Databricks OAuth 令牌：

curl --request POST https://<databricks-workspace-host>/oidc/v1/token \
  --data "subject_token=${FEDERATED_JWT_TOKEN}" \
  --data 'subject_token_type=urn:ietf:params:oauth:token-type:jwt' \
  --data 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data 'scope=all-apis'

小窍门

若要访问 Databricks 帐户资源，请使用 URL https://<databricks-account-host>/oidc/accounts/<account-id>/v1/token。

对于服务主体联合策略，请在请求中包含客户端 ID：

curl --request POST https://<databricks-workspace-host>/oidc/v1/token \
  --data "client_id=${CLIENT_ID}" \
  --data "subject_token=${FEDERATED_JWT_TOKEN}" \
  --data 'subject_token_type=urn:ietf:params:oauth:token-type:jwt' \
  --data 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data 'scope=all-apis'

将 CLIENT_ID 替换为服务主体 UUID（例如，7cb2f8a4-49a7-4147-83db-35cb69e5cede）。

如果标识提供者的令牌有效且与联合策略匹配，则会收到一个标准 JSON 响应，其中包含 access_token 字段中的 Databricks OAuth 令牌。此 OAuth 令牌可用于访问 Databricks API。生成的 Databricks OAuth 令牌的过期（exp）声明与 subject_token 参数中提供的 JWT 相同。

示例响应：

{
  "access_token": "eyJraWQ...odi0WFNqQw",
  "scope": "all-apis",
  "token_type": "Bearer",
  "expires_in": 3600
}

使用 OAuth 令牌调用 Databricks API

然后，可以使用生成的 Databricks OAuth 令牌作为持有者令牌来访问 Databricks API。例如，若要调用 Databricks SCIM Me API 来检索 Databricks 用户和显示名称：

TOKEN='<your-databricks-oauth-token>'

curl --header "Authorization: Bearer $TOKEN" \
  --url https://${DATABRICKS_WORKSPACE_HOSTNAME}/api/2.0/preview/scim/v2/Me

响应应如下所示：

{
  "userName": "username@mycompany.com",
  "displayName": "Firstname Lastname"
}

Last updated on 2025-12-08

Compartir a través de

使用标识提供者令牌进行身份验证

身份验证过程

先决条件

配置您的环境

环境

个人资料

CLI

Connect

VS Code

Terraform

Python

Java

Go

访问 Databricks API

CLI

Python

Java

Go

实现自定义授权提供程序

Python

Java

Go

手动交换令牌

交换联合 JWT 以获取 Databricks OAuth 令牌

使用 OAuth 令牌调用 Databricks API

Recursos adicionales