配置联合策略

通过 Databricks OAuth 令牌联合身份验证，可以使用来自身份提供商（IdP）的令牌安全地访问 Databricks 的 API。 若要启用 OAuth 令牌联合，必须将联合策略配置为 Databricks 帐户范围或工作负荷。

本文介绍如何创建和配置 OAuth 令牌联合策略。

帐户范围的令牌联合

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

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

例如，给定以下帐户联合策略：

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

此 JWT 正文可用于向 Databricks 进行身份验证，如下所示 username@mycompany.com：

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

配置帐户联合策略

若要配置帐户联合策略，必须指定：

• 在令牌声明 中，指定了所需令牌 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 字段，该字段指定用于验证令牌签名的公钥的地址。

帐户管理员可以使用 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"
    }
  }'

帐户联合策略示例

下表提供示例帐户联合策略和匹配的 JWT 正文。

工作负载身份联合

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

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

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

例如，给定 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"
}

配置服务主体联合策略

若要配置服务主体联合策略，必须指定：

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

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

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

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

  注释

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

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

帐户管理员可以使用 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 正文。

有关为其中一些常见标识提供者启用工作负荷标识联合的完整配置步骤，请参阅 在 CI/CD 中启用工作负荷标识联合。

后续步骤

为帐户配置联合策略后：

• 可能需要将标识提供者配置为为用户生成令牌以与 Databricks 交换。 有关如何做的说明，请参阅您的身份提供商的文档。 有关为某些常见标识提供者启用工作负荷标识联合的完整配置步骤，请参阅 在 CI/CD 中启用工作负荷标识联合。
• 可以使用标识提供者中的 JWT 访问 Databricks API。 首先从标识提供者交换 JWT 令牌以获取 Databricks OAuth 令牌，然后使用 API 调用字段中的 Databricks OAuth 令牌 Bearer: 获取访问权限并完成调用。 令牌必须是使用 RS256 或 ES256 算法签名的有效 JWT。 有关实现令牌交换的详细信息，请参阅 使用标识提供者令牌对 Databricks REST API 进行身份验证。