This page describes how to configure Docker to authenticate to Artifact RegistryDocker repositories.

You don't need to configure authentication for Cloud Build or Google Cloudruntime environments such as Google Kubernetes Engine and Cloud Run, but you shouldverify that the requiredpermissionsare configured.

Before you begin

1. Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:

   gcloudinit

   If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

2. (Optional)Configure defaults for gcloud CLI commands.
3. Verify that the account you are using for authentication haspermission to access Artifact Registry. We recommend using aservice account rather than a user account.
4. Install Docker if it is not already installed. Docker is included in Cloud Shell.
5. 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 sinceDocker Desktop runs on a virtual machine as the root user.

   Linux

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

         sudo usermod -a -G docker ${USER}

   Windows

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

           net localgroup docker-usersDOMAIN\USERNAME /add

   Where:

   • DOMAIN is your Windows domain.
   • USERNAME is your username.

   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 that is equivalent to the root or Administrator user. Only add trusted users who require access to Docker. For details about security impacts, seeDocker daemon security.

Choosing an authentication method

The following authentication methods are available:

gcloud CLI credential helper

Configure your Artifact Registry credentials for use withDocker directly in gcloud CLI. This is the simplest authentication method, butcan be slower than the standalone credential helper.

Standalone Docker credential helper

This option is primarily for configuring your credentials for use with Dockerin the absence of Google Cloud CLI. It is significantly faster than the gcloud CLIcredential helper and usesApplication Default Credentials (ADC) to automatically findcredentials in your environment.

Access token

You can generate a short-lived access token for a service account and thenuse the token for password authentication. Since the token only valid for 60minutes, it is a safer option than a service account key.

Service account key

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

When possible, use anaccess tokenor a credential helper to reduce the risk of unauthorized access to yourcontainer images. If you must use a service account key, ensure thatyou followbest practices for managing credentials.

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

Authentication settings in the Docker configuration file

Docker saves authentication settings in the configuration fileconfig.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 authenticationArtifact Registry stores the credential helper settings in thecredHelpers section of the file.

auths

If you use Docker to sign in with a token or service account key as yourpassword, Docker stores a base64-encoded version of your credentials in theauths section of the file.

credStore

If you configured acredential store to manage your credentials, the settings for the credential store are inthecredStore section of the file.

When Docker connects to a registry, it checks first for a credential helperthat is associated with the host. So if yourconfig.json includesArtifact Registry settings in both thecredHelpers andauths sections,the settings in theauths section are ignored.

gcloud CLI credential helper

The gcloud CLI credential helper provides secure, short-lived access to yourproject resources. It configures Docker to authenticate toArtifact Registry hosts in any environment where theGoogle Cloud CLI is installed.Cloud Shellincludes the Google Cloud CLI and a current version of Docker.

The gcloud CLI credential helper is the simplest authentication method to set up.It configures Docker with the credentials of the active user or service accountin your gcloud CLI session. Since this credential helper depends ongcloud CLI, it can be significantly slower than thestandalone credential helper. For automated builds withthird-party tools or Docker clients with a large number of configured registryhosts, use the standalone credential helper instead.

To authenticate to Artifact Registry:

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

   • To configure authentication with user credentials, run the followingcommand:

     gcloudauthlogin

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

     gcloudauthactivate-service-accountACCOUNT--key-file=KEY-FILE

     Where

     • ACCOUNT is the service account that you want to use withArtifact Registry in the formatUSERNAME@PROJECT-ID.iam.gserviceaccount.com.If you want to use an existing account, you can view a list of serviceaccounts on theService Accountspage of Google Cloud console or with the commandgcloud iam service-accounts list
     • KEY-FILE is the service account key file. See theIdentity and Access Management (IAM) documentationfor 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 keyswhenever possible. If you must authenticate with a service account key, you are responsible for thesecurity 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 mightbe disabled for your organization. For more information, see Managing secure-by-default organization resources.

     If you acquired the service account key from an external source, you must validate it before use.For more information, see Security requirements for externally sourced credentials.

1. Run the following command:

   gcloudauthconfigure-dockerHOSTNAME-LIST

   WhereHOSTNAME-LIST is a comma-separated list of repositoryhostnames to add to the credential helper configuration.

   For example, to add the regionsus-west1 andasia-northeast1, runthe command:

   gcloud auth configure-docker us-west1-docker.pkg.dev,asia-northeast1-docker.pkg.dev

   The specified hostnames are added to the credential helper configuration.You can add other hostnames to the configuration later by running thecommand again.

   To view a list of supported repository locations, run the command:

   gcloudartifactslocationslist

2. The command displays thecredHelpers section of your current Dockerconfiguration and the updated configuration after adding the specifiedhostnames.

   To accept the configuration changes, entery.

   Your credentials are saved in your user home directory.

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

3. Docker requires credential helpers to be in the systemPATH. Ensure thatthegcloud command is in the systemPATH.

Note: If you normally run Docker commands on Linux withsudo, Docker looksfor Artifact Registry credentials in/root/.docker/config.json insteadof$HOME/.docker/config.json. If you want to usesudo withdockercommands instead of using the Docker security group, configure credentials withsudo gcloud auth configure-docker instead.

Standalone credential helper

The standalone Docker credential helper configures Docker to authenticateto Artifact Registry on a system where the gcloud CLI is not available.It is significantly faster than thegcloud CLI credential helperand usesApplication Default Credentials (ADC) to automatically findcredentials in the your environment. For operations other than pushing andpulling images, such as tagging or listing images. We recommend using thisauthentication method for automated builds with third-party tools or Dockerclients with a large number of configured registry hosts.

The standalone Docker credential helper fetches your Artifact Registrycredentials and writes them to the Docker configuration file. This way, youcan use the Docker command-line tool,docker, to interact directly withArtifact Registry.

To use the Docker credential helper:

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

2. Download the standalone Docker credential helper fromGitHub.

   You can optionally use thecurl command-line utility. For example:

   VERSION=2.1.29OS=linux# or "darwin" for OSX, "windows" for Windows.ARCH=amd64# or "386" for 32-bit OSscurl-fsSL"https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz"\|tarxzdocker-credential-gcr\&&chmod+xdocker-credential-gcr &&sudomvdocker-credential-gcr/usr/bin/

3. Configure Docker to use your Artifact Registry credentials wheninteracting with Artifact Registry (you are only required to do thisonce):

   docker-credential-gcrconfigure-docker--registries=HOSTNAME-LIST

   WhereHOSTNAME-LIST is a comma-separated list of repositoryhostnames to add to the credential helper configuration.

   For example, to add the regionsus-west1 andasia-northeast1, runthe command:

   docker-credential-gcr configure-docker --registries=us-west1-docker.pkg.dev,asia-northeast1-docker.pkg.dev

   The specified hostnames are added to the credential helper configuration.You can add other hostnames to the configuration later by running thecommand again.

   To view a list of supported repository locations, run the command:

   gcloudartifactslocationslist

   See thestandalone Docker credential helper documentation on GitHub for more information.

   Note: If you normally run Docker commands on Linux withsudo, Docker looksfor Artifact Registry credentials in/root/.docker/config.json insteadof$HOME/.docker/config.json. If you want to usesudo withdockercommands instead of using the Docker security group, configure credentials withsudo docker-credential-gcr configure-docker instead.

   Your credentials are saved in your user home directory.

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

4. Docker requires credential helpers to be in the systemPATH. Ensure thatthedocker-credential-gcr command is in the systemPATH.

5. To verify that the credential helper can successfully retrieve yourcredentials, run the following command:

   echo"https://HOSTNAME"|docker-credential-gcrget

   ReplaceHOSTNAME with a hostname that you added to theconfiguration. For example:

   echo "https://us-west1-docker.pkg.dev" | docker-credential-gcr get

   If the command is successful, the returned JSON output includes a token intheSecret field. For example:

   {"ServerURL":"https://us-west1-docker.pkg.dev","Username":"_dcgcr_2_0_0_token","Secret":"ya29..."}

Docker is now configured to authenticate with Artifact Registry. To pushand pull images, make sure thatpermissionsare correctly configured.

Access token

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

To use an access token with service account credentials:

1. Create a service account to act on behalf of your application,or choose an existing service account that you use for automation.

2. Grant the specificArtifact Registry roleto the service account to provide repository access.

3. Generate an access token for the service account and authenticate:

   You must have the permissions in the Service Account Token Creator role(roles/iam.serviceAccountTokenCreator) toimpersonate a service account,to obtain a token for it, and then authenticate as the service account.

   Run the following command, replacingACCOUNT with yourservice account email address andLOCATION with theregional or multi-regionallocation ofthe repository.

   Linux

   gcloudauthprint-access-token\--impersonate-service-accountACCOUNT|dockerlogin\-uoauth2accesstoken\--password-stdinhttps://LOCATION-docker.pkg.dev

   Windows

   gcloudauthprint-access-token--impersonate-service-accountACCOUNT|dockerlogin-uoauth2accesstoken--password-stdinhttps://LOCATION-docker.pkg.dev

Docker is now authenticated with Artifact Registry.

Service account key

Note: When possible, use anaccess token or credential helper toreduce 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 keyswhenever possible. If you must authenticate with a service account key, you are responsible for thesecurity 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 mightbe disabled for your organization. For more information, see Managing secure-by-default organization resources.

If you acquired the service account key from an external source, you must validate it before use.For more information, see Security requirements for externally sourced credentials.

Anyone who has access to a valid private key for a service account will be ableto access resources through the service account. Note that the lifecycle of thekey's access to the service account (and thus, the data the service account hasaccess to) is independent of the lifecycle of the user who has downloaded thekey.

Use the following guidelines to limit access to your repositories:

• Create dedicated service accounts that are only used to interact withrepositories.
• Grant the specificArtifact Registry rolefor the access required by the service account. For example, a service accountthat only downloads artifacts only requires the Artifact Registry Readerrole.
• Configure the permissions for your dedicated service accounts on eachrepository rather than at the project level. You can then specify accessbased on the repository context. For example, a service accountfor development builds might have the Artifact Registry Reader role fora production repository and the Artifact Registry Writer role for astaging repository.
• Followbest practices for managing credentials.

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

1. Create a serviceaccount to act on behalf of your application, or choose an existing serviceaccount that you use for automation.

   You will need the location of the service account key file to set upauthentication with Artifact Registry. For existing accounts,you can view keys and create new keys on the Service Accounts page.

   Go to the Service Accounts page

   Note: Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keyswhenever possible. If you must authenticate with a service account key, you are responsible for thesecurity 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 mightbe disabled for your organization. For more information, see Managing secure-by-default organization resources.

   If you acquired the service account key from an external source, you must validate it before use.For more information, see Security requirements for externally sourced credentials.

2. You can optionally base64-encode all the contents of the key file.

   Linux

   base64FILE-NAME >NEW-FILE-NAME

   macOS

   base64-iFILE-NAME-oNEW-FILE-NAME

   Windows

   Base64.exe-eFILE-NAME >NEW-FILE-NAME

   WhereFILE-NAME is the original key filename andNEW-FILE-NAME is your base64-encoded key file.

3. Verify thatpermissions are correctlyconfigured for the service account. If you are using the Compute Engineservice account, you must correctly configure both permissions andaccess scopes.

4. Use the service account key to configure integration with Docker:

   Run the following command:

   Linux / macOS

   catKEY-FILE|dockerlogin-uKEY-TYPE--password-stdin\https://LOCATION-docker.pkg.dev

   Windows

   Get-ContentKEY-FILE|dockerlogin-uKEY-TYPE--password-stdinhttps://LOCATION-docker.pkg.dev

   Replace the following:

   • KEY-TYPE is one of the following:
     • _json_key if you are using the service account key in JSON format as it was provided when you created the file.
     • _json_key_base64 if you base64-encoded the all contents of the file.
   • KEY-FILE is the name of the service account key file in JSON format.
   • LOCATION is the regional or multi-regionallocation of the repository where the image is stored.

Docker is now authenticated with Artifact Registry.