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 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 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 download and install the Docker credential helper from GitHub , or 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 main 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 GCP Console project and its resources.

Service accounts automatically created by GCP, such as the Container Registry service account, are granted the read-write Editor role for your whole project. However, you may wish to grant other service accounts more specific permissions. Configuring Access Control explains the roles that can interact with Container Registry.

You can grant the service account access to the registry containing your Container Registry images.

Alternatively, if a service account is only used for pulling and viewing images, you can set the service account's project-level role to the read-only Viewer from the GCP Console IAM menu. However, the Viewer role has read-only permissions for your whole project and all of its resources, which may not be desired.

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