tommwq.work/aip

AIP-4119

· [tommwq@126.com]

```org

mTLS Token Binding

Token binding 允许颁发与 mTLS 凭证绑定的 Google 访问令牌。这种与 mTLS 绑定的令牌的优势在于，它们只能在通过其绑定的 mTLS 凭证建立的安全通道上使用。因此，使用绑定令牌比使用可以被窃取并恶意重放的承载令牌更安全。

本 AIP 描述了 (1) 获取与 X.509 证书身份绑定的访问令牌（称为身份绑定令牌）的流程，以及 (2) 如何使用这些令牌通过 Google 认证库访问 Google API。

注意： 由于本 AIP 以语言中立的方式描述指导和要求，因此使用了可能在某些语言或环境中不精确或不合适的通用术语。

指导

如果用户启用令牌绑定，他们**应**通过 ADC 进行。本节描述了支持此类令牌的一般指导。

先决条件

身份绑定访问令牌要求客户端具有 X.509 SPIFFE 可验证身份文档 (SVIDs)。使用工作负载凭证进行相互认证 描述了如何在 Google Cloud 中配置此类 SVIDs。

此外，身份绑定访问令牌要求使用 Google Cloud 的 IAM 配置工作负载身份池和身份提供者。如何执行此操作的说明超出了本 AIP 的范围。

使用 mTLS Token Binding

认证库**必须**支持 "~/.config/gcloud/certificate_config.json" 配置文件中的以下值。请注意，可以使用 `GOOGLE_API_CERTIFICATE_CONFIG` 环境变量更改此文件的默认位置。

```json { “version”: 1 “cert_configs”: { “workload”: { “cert_path”: “path/to/cert/file” “key_path”: “path/to/key/file” “workload_identity_provider”: “…” “authenticate_as_identity_type”: “gsa/native” “service_account_email”: “…” }, “keychain”: { … }, “pkcs11”: { … }, “windows”: { … }, }, “libs”: { … } } ```

以下列出了与 mTLS 令牌绑定配置相关的字段：

  • **“workload_identity_provider”**：指定的值将用于填充请求到安全令牌服务 (STS) 以请求身份绑定访问令牌。此值指的是在 IAM 中配置的工作负载身份池和身份提供者的完全限定名称。指定的值**必须**为以下格式。

``` “workload_identity_provider”:"//iam.googleapis.com/projects/<project_number>/locations/global/workloadIdentityPools/<pool_identifier>/providers/<provider_identifier>" ```

  • **“authenticate_as_identity_type”**：此字段指定用于向 Google API 进行身份验证的身份。值可以设置为 `gsa` 或 `native`，其中 `gsa` 是工作负载的 GCP 服务账户，例如 GCE VM 的 GCP 服务账户，而 `native` 是本地工作负载身份，例如 GKE pod 的 Kubernetes 服务账户。如果未指定，默认值为 `gsa`。

  • **“service_account_email”**：如果设置，指定的值将用于填充请求到 IAM 凭证服务以请求身份绑定访问令牌。此值指的是用于资源访问的服务账户电子邮件。如果未设置，服务账户电子邮件将通过查询以下元数据服务端点自动确定：

`http://metadata/computeMetadata/v1/instance/service-accounts/default/email`。 此字段的值仅在 “authenticate_as_identity_type” 设置为 `gsa` 时相关。

“cert_path” 和 “key_path” 字段的描述可以在 使用工作负载凭证进行相互认证 中找到。

要在与 Google API 通信时启用令牌绑定，需要满足以下条件：

  • 使用工作负载凭证进行相互认证 必须 启用。

  • “workload_identity_provider” 必须 存在，**“authenticate_as_identity_type”* 可以 设置，*“service_account_email”* 可以 设置在 *"~/.config/gcloud/certificate_config.json"* 配置文件的 *“workload”** 部分。

预期行为

为了支持使用身份绑定访问令牌，认证库在向 Google API 发送请求时**必须**遵循以下步骤：

  1. 使用 使用工作负载凭证进行相互认证 中描述的工作负载凭证连接到 STS API 的 mTLS 端点。此端点**必须**为 `sts.mtls.googleapis.com`。

  2. 向 STS 的 ExchangeToken 方法发送 HTTP 请求，使用 "~/.config/gcloud/certificate_config.json" 配置文件中的 “workload_identity_provider” 字段中的信息请求身份绑定令牌。请求的令牌范围**必须**为 `https://www.googleapis.com/auth/iam`。

  3. 使用 使用工作负载凭证进行相互认证 中描述的工作负载凭证连接到 IAM 凭证服务 API 的 mTLS 端点。此端点**必须**为 `iamcredentials.mtls.googleapis.com`。

  4. 如果 “authenticate_as_identity_type” 设置为 `gsa`，则向 IAM 凭证服务的 GenerateAccessToken 方法发送 HTTP 请求，请求身份绑定令牌，断言 "~/.config/gcloud/certificate_config.json" 配置文件中的 “service_account_email” 字段中的服务账户电子邮件。此令牌的范围**必须**与用户定义的访问请求的 Google API 的范围相同。

  5. 将步骤 4 中返回的令牌附加到请求中。请注意，此请求**必须**通过使用步骤 1 中的相同工作负载凭证的 mTLS 通道发送。

```