Authentication methods

This page describes how to configure a third-party client to authenticate with Container Registry.

Google Cloud services that integrate with Container Registry are preconfigured with permissions to access repositories in the same project. You do not need to configure authentication for these services, but you should verify that permissions are appropriately configured.

Before you begin

1. The account that you will use for authentication must have permissions to access the registry. We recommend using a service account rather than a user account. Service accounts are not associated with a specific user, and Google Cloud applications can use the Application Default Credentials strategy to obtain credentials automatically.

2. Install the latest version of Cloud SDK. To update an existing installation, run the command gcloud components update.

3. Docker requires credential helpers to be in the system PATH. Ensure that the gcloud command is in the system PATH.

4. Install Docker if it is not already installed.

5. Docker requires privileged access to interact with registries. If Docker is installed on Linux or Windows, add the user that you use to run Docker commands to the Docker security group.

   On MacOS, Docker runs from a virtual machine with the root user, so this step is not required. For details about Docker on MacOS, see the Docker documentation.

   Linux

   The Docker security group is called docker. To add your username, run the following command:

   sudo usermod -a -G docker ${USER}
   

   Windows

   The Docker security group is called docker-users. To add a user from the Administrator command prompt, run the following command:

   net localgroup docker-users DOMAIN\USERNAME /add
   

   Where

   • DOMAIN is your Windows domain.
   • USERNAME is your user name.

   Log out and log back in for group membership changes to take effect. If you are using a virtual machine, you may need to restart the virtual machine for membership changes to take effect.

   Note: The Docker security group has access equivalent to the root or Administrator user. Only add trusted users who require access to Docker. For details about security impacts, see Docker daemon security.

Authentication methods

You must configure any third-party clients that need to access Container Registry.

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 an access token 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.

Credential helpers

Docker credential helpers configure Docker for authentication with a specific registry. Container Registry provides:

• A gcloud credential helper
• A standalone credential helper for systems where Cloud SDK is not available

Warning: You should use a Docker credential helper only for versions 18.03 or above. A bug in earlier versions of the Docker client slows down docker build dramatically when credential helpers are configured.

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.

Use gcloud to configure authentication in Cloud Shell or any environment where the Cloud SDK is installed. Cloud Shell includes a current version of Docker.

To configure authentication:

1. Log in to gcloud as the user that will run Docker commands.

   • To configure authentication with user credentials, run the following command:

     gcloud auth login
     

   • To configure authentication with service account credentials, run the following command:

     gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
     

     Where

     • ACCOUNT is the service account name in the format [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com. You can view existing service accounts on the Service Accounts page of Cloud Console or with the command gcloud iam service-accounts list
     • KEY-FILE is the service account key file. See the Identity and Access Management (IAM) documentation for information about creating a key.

2. Configure Docker with the following command:

   gcloud auth configure-docker
   

   Your credentials are saved in your user home directory.

   • Linux: $HOME/.docker/config.json
   • Windows: %USERPROFILE%/.docker/config.json

Docker is now configured to authenticate with Container Registry. To push and pull images, make sure that permissions are correctly configured.

Note: If you normally run Docker commands on Linux with sudo, Docker looks for Container Registry credentials in /root/.docker/config.json instead of $HOME/.docker/config.json. If you want to use sudo with docker commands instead of using the Docker security group, configure credentials with sudo gcloud auth configure-docker instead.

Standalone Docker credential helper

The standalone Docker credential helper configures Docker to authenticate to Container Registry on a system where Cloud SDK is not available.

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 configure authentication:

1. Log on to the machine as the user who will run Docker commands.

2. 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/local/bin/docker-credential-gcr && chmod +x /usr/local/bin/docker-credential-gcr
   

3. Configure Docker with the following command:

   docker-credential-gcr configure-docker
   

   Your credentials are saved in your user home directory.

   • Linux: $HOME/.docker/config.json
   • Windows: %USERPROFILE%/.docker/config.json

See the standalone Docker credential helper documentation on GitHub for more information.

Note: If you normally run Docker commands on Linux with sudo, Docker looks for Container Registry credentials in /root/.docker/config.json instead of $HOME/.docker/config.json. If you want to use sudo with docker commands instead of using the Docker security group, configure credentials with sudo docker-credential-gcr configure-docker instead.

Docker is now configured to authenticate with Container Registry. To push and pull images, make sure that permissions are correctly configured.

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.

Google Cloud obtains an access token using Application Default Credentials.

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

   Console

   1. In Google Cloud Console, open the Create service account key page.

      Go to the Create Service Account Key page

   2. 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.

   3. Select JSON as the key type.

   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 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. Run the following command to log in to Cloud SDK as a service account.

   gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
   

   Where

   • ACCOUNT is the service account name in the format [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com.
   • KEY-FILE is the service account key file. See the IAM documentation for information about creating a key.

3. Verify that permissions are correctly configured for the service account. If you are using the Compute Engine service account, you must correctly configure both permissions and access scopes.

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.

   Note: Google Cloud services that provide images at a gcr.io subdomain might require authentication. For example, you must authenticate to marketplace.gcr.io to pull images from Google Cloud Marketplace.

Docker is now authenticated with Container Registry.

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 Create service account key page.

      Go to the Create Service Account Key page

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

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

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

   5. 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. Verify that permissions are correctly configured for the service account. If you are using the Compute Engine service account, you must correctly configure both permissions and access scopes.

3. 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.

   Note: Google Cloud services that provide images at a gcr.io subdomain might require authentication. For example, you must authenticate to marketplace.gcr.io to pull images from Google Cloud Marketplace.

Docker is now authenticated with Container Registry.