Authentication methods

This page describes how to configure authentication to Container Registry.

Before you begin

Make sure that you have:

  1. Installed the most recent version of the Cloud SDK, which includes the gcloud command-line tool

  2. Installed Docker.

Choosing an authentication method

The following authentication methods are available:

gcloud as credential helper (Recommended)
Configure your Container Registry credentials for use with Docker directly in gcloud. Use this method when possible for secure, short-lived access to your project resources. This option only supports Docker versions 18.03 or above.
Standalone Docker credential helper
This option is primarily for configuring your credentials for use with Docker in the absence of Cloud SDK. This option only supports Docker versions 18.03 or above.
Access token
Application Default Credentials provide short-lived access tokens that a service account uses to access your Google Cloud resources. It is the safest of the alternatives to using gcloud as a credential helper.
JSON key file

A user-managed key-pair that you can use as a credential for a service account. Because the credential is long-lived, it is the least secure option of all the available authentication methods.

When possible, use Application Default Credentials or another available authentication method to reduce the risk of unauthorized access to your artifacts. If you must use a service account key, ensure that you follow best practices for managing credentials.

Some tools or workflows do not provide good support for using gcloud as a credential helper. If you use one of the alternative options, ensure that you understand security implications.

gcloud as a Docker credential helper

We strongly recommend that you use this method when possible. It provides secure, short-lived access to your project resources.

To authenticate to Container Registry, use gcloud as a Docker credential helper. To do so, run the following command:

gcloud auth configure-docker

You need to run this command once to authenticate to Container Registry.

Standalone Docker credential helper

Docker needs access to Container Registry to push and pull images. You can use docker-credential-gcr, the Docker credential helper which does not require gcloud, 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.

To use the Docker credential helper:

  1. Download docker-credential-gcr from GitHub releases:

    You may optionally using the curl command-line utility. For example:

    VERSION=2.0.0
    OS=linux  # or "darwin" for OSX, "windows" for Windows.
    ARCH=amd64  # or "386" for 32-bit OSs, "arm64" for ARM 64.
    
    curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \
      | tar xz --to-stdout ./docker-credential-gcr \
      > /usr/bin/docker-credential-gcr && chmod +x /usr/bin/docker-credential-gcr
      ```
    
  2. Configure Docker to use your Container Registry credentials when interacting with Container Registry (you are only required to do this once):

    docker-credential-gcr configure-docker
    

    See docker-credential-gcr's main documentation on GitHub for more information.

  3. If the service account is for pushing or pulling images from a Compute Engine VM instance, configure the access scopes for the required level of access.

Access token

An access token is a short-lived credential that provides access to your Google Cloud resources. You can use an access token as a password to connect to Container Registry.

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

  1. Obtain the key for the service account that will interact with Container Registry.

    Console

    1. In Google Cloud Console, open the Service account keys page.

    Go to the Create Service Account Key page

    1. From the Service account list, select the service account that you want to use.

      To create a new service account, choose New service account and specify the service accont name, ID, and appropriate Container Registry role based on the permissions you want to grant to the service account.

    2. Select JSON as the key type.

    3. Click Create. A JSON file that contains your key downloads to your computer.

      The instructions on this page use the file name keyfile.json for this key file.

    gcloud

    You can run the following commands using Cloud SDK on your local machine, or in Cloud Shell.

    1. Create the service account. Replace NAME with a name for the service account.

      gcloud iam service-accounts create NAME
      
    2. Grant permissions to the service account. Replace PROJECT_ID with your project ID and ROLE with the appropriate Container Registry role for the service account. This role applies across repositories in the project. You can change the role later and you can also set different permissions for the service account on specific repositories.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
      
    3. Generate the key file. The instructions on this page use the file name keyfile.json for the key file.

      gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com
      
  2. If the service account is for pushing or pulling images from a Compute Engine VM instance, configure the access scopes for the required level of access.

  3. Run the following command to log in to Cloud SDK as a service account. In this command, keyfile.json is the key file that you created for the service account.

    gcloud auth activate-service-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com --key-file=keyfile.json
    
  4. Obtain an access token for the service account. Since the token is short-lived, request it less than an hour before you use it to connect with Container Registry.

    Linux / macOS

    • Username is oauth2accesstoken
    • Password is your access token. For example, gcloud auth print-access-token

    For example:

    gcloud auth print-access-token | docker login -u oauth2accesstoken --password-stdin https://[HOSTNAME]
    

    where [HOSTNAME] is gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.

    Or, for older Docker clients which don't support --password-stdin:

    docker login -u oauth2accesstoken -p "$(gcloud auth print-access-token)" https://[HOSTNAME]
    

    Windows

    • Username is oauth2accesstoken
    • Password is the output of gcloud auth print-access-token
    1. Get the access token
    gcloud auth print-access-token
    

    The returned string is the access token that you use as your password. In this example, ya29.8QEQIfY_... represents the returned access token.

    ya29.8QEQIfY_...
    
    1. Log in with the access token
    docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." https://[HOSTNAME]
    

    where [HOSTNAME] is gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.

JSON key file

A service account key is a long-lived key-pair that you can use as a credential for a service account. You are responsible for security of the private key and other key management operations, such as key rotation.

Anyone who has access to a valid private key for a service account will be able to access resources through the service account. For example, some service accounts automatically created by Google Cloud, such as the Container Registry service account, are granted the read-write Editor role for the parent project. The Compute Engine default service account is configured with read-only access to storage within the same project.

In addition, the lifecycle of the key's access to the service account (and thus, the data the service account has access to) is independent of the lifecycle of the user who has downloaded the key.

Use the following guidelines to limit access to your container images:

  • Create dedicated service accounts that are only used to interact with Container Registry.
  • Grant the specific role for the least amount of access that the service account requires.
  • Follow best practices for managing credentials.

To create a new service account and a service account key for use with Container Registry repositories only:

  1. Create the service account for interacting with repositories:

    Console

    1. In Google Cloud Console, open the Service account keys page.

    Go to the Create Service Account Key page

    1. From the Service account list, select New service account.

    2. In the Service account name field, enter a name.

    3. From the Role list, select the appropriate Container Registry role for the service account.

    4. Click Create. A JSON file that contains your key downloads to your computer.

      The instructions on this page use the file name keyfile.json for this key file.

    gcloud

    You can run the following commands using Cloud SDK on your local machine, or in Cloud Shell.

    1. Create the service account. Replace NAME with a name for the service account.

      gcloud iam service-accounts create NAME
      
    2. Grant permissions to the service account. Replace PROJECT_ID with your project ID and ROLE with the appropriate role for the service account.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
      
    3. Generate the key file. In this example, the output key file name is keyfile.json

      gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com
      
  2. Use the service account key as your password to authenticate with Docker.

    Linux / macOS

    • Username is _json_key (NOT the name of your service account)
    • keyfile.json is the service account key you created

    For example:

    cat keyfile.json | docker login -u _json_key --password-stdin https:[HOSTNAME]
    

    where [HOSTNAME] is gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.

    Or, for older Docker clients which don't support --password-stdin:

    docker login -u _json_key -p "$(cat keyfile.json)" https:[HOSTNAME]
    

    where [HOSTNAME] is gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.

    Windows

    • Username is _json_key (NOT the name of your service account).
    • keyfile.json contains the service account JSON key.

    For example:

    docker login -u _json_key --password-stdin https://[HOSTNAME] < keyfile.json
    

    where [HOSTNAME] is gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.

    Or, for older Docker clients which don't support --password-stdin:

    set /p PASS=<keyfile.json
    docker login -u _json_key -p "%PASS%" https:[HOSTNAME]
    

    where [HOSTNAME] is gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.

  3. If the service account is for pushing or pulling images from a Compute Engine VM instance, configure the access scopes for the required level of access.

Using Container Registry with Google Cloud

Compute Engine instances and Google Kubernetes Engine clusters can push and pull Container Registry images based on Cloud Storage scopes on the instances. Refer to Using Container Registry with Google Cloud.

Images stored in Container Registry can be deployed to the App Engine flexible environment.