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. Verify that you have enabled the Container Registry API and installed gcloud CLI. See Enabling and disabling service for instructions.

2. Verify that the account you are using for authentication has permissions to access Container Registry. We recommend using a service account rather than a user account.

3. Install Docker if it is not already installed. Docker is included in Cloud Shell.

4. Docker requires privileged access to interact with registries. On Linux or Windows, add the user that you use to run Docker commands to the Docker security group. This step is not required on MacOS since Docker Desktop runs on a virtual machine as the root user.

   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 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 credential helper

This option is primarily for configuring your credentials for use with Docker in the absence of Google Cloud CLI. 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. Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keys whenever possible. If you must authenticate with a service account key, you are responsible for the security of the private key and for other operations described by Best practices for managing service account keys. If you are prevented from creating a service account key, service account key creation might be disabled for your organization. For more information, see Managing secure-by-default organization resources.

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

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.

Authentication settings in the Docker configuration file

Docker saves authentication settings in the configuration file config.json.

• Linux: ~/.docker/config.json
• Windows: %USERPROFILE%\.docker\config.json

There are separate sections in the file for different authentication methods:

credHelpers

If you use the Docker credential helper for authentication Container Registry stores the credential helper settings in the credHelpers section of the file.

auths

If you use Docker to log in with a token or service account key as your password, Docker stores your credentials in the auths section of the file.

credStore

If you configured a credential store to manage your credentials, the settings for the credential store are in the credStore section of the file.

When Docker connects to a registry, it checks first for a credential helper that is associated with the host. So if your config.json includes Container Registry settings in both the credHelpers and auths sections, the settings in the auths section are ignored.

gcloud credential helper

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

Use the gcloud CLI to configure authentication in Cloud Shell or any environment where the Google Cloud CLI 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 Google 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.
   Note: Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keys whenever possible. If you must authenticate with a service account key, you are responsible for the security of the private key and for other operations described by Best practices for managing service account keys. If you are prevented from creating a service account key, service account key creation might be disabled for your organization. For more information, see Managing secure-by-default organization resources.

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

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 credential helper

The standalone Docker credential helper configures Docker to authenticate to Container Registry on a system where gcloud CLI 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.1.23
   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 docker-credential-gcr \
   && chmod +x docker-credential-gcr && sudo mv docker-credential-gcr /usr/bin/
   

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

You can generate a short-lived OAuth access token to authenticate with Container Registry. Since the token is valid for 60 minutes, you should request it less than an hour before you use it to connect with Container Registry.

1. Create a new service account that will interact with Container Registry.

   Console

   1. In the Google Cloud console, go to the Create service account page.

      Go to the Create Service Account page

   2. Select the project that you want to use.

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

   4. Optional: In the Service account description field, enter a description.

   5. Click Create.

   6. Click the Select a role field. Under All roles, select an appropriate Cloud Storage role based on the permissions you want to grant to the service account.

   7. Click Done.

   gcloud

   You can run the following commands using Google Cloud CLI 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 a role to the service account. Replace PROJECT_ID with your project ID and ROLE with the appropriate Cloud Storage role for the service account. This role applies across repositories in the project. You can change the role later, and you can also grant different roles to 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"

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

   Note: Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keys whenever possible. If you must authenticate with a service account key, you are responsible for the security of the private key and for other operations described by Best practices for managing service account keys. If you are prevented from creating a service account key, service account key creation might be disabled for your organization. For more information, see Managing secure-by-default organization resources.

   Console

   1. In the Google Cloud console, go to the Service Accounts page.

      Go to the Service Accounts page

   2. Click the email address of the service account that you want to use.

   3. Click Keys.

   4. Click Add key, then Create new key.

   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.

   6. Click Close.

   gcloud

   You can run the following command using Google Cloud CLI on your local machine, or in Cloud Shell.

   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

3. Run the following command to log in to Google Cloud CLI 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.

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

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

   Run the following command:

   Linux

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

   Windows

   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.

   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. Unlike the OAuth access token, a service account key does not expire.

Note: Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keys whenever possible. If you must authenticate with a service account key, you are responsible for the security of the private key and for other operations described by Best practices for managing service account keys. If you are prevented from creating a service account key, service account key creation might be disabled for your organization. For more information, see Managing secure-by-default organization resources.

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 a new service account that will interact with Container Registry.

   Console

   1. In the Google Cloud console, go to the Create service account page.

      Go to the Create Service Account page

   2. Select the project that you want to use.

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

   4. Optional: In the Service account description field, enter a description.

   5. Click Create.

   6. Click the Select a role field. Under All roles, select an appropriate Cloud Storage role for the service account.

   7. Click Done.

   gcloud

   You can run the following commands using Google Cloud CLI 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 a role to the service account. Replace PROJECT_ID with your project ID and ROLE with the appropriate Cloud Storage role for the service account.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"

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

   Console

   1. In the Google Cloud console, go to the Service Accounts page.

      Go to the Service Accounts page

   2. Click the email address of the service account that you want to use.

   3. Click Keys.

   4. Click Add key, then Create new key.

   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.

   6. Click Close.

   gcloud

   You can run the following command using Google Cloud CLI on your local machine, or in Cloud Shell.

   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

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. Use the service account key as your password to authenticate with Docker.

   Linux / macOS

   cat KEY-FILE | docker login -u _json_key --password-stdin \
   https://HOSTNAME
   

   Windows

   Get-Content KEY-FILE |
   docker login -u _json_key --password-stdin https://HOSTNAME
   

   Replace the following:

   • KEY-FILE is the name of the service account key file in JSON format.
   • 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.