Advanced Authentication Methods

If your application can't use the gcloud command-line tool to authenticate to 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 your Docker username and password.

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.

Docker credential helper

Docker needs access to Container Registry to push and pull images. You can use the Docker credential helper tool to configure your Container Registry credentials for use with Docker.

The credential helper fetches your Container Registry credentials—either automatically, or from a location specified using its --token-source flag—then writes them to Docker's configuration file. This way, you can use Docker's command-line tool, docker, to interact directly with Container Registry.

You can install the Docker credential helper tool via the gcloud command-line tool:

gcloud components install docker-credential-gcr

Then, configure Docker to use your Container Registry credentials when interacting with Container Registry:

docker-credential-gcr configure-docker

See the credential helper documentation for more information.

Using an access token

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

The gcloud docker command authenticates Docker commands by passing a short-lived access token as a password to Container Registry.

  • For docker pull and docker search, the access token must use the devstorage.read_only scope.
  • For docker push, the access token must use 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.

To use an access token, see the Application Default Credentials documentation. Then, use the following credentials:

Linux / macOS

Username oauth2accesstoken
Password Your access token. For example, $(gcloud auth application-default print-access-token)

For example:

docker login -u oauth2accesstoken -p "$(gcloud auth application-default print-access-token)"

Username oauth2accesstoken
Password Copy-and-paste the output of gcloud auth application-default print-access-token.

For example:

gcloud auth application-default print-access-token

docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..."

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. If a service account JSON key is only used for docker pull, set 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 access control list and give it the desired access to the underlying Google Cloud Storage bucket.

To use 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.

For example:

docker login -u _json_key -p "$(cat keyfile.json)"

Username _json_key
Password The contents of the key file you downloaded when creating the service account.

For example:

set /p PASS=<keyfile.json
docker login -u _json_key -p "%PASS%"

See the service accounts documentation to learn more about configuring service accounts.

Send feedback about...

Container Registry