gcloud CLI Integration
Number	4113
Permalink	google.aip.dev/auth/4113
Scope	Auth
State	Approved
Created	2020-07-31
Updated	2020-07-31

AIP-4113

gcloud CLI Integration

gcloud is the CLI that manages authentication, local configuration, developer workflow, and interactions with the Google Cloud Platform (GCP) APIs. gcloud can generate default credentials by obtaining user access credentials via 3-legged OAuth (3LO) web flow and saving them to well-known locations in JSON format. These credentials are intended to be consumed by applications other than gcloud. Application Default Credentials (ADC) and Google Unified Auth Clients (GUAC) must support the gcloud default credentials.

Note: Although the sample code is written in Python, 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 the gcloud default credentials.

Credentials Generation

gcloud default credentials can be generated via command ‘gcloud auth application-default login’.

$ gcloud auth application-default login

The generated credentials are saved to well-known locations which vary as platforms:

Linux, Mac: \$HOME/.config/gcloud/application_default_credentials.json
Windows: %APPDATA%/gcloud/application_default_credentials.json

Below is an example of the gcloud default credentials,

{
  "client_id": "fake_id.apps.googleusercontent.com",
  "client_secret": "fake_secret",
  "quota_project_id": "fake_project",
  "refresh_token": "fake_token",
  "type": "authorized_user"
}

All the fields are populated by the login response from the Google authorization backend except for ‘quota_project_id’ which is retrieved from gcloud’s context. Additionally, the users can override ‘quota_project_id’ with the ‘--client-id-file’ flag,

$ gcloud auth application-default login --client-id-file=clientid.json

Expected Behaviors

The auth libraries will use the information in the gcloud default credentials to exchange access tokens with Google authorization backend. The resulting access tokens will be further used by applications to call GCP APIs.

The auth libraries and applications must follow the steps below:

The auth library loads the gcloud default credentials from the well-known location (see previous section) of the platform on which it runs.
The auth library calls Google authorization backend with the refresh token, client ID and client secret in the gcloud default credentials and procures an access token. The URL for acquiring access tokens from Google authorization backend is https://oauth2.googleapis.com/token. Below is an example code with google-auth as the auth library and urllib3 as the http transport.

from google.oauth2 import _client as google_auth_client
import google.auth.transport.urllib3 as google_auth_urllib3
import urllib3

# Create an http transport for communicating with Google authorization backend.
http = urllib3.PoolManager()
request = google_auth_urllib3.Request(http)

# Build parameters for the access token request. Assume the gcloud default
# credentials are deserialized are into a dictionary ‘gcloud_default’
# in the previous step.
token_uri = 'https://oauth2.googleapis.com/token'
refresh_token = gcloud_default['refresh_token']
client_id = gcloud_default['client_id']
client_secret = gcloud_default['client_secret']
scopes = ['https://www.googleapis.com/auth/cloud-platform']

# Obtain an access token.
access_token, _, _, _ = google_auth_client.refresh_grant(
  request, token_uri, refresh_token, client_id, client_secret, scopes)

The application calls GCP API with the access token obtained from the previous step. ‘quota_project_id’ in the gcloud default credentials should be added to the ‘X-Goog-User-Project’ http header so that the associated account will be charged for billing and quota.