配置联合策略

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

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

工作负载身份联合

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

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

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

例如，给定 Github Actions 工作负荷的以下服务主体联合策略：

• 发行：https://token.actions.githubusercontent.com
• 观众：https://github.com/my-github-org
• 主题：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 或 Databricks API 配置服务主体联合策略。 每个 Azure Databricks 服务主体最多可以创建 20 个服务主体联合策略。

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

• 颁发者 URL： 一个 HTTPS URL，用于标识工作负荷标识提供者，在工作负荷标识令牌声明中指定的 iss 。

• 主题： 工作负荷运行时环境中工作负荷的唯一标识符。 如果未指定，则默认值为 sub.

• 观众： 令牌的预期接收方，在 aud 声明中指定的。 如果令牌的受众匹配策略中的至少一个受众，则被视为匹配项。 如果未指定，则默认值为 Azure Databricks 帐户 ID。

• 使用者声明： （可选）指定包含令牌的工作负荷标识（也称为使用者）的令牌声明。 如果未设置，Azure Databricks 默认使用 sub 。 Databricks 建议保留工作负荷标识联合的默认 sub 声明。 如果 sub 不是合适的或稳定的使用者标识符，则仅选择其他声明，这很少见。 有关详细信息，请参阅 示例服务主体联合策略。

• 令牌签名验证： （可选）用于验证令牌签名的 JSON Web 密钥集（JWKS）格式的公钥或其 URL。 JWKS JSON 最多支持 5 个密钥。 如果您的标识提供者发布了更多信息，请改用 JWKS URI。

  如果未指定，Azure Databricks 将从颁发者的已知终结点检索密钥，这是建议的方法。 标识提供者必须提供 OpenID 提供程序元数据 <issuer-url>/.well-known/openid-configuration ，该元数据包括指定 jwks_uri 用于验证令牌签名的公钥的位置。

Databricks 用户界面

1. 作为帐户管理员，登录到 Azure Databricks 帐户控制台。https://accounts.azuredatabricks.net
2. 单击“用户管理”。
3. 转到 “服务主体 ”选项卡。
4. 选择要为其创建策略的服务主体。
5. 转到“ 凭据和机密 ”选项卡。
6. 在“ 联合策略 ”选项卡下，单击“ 创建策略”。
7. 选择联合凭据提供程序并配置相应的字段。
8. 单击“创建策略”。

Databricks 命令行界面 (CLI)

无法在 Azure Databricks 工作区 Web 终端 中使用 Azure Databricks CLI 创建联合策略。

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

2. 作为帐户管理员，请使用 CLI 向 Azure Databricks 帐户进行身份验证。 指定ACCOUNT_CONSOLE_URL和Azure DatabricksACCOUNT_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. 从帐户控制台或使用3659993829438643数字 ID（例如）。

2. 创建服务主体联合策略：

   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"
       }
     }'
   

   有关完整的 API 参考文档，请参阅 帐户联合策略 API。

Databricks 服务主体联合策略示例

下表提供示例服务主体联合策略和匹配的 JWT 正文。

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

帐户范围的令牌联合

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

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

例如，给定具有以下字段的联合策略：

• 发行：https://idp.mycompany.com/oidc
• 观众：databricks
• 使用者声明：sub

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

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

配置帐户联合策略

帐户管理员可以使用 Azure Databricks UI、 Databricks CLI 或 Databricks REST API 配置帐户联合策略。 可以在 Azure Databricks 帐户中最多指定 20 个帐户联合策略。

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

• 颁发者 URL： 一个 HTTPS URL，用于标识标识提供者，在令牌声明中指定的 iss 标识提供者。

• 观众： 令牌的预期接收方，在 aud 声明中指定的。 如果令牌的受众匹配策略中的至少一个受众，则被视为匹配项。 如果未指定，则默认值为 Azure Databricks 帐户 ID。

• 使用者声明： 令牌声明，其中包含颁发令牌的用户的 Azure Databricks 用户名。 如果未指定，则默认值为 sub.

• 令牌签名验证： （可选）用于验证令牌签名的 JSON Web 密钥集（JWKS）格式的公钥或其 URL。 JWKS JSON 最多支持 5 个密钥。 如果您的标识提供者发布了更多信息，请改用 JWKS URI。

  如果未指定，Azure Databricks 将从颁发者的已知终结点检索密钥，这是建议的方法。 标识提供者必须提供 OpenID 提供程序元数据 <issuer-url>/.well-known/openid-configuration ，该元数据包括指定 jwks_uri 用于验证令牌签名的公钥的位置。

Databricks 用户界面

1. 作为帐户管理员，登录到 Azure Databricks 帐户控制台。https://accounts.azuredatabricks.net
2. 单击 “设置” 并转到“ 身份验证 ”选项卡。
3. 在 “联合策略”下，单击“ 创建策略”。
4. 输入颁发者 URL、访问群体、使用者声明和可选的令牌签名验证。
5. 单击“创建策略”。

Databricks 命令行界面 (CLI)

无法在 Azure Databricks 工作区 Web 终端 中使用 Azure Databricks CLI 创建联合策略。

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

2. 作为帐户管理员，请使用 CLI 向 Azure Databricks 帐户进行身份验证。 指定ACCOUNT_CONSOLE_URL和 Azure DatabricksACCOUNT_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

以下 Azure 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"
    }
  }'

有关完整的 API 参考文档，请参阅 帐户联合策略 API。

帐户联合策略示例

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

后续步骤

为帐户配置联合策略后：

• 将标识提供者（IdP）配置为生成用户可以与 Azure Databricks 交换的令牌。 有关设置详细信息，请参阅 IdP 的文档。 有关使用常见 IdP 启用工作负荷标识联合的说明，请参阅 在 CI/CD 中启用工作负荷标识联合。
• 使用 IdP 中的 JWT 访问 Azure Databricks API，方法是先将其交换为 Azure Databricks OAuth 令牌。 在 API 调用的标头中包含 Bearer: Azure Databricks OAuth 令牌以完成请求。 JWT 必须有效并使用 RS256 或 ES256 算法进行签名。 有关实现详细信息，请参阅 使用标识提供者令牌进行身份验证。