This AIP is currently a draft. This means that it is being actively debated and discussed, and it may change in non-trivial ways.

AIP-4119

mTLS Token Binding

Token binding allows issuing Google access tokens that are bound to mTLS credentials. The advantage of such mTLS bound tokens is that they are meant to only be used over secure channels established via mTLS credentials they are bound to. Therefore, using bound tokens is more secure than bearer tokens which can be stolen and adversarially replayed.

This AIP describes the flow of (1) obtaining access tokens bound to X.509 certificate identities, called identity-bound tokens and (2) how to use them to access Google APIs using the Google auth libraries.

Note: Because this AIP describes guidance and requirements in a language-neutral way, it uses generic terminology which may be imprecise or inappropriate in certain languages or environments.

Guidance

If users enable token binding, they should do so via ADC. This section describes the general guidance of supporting such tokens.

Prerequisites

Identity-bound access tokens require that the clients have X.509 SPIFFE Verifiable Identity Documents (SVIDs). Mutual Authentication Using Workload Credentials describes how such SVIDs are provisioned in Google Cloud.

Additionally, identity-bound access tokens tokens require configuring a workload identity pool and identity provider with Google Cloud's IAM. The instructions on how to do this are out of scope of this AIP.

Using mTLS Token Binding

The auth libraries must support the following values in the "~/.config/gcloud/certificate_config.json" configuration file. Note that the default location of this file can be changed using the GOOGLE_API_CERTIFICATE_CONFIG environment variable.

{
  "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": {
   ...
  }
}

The following lists the fields relevant to mTLS token binding configuration:

  • "workload_identity_provider": The specified value will be used to populate the request to Security Token Service (STS) to request identity-bound access tokens. This value refers to the fully qualified name of the workload identity pool and identity provider configured in IAM. The specified value must be of the following format.
"workload_identity_provider":"//iam.googleapis.com/projects/<project_number>/locations/global/workloadIdentityPools/<pool_identifier>/providers/<provider_identifier>"

  • "authenticate_as_identity_type": This field specifies what identity is used to authenticate to Google APIs. The value can be set to gsa or native, where gsa is the GCP service account of the workload, e.g., the GCP service account of a GCE VM, and native is the native workload identity, e.g., the GKE pod kubernetes service account. If not specified, the default value is gsa.

  • "service_account_email": If set, the specified value will be used to populate the request to the IAM Credentials service to request identity-bound access tokens. This value refers to the service account email to be used for resource access. If not set, the service account email will be determined automatically by querying the following Metadata Service endpoint: http://metadata/computeMetadata/v1/instance/service-accounts/default/email. The value of this field is only relevant if "authenticate_as_identity_type" is set to gsa.

The description of the "cert_path" and "key_path" fields can be found in Mutual Authentication Using Workload Credentials.

To enable using token binding when communicating with Google APIs the following conditions are required:

  • Mutual Authentication Using Workload Credentials must be enabled.

  • The "workload_identity_provider" must be present, "authenticate_as_identity_type" may be set and "service_account_email" may be set in the "workload" section of the "~/.config/gcloud/certificate_config.json" configuration file.

Expected Behavior

To support the usage of identity-bound access tokens, the auth libraries must follow the steps below when sending requests to Google APIs:

  1. Connect to the mTLS endpoint of the STS API using the workload credentials provisioned as described in Mutual Authentication Using Workload Credentials. This endpoint must be sts.mtls.googleapis.com.

  2. Send an HTTP request to STS’s ExchangeToken method requesting an identity-bound token using the information in the "workload_identity_provider" field in the "~/.config/gcloud/certificate_config.json" configuration file. The scope of the requested token must be https://www.googleapis.com/auth/iam.

  3. Connect to the mTLS endpoint of the IAM Credentials Service API using the workload credentials provisioned as described in Mutual Authentication Using Workload Credentials. This endpoint must be iamcredentials.mtls.googleapis.com.

  4. If "authenticate_as_identity_type" is set to gsa, send an HTTP request to the IAM Credentials Service’s GenerateAccessToken method requesting an identity bound token asserting the service account email in the "service_account_email" field in the "~/.config/gcloud/certificate_config.json" configuration file. The scope of this token must be the same scope defined by the user for accessing the requested Google API.

  5. Attach the returned token in Step 4 to the request. Note that this request must be sent over an mTLS channel using the same workload credentials in Step 1.