AIP-4114

Device Certificate Authentication via Mutual TLS

Mutual TLS (a.k.a mTLS) authentication enables authentication of both client and server identities in a TLS handshake and provides the foundation for Device Certificate Authentication for Context Aware Access for GCP enterprise customers. With Device Certificate Authentication, the server takes into account the client certificate in the transport layer when making authorization decisions. The use of a client certificate provides a stronger indication of the access originating from a trusted device. This allows enterprise customers to restrict access from untrusted devices.

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

This section describes the general guidance of supporting Device Certificate Authentication (a.k.a. DCA) via mTLS.

Application Default Credentials for DCA

Users should enable DCA through ADC instead of manual configuration via client options.

There are two aspects of ADC for DCA. The first is the automatic procurement of a device certificate. The second is the automatic switching of the service endpoint to the mTLS version of the service endpoint. Clients must support both of these aspects when supporting ADC for DCA.

Expected Behavior

Client support for DCA must give priority to user overrides specified via client options. The following decision tree should be used:

  1. If user specifies both device certificate and endpoint override via client options, use them as is.
  2. If user does not specify device certificate, attempt to procure and use a default device certificate.
  3. If user does not specify endpoint override, use the default mTLS endpoint if a device certificate is available and the default regular endpoint otherwise.

Implications of the above logic:

  1. If user specifies a non-mTLS endpoint override but a device certificate is available, pass along the certificate anyway and let the server decide what to do.
  2. If user specifies an mTLS endpoint override but device certificate is not available, do not fail-fast, but let server return error when connecting.

The above behavior avoids introducing client-side logic that parses whether the endpoint override is an mTLS url, since the url pattern may change at anytime.

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.

Obtaining the Default Device Certificate

The default device certicate should be procured using the EndpointVerification workflow, which fetches the certificate from a platform-specific credential store (ex. KeyChain in macOS) via a native helper.

Exporting the certificate via the native helper involves executing a "cert provider command" specified in a well-known gcloud metadata file of the following format:

{
   "version": 1
   "min_cloud_sdk_version": "240.0.0"
   "has_client_cert": true
   "endpoint_verification_error": ""
   "cert_provider_command": "[absolute_path_to_provider_command] --fetch_client_cert"
}

For Linux and macOS platforms, the above metadata file is located at "~/.secureConnect/context_aware_metadata.json".

The cert provider command will print the certificate to stdout, which will be in the form of an X.509 cert followed immediately by the private key:

-----BEGIN CERTIFICATE-----
Common Name: Google Endpoint Verification
Valid From: November 10, 2019
Valid To: November 10, 2020
Serial Number: 4921083229008411918 (0x444b331faf2dbd0e)
...
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----

Environment Variables

There are situations where the ADC for DCA behavior needs to be modified, such as for integration testing, or for failsafe. To accomodate those scenarios, the following environment variables should be supported.

GOOGLE_API_USE_MTLS_ENDPOINT: If "always", always use mTLS endpoint. If "never", always use regular endpoint. If "auto", use the default behavior, which is to use the mTLS endpoint if a device certificate is available. The default value of this environment variable will be "auto".

GOOGLE_API_USE_CLIENT_CERTIFICATE: If "true", device certificate authentication will be supported as described in the general guidance. If "false", the device certificate must not be used, even if specified by the user. For now, the default value will be "false", since mTLS support is not yet fully adopted by all services. Users who wish to enable DCA feature must explicitly set this environment variable to "true". In the future, the default value will be "true' to allow a more secure connection to be established whenever possible.