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
- Verify that you have enabled the Container Registry API and installed gcloud CLI. See Enabling and disabling service for instructions.
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.
Install Docker if it is not already installed. Docker is included in Cloud Shell.
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.
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.
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:
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 commandgcloud 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.
- ACCOUNT is the service account name in the format
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
- Linux:
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:
Log on to the machine as the user who will run Docker commands.
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/
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
- Linux:
See the standalone Docker credential helper documentation on GitHub for more information.
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.
Create a new service account that will interact with Container Registry.
Console
In the Google Cloud console, go to the Create service account page.
Select the project that you want to use.
In the Service account name field, enter a name.
Optional: In the Service account description field, enter a description.
Click Create.
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.
Click Done.
gcloud
You can run the following commands using Google Cloud CLI on your local machine, or in Cloud Shell.
Create the service account. Replace NAME with a name for the service account.
gcloud iam service-accounts create NAME
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"
Obtain a key for the service account that will interact with Container Registry.
Console
In the Google Cloud console, go to the Service Accounts page.
Click the email address of the service account that you want to use.
Click Keys.
Click Add key, then Create new key.
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.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
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.
- ACCOUNT is the service account name in the format
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.
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
, orasia.gcr.io
.
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.
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:
Create a new service account that will interact with Container Registry.
Console
In the Google Cloud console, go to the Create service account page.
Select the project that you want to use.
In the Service account name field, enter a name.
Optional: In the Service account description field, enter a description.
Click Create.
Click the Select a role field. Under All roles, select an appropriate Cloud Storage role for the service account.
Click Done.
gcloud
You can run the following commands using Google Cloud CLI on your local machine, or in Cloud Shell.
Create the service account. Replace NAME with a name for the service account.
gcloud iam service-accounts create NAME
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"
Obtain a key for the service account that will interact with Container Registry.
Console
In the Google Cloud console, go to the Service Accounts page.
Click the email address of the service account that you want to use.
Click Keys.
Click Add key, then Create new key.
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.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
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.
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
, orasia.gcr.io
.
Docker is now authenticated with Container Registry.