Advanced Authentication Methods

If your application can't use the gcloud command-line tool to authenticate to the Google Container Registry, you can use docker login directly to authenticate. This allows the use of third-party continuous integration solutions and cluster management technology with Google Container Registry.

The docker login command requires three pieces of information: a username, a password, and an email address. Here we provide information on three different methods of logging in with docker login.

We strongly recommend that you use the gcloud docker command to log in to Google Container Registry when possible. This provides secure, short-lived access to your project resources. These alternatives should only be used when required, and when the security implications are understood.

Using an access token

Access tokens are short-lived tokens that provide read/write access to your Google Cloud Platform resources.

The way the gcloud docker command authenticates Docker commands is to pass a short-lived access token as a password to the Registry. For docker pull and docker search, the access token must contain the devstorage.read_only scope. For docker push, the access token must contain the devstorage.read_write scope.

This same scheme can be used in the absence of the gcloud command-line tool by creating an appropriate access token (such as Compute Engine instance metadata).

The access granted by this token is the same as what is granted when using the gcloud docker command to authenticate, making this the safest of the alternative authentication methods.

In order to log in with an access token, use the following credentials:

Linux / macOS

Username oauth2accesstoken
Password Your access token. For example, $(gcloud auth application-default print-access-token)
Email Unused, must be a well-formed email address (such as 1234@5678.com).

For example:

$ docker login -e 1234@5678.com -u oauth2accesstoken -p "$(gcloud auth application-default print-access-token)" https://gcr.io
Windows

Username oauth2accesstoken
Password Copy-and-paste the output of gcloud auth application-default print-access-token.
Email Unused, must be a well-formed email address (such as 1234@5678.com).

For example:

gcloud auth application-default print-access-token
ya29.8QEQIfY_...

docker login -e 1234@5678.com -u oauth2accesstoken -p "ya29.8QEQIfY_..." https://gcr.io

See Application Default Credentials documentation for more information about using credentials.

Using a JSON key file

A service account JSON key file is a long-lived credential that is scoped to a specific Cloud Platform Console project and its resources. By default, the service account has edit permissions on the project, so exercise caution with the contents of the key file.

If a JSON key is only used for docker pull, you can adjust the service account's role to read-only from the Permissions page of the Cloud Platform Console. Alternatively, you can remove the service account from the project-level ACL and give it the desired access to the underlying Google Cloud Storage bucket.

To create a JSON key file, follow the service account instructions instructions in the Google Cloud Platform Console Help Center. Then use the following credentials:

Linux / macOS

Username _json_key
Password The contents of the key file you downloaded when creating the service account.
Email Unused, must be a well-formed email address (e.g 1234@5678.com).

For example:

docker login -e 1234@5678.com -u _json_key -p "$(cat keyfile.json)" https://gcr.io
Windows

Username _json_key
Password The contents of the key file you downloaded when creating the service account.
Email Unused, must be a well-formed email address (e.g 1234@5678.com).
set /p PASS=<keyfile.json
docker login -e 1234@5678.com -u _json_key -p "%PASS%" https://gcr.io