使用 OAuth 令牌联合认证对 Azure Databricks 的访问

本文指导你配置 OAuth 联合身份验证，以使用标识提供者的令牌访问 Azure Databricks 帐户和工作区资源。

什么是 Databricks OAuth 令牌联合认证？

通过 Databricks OAuth 令牌联合身份验证，可以使用来自身份提供商（IdP）的令牌安全地访问 Databricks 的 API。 OAuth 令牌联合机制消除了管理 Databricks 机密的需求，例如个人访问令牌和 Databricks OAuth 客户端机密。

使用 Databricks OAuth 令牌联合身份验证，用户和服务主体可以从身份提供者交换 JWT（JSON Web 令牌），以获得 Databricks OAuth 令牌，然后可用于访问 Databricks API。

Databricks 支持两种类型的令牌联合：

• 帐户范围的令牌联合 使 Databricks 帐户中的所有用户和服务主体都可以使用标识提供者的令牌访问 Databricks API。 使用帐户范围的令牌联合可以集中管理标识提供者中的令牌颁发策略，并且通常与 SCIM 结合使用，因此标识提供者中的用户将同步到 Azure Databricks 帐户。
• 工作负载身份联合 允许在 Azure Databricks 外部运行的自动化工作负载访问 Databricks APIs，而无需 Databricks 密钥。 通过工作负载身份联合，应用程序（工作负荷）使用工作负荷运行时颁发的令牌以 Databricks 服务主体身份向 Databricks 进行身份验证。

跨帐户令牌联合

帐户管理员可以通过使用帐户联合策略在 Azure Databricks 帐户中配置 OAuth 令牌联合身份验证。 帐户联合策略允许 Azure Databricks 帐户中的所有用户和服务主体使用标识提供者的令牌访问 Databricks API。 帐户联合策略规定了：

• Azure Databricks 将从中接受令牌的标识提供者或颁发者。
• 将令牌映射到相应的 Azure Databricks 用户或服务主体的条件。

若要配置帐户联合策略，请提供以下内容：

• 在令牌声明 中，指定了所需令牌 iss。 颁发者是用于标识您的身份提供者的 HTTPS URL。

• 允许的令牌 受众，在令牌的 aud 声明中指定。 此标识符表示令牌的接收方。 只要令牌中的受众至少匹配策略中的一个受众，令牌就被视为匹配项。 如果未指定，则默认值为 Azure Databricks 帐户 ID。

• 主题声明。 这表示哪个令牌声明包含颁发令牌的用户的 Azure Databricks 用户名。 如果未指定，则默认值为 sub。

• 可以选择使用用于验证令牌签名的公钥（或公钥的 URL），其格式为 JSON Web 密钥集（JWKS）。 如果未指定（推荐），Databricks 会自动从颁发者的已知终结点提取公钥。 Databricks 强烈建议依赖发行者的已知终结点来获取公钥。

  注释

  如果在联合策略中未指定 JWKS 或 jwks_uri，则标识提供者必须在 {issuer-url}/.well-known/openid-configuration 提供 OpenID 提供者元数据服务。 OpenID 提供者元数据必须包含一个 jwks_uri 字段，该字段指定用于验证令牌签名的公钥的地址。

下面是帐户联合策略示例：

issuer: "https://idp.mycompany.com/oidc"
audiences: ["databricks"]
subject_claim: "sub"

以下示例 JWT 正文与上述策略匹配，可用于将用户 username@mycompany.com认证至 Databricks：

{
  "iss": "https://idp.mycompany.com/oidc",
  "aud": "databricks",
  "sub": "username@mycompany.com"
}

配置帐户联合策略

帐户管理员可以使用 Databricks CLI（版本 0.239.0 及更高版本）或 Databricks API 配置帐户联合策略。 可以在 Azure Databricks 帐户中指定最多五个帐户联合策略。

Databricks 命令行界面 (CLI)

1. 安装或更新到最新版本的 Databricks CLI。

2. 作为帐户管理员，请使用 CLI 向 Databricks 帐户进行身份验证。 指定 ACCOUNT_CONSOLE_URL（例如https://accounts.cloud.databricks.com）和您的 Databricks ACCOUNT_ID：

   databricks auth login --host ${ACCOUNT_CONSOLE_URL} --account-id ${ACCOUNT_ID}
   

3. 创建帐户联合策略。 例如：

   databricks account federation-policy create --json \
   '{
     "oidc_policy": {
       "issuer": "https://idp.mycompany.com/oidc",
       "audiences": [
         "databricks"
       ],
       "subject_claim": "sub"
     }
   }'
   

Databricks 帐户 API

下面是用于创建帐户联合策略的示例 Databricks REST API 调用：

curl --request POST \
  --header "Authorization: Bearer $TOKEN" \
  "https://accounts.cloud.databricks.com/api/2.0/accounts/${ACCOUNT_ID}/federationPolicies" \
  --data '{
    "oidc_policy": {
      "issuer": "https://idp.mycompany.com/oidc",
      "audiences": [
        "databricks"
      ],
      "subject_claim": "sub"
    }
  }'

可能需要将标识提供者配置为为用户生成令牌以与 Databricks 交换。 有关如何做的说明，请参阅您的身份提供商的文档。

帐户联合策略示例

工作负载标识联合

工作负荷标识联合允许在 Azure Databricks 外部运行的自动化工作负荷访问 Databricks API，而无需 Databricks 机密。 账户管理员可以使用服务主体联合身份策略配置工作负载身份联合。

服务主体联合策略与 Azure Databricks 帐户中的服务主体相关联，并指定：

• 服务主体可从中进行身份验证的标识提供者（或颁发者）。
• 允许作为 Databricks 服务主体进行身份验证的工作负载标识（或使用者）。

若要配置服务主体联合策略，请提供以下内容：

• 在 声明中指定的工作负荷标识令牌中，所需令牌的发行者是 iss。 颁发者是用于标识工作负载身份提供者的 HTTPS URL。

• 在工作负荷标识令牌的 声明中指定的所需令牌 sub。 主体在工作负荷运行时环境中唯一标识工作负荷。

• 允许的令牌 受众，在工作负荷标识令牌的 aud 声明中被指定。 受众指代令牌的接收方。 只要令牌中的受众至少匹配策略中的一个受众，令牌就被视为匹配项。 如果未指定，则默认值为 Azure Databricks 帐户 ID。

• （可选）用于验证工作负荷标识令牌签名的公钥（或公钥的 URL），采用 JSON Web 密钥集（JWKS）格式。 如果未指定（建议），Azure Databricks 会自动从颁发者的已知终结点提取公钥。 Databricks 强烈建议依赖颁发者的已知终结点来发现公钥。

• （可选）使用者声明。 这表示哪个令牌声明包含令牌的工作负载标识（或使用者）。 如果未指定，则默认值为 sub。 Databricks 强烈建议为工作负载身份联合使用默认的 sub 申明。 除了 sub 以外的声明，应仅在 sub 声明不是适当的或稳定的使用者标识符的情况下使用，这并不常见。 有关详细信息，请参阅下面的 示例服务主体联合策略。

  注释

  如果在联合策略中未指定 JWKS 或 jwks_uri，则标识提供者必须在 {issuer-url}/.well-known/openid-configuration 提供 OpenID 提供者元数据服务。 OpenID 提供者元数据必须包含一个 jwks_uri 字段，该字段指定用于验证令牌签名的公钥的地址。

下面是 Github Actions 工作负荷的示例服务主体联合策略：

issuer: "https://token.actions.githubusercontent.com"
audiences: ["https://github.com/my-github-org"]
subject: "repo:my-github-org/my-repo:environment:prod"

以下示例 JWT 正文与上述策略匹配，可用于对 Azure Databricks 进行身份验证：

{
  "iss": "https://token.actions.githubusercontent.com",
  "aud": "https://github.com/my-github-org",
  "sub": "repo:my-github-org/my-repo:environment:prod"
}

配置服务主体联合策略

帐户管理员可以使用 Databricks CLI（版本 0.239.0 及更高版本）或 Databricks API 配置服务主体联合策略。 每个 Databricks 服务主体最多可以创建五个服务主体联合策略。

Databricks 命令行界面 (CLI)

1. 安装或更新到最新版本的 Databricks CLI。

2. 作为帐户管理员，请使用 CLI 向 Databricks 帐户进行身份验证。 指定 ACCOUNT_CONSOLE_URL（例如https://accounts.cloud.databricks.com）和您的 Databricks ACCOUNT_ID：

   databricks auth login --host ${ACCOUNT_CONSOLE_URL} --account-id ${ACCOUNT_ID}
   

3. 获取将应用联合策略的服务主体的数字 ID。 （例如， 3659993829438643.）

   如果事先知道服务主体应用程序 ID（通常为 GUID 值，例如bc3cfe6c-469e-4130-b425-5384c4aa30bb），则可以使用 Databricks CLI 来确定服务主体的数字 ID。

   databricks account service-principals list --filter 'applicationId eq "<service-principal-application-id>"'
   

4. 创建服务主体联合策略。 下面是为 GitHub Action 创建联合策略的示例：

   databricks account service-principal-federation-policy create ${SERVICE_PRINCIPAL_NUMERIC_ID} --json \
   '{
     "oidc_policy": {
       "issuer": "https://token.actions.githubusercontent.com",
       "audiences": [
         "https://github.com/my-github-org"
       ],
       "subject": "repo:my-github-org/my-repo:environment:prod"
     }
   }'
   

Databricks 帐户 API

1. 获取将应用联合策略的服务主体的数字 ID。 （例如， 3659993829438643.）

   如果事先知道服务主体应用程序 ID（通常为 GUID 值，例如 bc3cfe6c-469e-4130-b425-5384c4aa30bb），这样的话您可以使用 Databricks 服务主体 REST API 确定服务主体数字 ID：

   curl --get \
     --header "Authorization: Bearer $TOKEN" \
     "https://accounts.cloud.databricks.com/api/2.0/accounts/${ACCOUNT_ID}/scim/v2/ServicePrincipals" \
     --data-urlencode 'filter=applicationId eq "<service-principal-application-id>"'
   

   服务主体的数字 ID 在响应的 id 字段中返回。

2. 创建服务主体联合策略。 下面是为 GitHub Action 创建联合策略的示例：

   curl --request POST \
     --header "Authorization: Bearer $TOKEN" \
     "https://accounts.cloud.databricks.com/api/2.0/accounts/${ACCOUNT_ID}/servicePrincipals/${SERVICE_PRINCIPAL_NUMERIC_ID}/federationPolicies" \
     --data '{
       "oidc_policy": {
         "issuer": "https://token.actions.githubusercontent.com",
         "audiences": [
           "https://github.com/my-github-org"
         ],
         "subject": "repo:my-github-org/my-repo:environment:prod"
       }
     }'
   

Databricks 帐户和服务主体联合策略示例

为帐户配置联合策略后，可以使用标识提供者中的 JWT 访问 Databricks API。 为此，请先从标识提供者交换 JWT 令牌以获取 Databricks OAuth 令牌，然后使用 API 调用 Bearer: 字段中的 Databricks OAuth 令牌获取访问权限并完成调用。 令牌必须是使用 RS256 或 ES256 算法签名的有效 JWT。

有关此过程的指导，请参阅 使用标识提供者令牌向 Databricks进行身份验证。

资源

• Databricks 客户端统一身份验证
• 使用 OAuth 通过用户帐户授权对 Azure Databricks 资源的交互式访问
• 使用 OAuth 通过服务主体授权 Azure Databricks 资源的无人值守访问