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-4118

Mutual Authentication Using Workload Credentials

Mutual TLS (a.k.a mTLS) authentication enables authentication of both client and server identities in a TLS handshake. With workload credentials, applications running in Google Cloud can authenticate to Google APIs using X.509 SPIFFE Verifiable Identity Documents (SVIDs). These SVIDs are X.509 certificates that contain SPIFFE IDs specifying the identity of the certificate owners. mTLS authentication using X.509 SVIDs occurs when the client uses an X.509 SVID when performing the TLS handshake.

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 authentication.

Provisioning Workload Credentials in Google Cloud

On Google Cloud, workload credentials should be provisioned using one of the following methods:

• Set up service security with Envoy.

• Set up service security with proxyless gRPC.

In order for workload credentials to be properly used, the auth libraries must support the automatic switching of the service endpoint to its mTLS counterpart.

Using Workload Credentials

Users should configure ADC to use workload credentials via the certificate configuration gcloud metadata file. Workload credentials can be added as a "cert_configs" type as follows:

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

For Linux and macOS platforms, the above metadata file is located in the well-known gcloud config directory at "~/.config/gcloud/certificate_config.json". Note that the default location of this file can be changed using the GOOGLE_API_CERTIFICATE_CONFIG environment variable.

The following lists the fields of the "workload" certificate info type that are relevant to workload credentials:

• "cert_path": The specified value will be used as the full path to locate the workload certificate file. This file must contain a PEM-encoded X.509 certificate chain (ordered from leaf to root) where the leaf certificate is a valid X.509 SVID. The chain may consist of only the leaf certificate.

• "key_path": The specified value will be used as the full path to locate the workload private key file. This file must contain a PEM-formatted private key associated with the X.509 certificate specified by “cert_path”.

The description of the "workload_identity_provider", "authenticate_as_identity_type" and "service_account_email" fields can be found in mTLS Token Binding.

To enable mutual authentication to Google APIs using workload credentials, the "workload" section and its "cert_path" and "key_path" values must be present in the "~/.config/gcloud/certificate_config.json" configuration file.

Expected Behavior

Support for mTLS authentication to Google APIs using workload credentials must give priority to user mTLS endpoint override via client options. The auth libraries must follow the steps below:

• Locate the workload certificate and private key files using the above config file. If one of these files is not present, mTLS using workload credentials may be disabled. The auth libraries must check that the public and private keys in the certificate and key files match before passing them to the TLS library.

  • Occasional mismatches may happen, since during certificate rotation the client library may read the two files while another process is replacing them. In that case, the library must retry reading the certificate and private key files and checking their match status, up to a maximum of four attempts. The library should wait for 5 seconds between attempts.
  • If the certificate and private key files are loaded in memory (as opposed to being read from disk for every mTLS connection), the auth libraries must periodically reload them (at least every 10 minutes or when the certificate expires) to refresh their copies in memory after the infrastructure rotates them. Refreshing the credentials must be done in a background thread and not upon usage.

• Configure the TLS library to use the found, and matched, certificate and key for client authentication during the TLS handshake.

• If the user specifies the endpoint override via client options, use it as is and connect to the specified endpoint using mTLS.

• If the user does not specify the endpoint override, use the default mTLS endpoint if the certificate and key files exist and the default regular endpoint otherwise.

Note that mTLS 1.3 must be the only supported version to preserve client identity and certificate confidentiality.

One implication of the above logic is that if the user enables mTLS authentication using workload credentials, provides valid certificate and key files, and specifies a non-mTLS endpoint override, the client libraries should use the certificate and key anyway and let the server decide what to do. This avoids introducing client-side logic that parses whether the endpoint override is an mTLS URL, since the URL pattern may change at any time.

Obtaining the Default mTLS Endpoint

The default mTLS endpoint for a service should be read from the Discovery Document field "mtlsRootUrl" instead of generated via regex patterns.