AIP-4115

Default Credentials For Google Cloud Virtual Environments

If the client runs on Google cloud virtual environments such as Google Compute Engine (GCE), Serverless, or Google Kubernetes Engine (GKE), the auth library may leverage Google’s default mutual TLS (mTLS) credentials and obtain bound tokens for the instance. The auth library may use the default mTLS credentials and bound tokens to access Google APIs.

mTLS authentication enables authentication of both client and server identities in a TLS handshake. Applications running in Google virtual environments 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 owner.

Bound tokens are access tokens that are bound to some property of the credentials used to establish the mTLS connection. The advantage of bound tokens is that they can be used over secure channels established via mTLS credentials with the correct binding information, when appropriate access policies have been put in place. Therefore, using bound tokens is more secure than bearer tokens, which can be stolen and adversarially replayed.

This AIP describes the flow of:

  1. Retrieving a configuration through a metadata server (MDS) endpoint. The configuration specifies how to access Google’s default mTLS credentials.
  2. Requesting bound tokens.

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

Access Default mTLS Credentials

Note: Before trying to use Google’s default mTLS credentials, the client must first check if the remote Google API endpoint supports mTLS. If the remote endpoint does NOT support mTLS, the client should connect to the endpoint using TLS. How to check if an endpoint supports mTLS is out of the scope of this AIP. If the remote endpoint does support mTLS, the client should try to connect using mTLS first before falling back to TLS. How to find the remote API’s mTLS endpoint is out of the scope of this AIP. If users enabled Device Certificate Authentication (DCA), the client should give priority to DCA as mTLS credentials.

To leverage Google’s default mTLS credentials, the client should retrieve configurations from MDS. The MDS in all virtual environments (GCE, Serverless, and GKE) exposes an HTTP endpoint that serves a configuration that specifies how to access Google's default mTLS credentials. This endpoint is called the mTLS configuration endpoint.

The URL of the MDS's mTLS configuration endpoint is: 

http://metadata.google.internal/computeMetadata/v1/instance/platform-security/auto-mtls-configuration

The request to the MDS's mTLS configuration endpoint should be an HTTP GET request without any parameter or payload.

The response from the MDS's mTLS configuration endpoint should contain the following information:

  • The Secure Session Agent address: the client doesn’t have direct access to mTLS credentials. The Secure Session Agent manages default mTLS credentials. The client can only use mTLS credentials through the Secure Session Agent. The address can be an IP:port address or a file path representing a Unix Domain Socket (UDS).

The client must follow the steps below to access Google’s default mTLS credentials.

  1. Check if the remote endpoint supports mTLS.
    • If yes, go to step (2).
    • If not, go to step (3).
  2. Send a request to the MDS's mTLS configuration endpoint. If the request is successful and the response contains a Secure Session Agent address, use the address to access Google's default mTLS credentials, and go to step (4). If the request fails or the response contains an empty address, go to step (3).
  3. Fall back to TLS [END].
  4. Configure the TLS library to use the Secure Session Agent (example) for client authentication during the mTLS handshake.

Request Bound Tokens

To access Google APIs with bound tokens, the client should request tokens from MDS. The MDS in all virtual environments (GCE, Serverless, and GKE) exposes an HTTP endpoint that serves access tokens. This endpoint is called the access token endpoint.

The URL of the MDS's access token endpoint is: 

http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token

The request to the MDS's access token endpoint should be an HTTP GET request. The request may have a “scopes” URL parameter with a list of comma-separated scopes. The auth library should allow the caller to optionally specify a list of custom scopes, and add the “scopes” parameter to the request when needed. Depending on the runtime environment, the request for custom scopes may be transparently ignored or fulfilled by the server.

The response from the MDS's access token endpoint should contain an access token in the following JSON format:

{
      "access_token": "YOUR_ACCESS_TOKEN",
      "expires_in": 3599,
      "token_type": "Bearer"
 }

The client must follow the steps below to request new access tokens for Google APIs if existing tokens expire.

  1. Send an HTTP request to the MDS access token endpoint, retrieve the access token from the response and go to step (2).
  2. Attach the token from step (1) to the request to Google APIs.

Changelog

  • 2020-12-14: Replace note on scopes with more detailed discussion.
  • 2021-07-13: Clarify GCE equivalent runtimes
  • 2023-02-16: Add mTLS configuration endpoint and unify the token binding flow.