Configure authentication to Artifact Registry for Docker

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

You don't need to configure authentication for Cloud Build or Google Cloud runtime environments such as Google Kubernetes Engine and Cloud Run, but you should verify that the required permissions are configured.

Before you begin

  1. Install the Google Cloud CLI, then initialize it by running the following command:

    gcloud init
  2. (Optional) Configure defaults for gcloud CLI commands.
  3. Verify that the account you are using for authentication has permissions to access Artifact Registry. We recommend using a service 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 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 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.

Choosing an authentication method

The following authentication methods are available:

gcloud CLI credential helper
Configure your Artifact Registry credentials for use with Docker directly in gcloud CLI. This is the simplest authentication method, but can be slower than the standalone credential helper.
Standalone Docker credential helper
This option is primarily for configuring your credentials for use with Docker in the absence of Google Cloud CLI. It is significantly faster than the gcloud CLI credential helper and uses Application Default Credentials (ADC) to automatically find credentials in your environment.
Access token
You can generate a short-lived access token for a service account and then use the token for password authentication. Since the token only valid for 60 minutes, 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 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 a credential helper to reduce the risk of unauthorized access to your container images. If you must use a service account key, ensure that you follow best practices for managing credentials.

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 Artifact Registry stores the credential helper settings in the credHelpers section of the file.
auths
If you use Docker to sign in with a token or service account key as your password, Docker stores a base64-encoded version of 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 Artifact Registry settings in both the credHelpers and auths sections, the settings in the auths section are ignored.

gcloud CLI credential helper

The gcloud CLI credential helper provides secure, short-lived access to your project resources. It configures Docker to authenticate to Artifact Registry hosts in any environment where the Google Cloud CLI is installed. Cloud Shell includes 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 account in your gcloud CLI session. Since this credential helper depends on gcloud CLI, it can be significantly slower than the standalone credential helper. For automated builds with third-party tools or Docker clients with a large number of configured registry hosts, 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 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 that you want to use with Artifact Registry in the format USERNAME@PROJECT-ID.iam.gserviceaccount.com. If you want to use an existing account, you can view a list of 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.
  2. Run the following command:

    gcloud auth configure-docker HOSTNAME-LIST
    

    Where HOSTNAME-LIST is a comma-separated list of repository hostnames to add to the credential helper configuration.

    For example, to add the regions us-central1 and asia-northeast1, run the command:

    gcloud auth configure-docker us-central1-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 the command again.

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

    gcloud artifacts locations list
    
  3. The command displays the credHelpers section of your current Docker configuration and the updated configuration after adding the specified hostnames.

    To accept the configuration changes, enter y.

    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 system PATH. Ensure that the gcloud command is in the system PATH.

Standalone credential helper

The standalone Docker credential helper configures Docker to authenticate to Artifact Registry on a system where the gcloud CLI is not available. It is significantly faster than the gcloud CLI credential helper and uses Application Default Credentials (ADC) to automatically find credentials in the your environment. For operations other than pushing and pulling images, such as tagging or listing images. We recommend using this authentication method for automated builds with third-party tools or Docker clients with a large number of configured registry hosts.

The standalone Docker credential helper fetches your Artifact Registry credentials and writes them to the Docker configuration file. This way, you can use the Docker command-line tool, docker, to interact directly with Artifact 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 from GitHub.

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

    VERSION=2.1.22
    OS=linux  # or "darwin" for OSX, "windows" for Windows.
    ARCH=amd64  # or "386" for 32-bit OSs
    
    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 to use your Artifact Registry credentials when interacting with Artifact Registry (you are only required to do this once):

    docker-credential-gcr configure-docker --registries=HOSTNAME-LIST
    

    Where HOSTNAME-LIST is a comma-separated list of repository hostnames to add to the credential helper configuration.

    For example, to add the regions us-central1 and asia-northeast1, run the command:

    docker-credential-gcr configure-docker --registries=us-central1-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 the command again.

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

    gcloud artifacts locations list
    

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

    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 system PATH. Ensure that the docker-credential-gcr command is in the system PATH.

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

    echo "https://HOSTNAME" | docker-credential-gcr get
    

    Replace HOSTNAME with a hostname that you added to the configuration. For example:

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

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

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

Docker is now configured to authenticate with Artifact 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 Artifact Registry. Since the token is valid for 60 minutes, you should request it less than an hour before you use it to connect with Artifact 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.

    You will need the location of the service account key file to set up authentication 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

  2. Grant the specific Artifact Registry role to the service account to provide repository access.

  3. Generate an access token for the service account and authenticate using one of the following options:

    • If you have permissions in the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator), you can impersonate a service account, to obtain a token for it, and then authenticate as the service account.

      Run the following command, replacing ACCOUNT with your service account email address and LOCATION regional or multi-regional location of the repository.

      Linux

      gcloud auth print-access-token \
          --impersonate-service-account ACCOUNT | docker login \
          -u oauth2accesstoken \
          --password-stdin https://LOCATION-docker.pkg.dev
      

      Windows

      gcloud auth print-access-token --impersonate-service-account ACCOUNT |
          docker login -u oauth2accesstoken --password-stdin https://LOCATION-docker.pkg.dev
      
    • Activate a service account in your gcloud CLI session and then obtain an access token.

      1. Activate the service account that you want to use. Replace ACCOUNT with your service account email address and KEY-FILE with the filename for your service account key.

        gcloud auth activate-service-account ACCOUNT \
            --key-file=KEY-FILE
        
      2. Generate a token and authenticate.

        Run the following command, replacing LOCATION with the regional or multi-regional location of the repository.

        Linux

        gcloud auth print-access-token | docker login -u oauth2accesstoken \
            --password-stdin https://LOCATION-docker.pkg.dev
        

        Windows

        gcloud auth print-access-token |
            docker login -u oauth2accesstoken --password-stdin https://LOCATION-docker.pkg.dev
        

Docker is now authenticated with Artifact Registry.

Service account key

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. 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. Note that 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 repositories:

  • Create dedicated service accounts that are only used to interact with repositories.
  • Grant the specific Artifact Registry role for the access required by the service account. For example, a service account that only downloads artifacts only requires the Artifact Registry Reader role.
  • Configure the permissions for your dedicated service accounts on each repository rather than at the project level. You can then specify access based on the repository context. For example, a service account for development builds might have the Artifact Registry Reader role for a production repository and the Artifact Registry Writer role for a staging repository.
  • Follow best practices for managing credentials.

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

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

    You will need the location of the service account key file to set up authentication 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

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

    Linux

    base64 FILE-NAME > NEW-FILE-NAME
    

    macOS

    base64 -i FILE-NAME -o NEW-FILE-NAME
    

    Windows

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

    Where FILE-NAME is the original key filename and NEW-FILE-NAME is your base64-encoded key file.

  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 to configure integration with Docker:

    Run the following command:

    Linux / macOS

    cat KEY-FILE | docker login -u KEY-TYPE --password-stdin \
    https://LOCATION-docker.pkg.dev
    

    Windows

    Get-Content KEY-FILE |
    docker login -u KEY-TYPE --password-stdin https://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-regional location of the repository where the image is stored.

Docker is now authenticated with Artifact Registry.