AIP-4115

Default Credentials From Google Virtual Machines

If the client runs on Google virtual machine instance such as Google App Engine or Compute Engine, the auth library may obtain the identity token that is associated with the instance, and use the identity token as the credential to access Google APIs. By using the instance identity, the users no longer need to config their credentials explicitly.

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 default credentials from Google virtual machine environments.

Application Default Credentials

Supporting the default credentials from Google virtual machines is considered as a part of the Application Default Credential. To understand the overall credential flow, please read AIP-4110.

Google Virtual Machine Environments

There are typically two types of Google virtual machine environments where the auth library should obtain the identity token based on the environment type:

• Google App Engine Standard 1.0 (aka 1st generation)
• Compute Engine
  • GCE equivalent runtimes
    • Google App Engine Standard 2.0+
    • Google App Engine Flex
    • Google Cloud Functions
    • Cloud Run
    • Workload Identity on Google Kubernetes Engine

The auth library should depend on the Google App Engine SDK or well defined GAE environment variables to detect if the application is running within the 1st generation Google App Engine environment.

To detect if the application is running on Compute Engine or an equivalent runtime, the auth library should depend on the Metadata Service Library.

Compute Engine or Equivalent Runtime

If the application runs on a Compute Engine instance (or equivalent runtime), the auth library can request the following URL to get an access token associated with instance:

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

In response, the auth library will usually receive a token in the following JSON format:

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

Scopes

Access tokens obtained from the metadata server contain the scopes specified at instance creation. For example, if an instance is granted only the https://www.googleapis.com/auth/storage-full scope for Cloud Storage, then the tokens obtained from the instance's metadata server have only the storage-full scope.

When running on GCE, the metadata server ignores requests for custom scopes. On GCE equivalent runtimes, clients can request a different set of scopes to the metadata server using the scopes url parameter, e.g.:

http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token?scopes=comma-separated-list-of-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 will be transparently ignored by the server (GCE) or fulfilled (GCE equivalent).

Google App Engine Standard 1.0 Runtime

If the application runs on a App Engine Standard 1st generation instance, the auth library should rely on the Google App Engine SDK to retrieve the access token. Here is one example in Go. Essentially the SDK relies on the underlying App Engine Identity service to generate the token.

Like GCE equivalent runtimes, the auth library can specify scopes when requesting the token in the App Engine Standard 1.0 runtime.

Sample code of getting the access token in Go:

import "google.golang.org/appengine"
...
token, exp, err := appengine.AccessToken(context, scopes...)
...

Token Expiration

The access tokens expire after a short period of time. The auth library must get a new token if the existing token expires.

Changelog

• 2020-12-14: Replace note on scopes with more detailed discussion.
• 2021-07-13: Clarify GCE equivalent runtimes