Setting up authentication for Docker

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

Before you begin

  1. If the target repository does not exist, create a new repository.
  2. (Optional) Configure defaults for gcloud commands.
  3. Install Docker if it is not already installed. Docker is included in Cloud Shell.
  4. 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.

Choosing an authentication method

In most situations, we recommend using a service account for authenticating to Artifact Registry.

Service accounts are not associated with a specific user, and Google Cloud applications can use an Application Default Credentials strategy to obtain credentials automatically.

The service accounts for applications that typically integrate with Artifact Registry, such as Cloud Build or Cloud Run, are configured by default with permissions to access repositories in the same project. You do not need to configure Docker authentication for these applications.

The following authentication methods are available:

gcloud as credential helper (Recommended)
Configure your Artifact 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.

You should only use one of the alternative authentication options when using gcloud as the credential helper is not ideal, and when you understand the security implications of using the other options.

In addition, consider the permissions granted to the user account or service account that you use to connect to Artifact Registry. For example, the Compute Engine default service account has the Editor basic role for the parent project. Instead of using a default service account to interact with repositories, consider creating a service account with the specific permissions that are required for use with your repositories.

Credential helpers

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

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

gcloud as a credential helper (Recommended)

We strongly recommend that you use this authentication 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 authenticate to Artifact Registry:

  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. 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 repository locations are added to the credential helper configuration. You can add other locations 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. Docker requires credential helpers to be in the system PATH. Ensure that the gcloud command is in the system PATH.

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

Standalone credential helper

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

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.0.0
    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 --to-stdout ./docker-credential-gcr \
    > /usr/bin/docker-credential-gcr && chmod +x /usr/bin/docker-credential-gcr
    
  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 repository locations are added to the credential helper configuration. You can add other locations 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.

  4. Docker requires credential helpers to be in the system PATH. Ensure that the docker-credential-gcr command is in the system PATH.

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

Access token

Access tokens are short-lived tokens that provide access to your Google Cloud resources. Since the token is short-lived, you should request it less than an hour before you use it to connect with Artifact Registry repositories.

Google Cloud obtains an access token using Application Default Credentials.

To use an access token:

  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. 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. Obtain an access token as credentials when you authenticate to Artifact Registry with Docker.

    Linux / macOS

    Run the following command:

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

    Or, for older Docker clients which don't support --password-stdin:

    docker login -u oauth2accesstoken -p "$(gcloud auth print-access-token)" \
    https://LOCATION-docker.pkg.dev
    

    Where

    • oauth2accesstoken is the user name to use when authenticating with an access token.
    • gcloud auth print-access-token is the gcloud command to obtain the access token. Your access token is the password for authentication.
    • LOCATION is the regional or multi-regional location of the repository where the image is stored.

    Windows

    Run the following command:

    gcloud auth print-access-token
    ya29.8QEQIfY_...
    
    docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
    https://LOCATION-docker.pkg.dev/<var>PROJECT-ID</var>/<var>REPOSITORY</var>
    

    Where

    • oauth2accesstoken is the user name to use when authenticating with an access token.
    • gcloud auth print-access-token is the gcloud command to obtain the access token. Your access token is the password for authentication.
    • LOCATION is the regional or multi-regional location of the repository where the image is stored.

Docker is now authenticated with Artifact 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. 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 &gt; NEW-FILE-NAME
    

    macOS

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

    Windows

    Base64.exe -e FILE-NAME &gt; NEW-FILE-NAME
    

    Where FILE-NAME is the original key file name 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:

    Linux / macOS

    Run the following command:

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

    Or, for older Docker clients which don't support --password-stdin:

    docker login -u KEY-TYPE -p "$(cat FILE-NAME.json)" \
    https://LOCATION-docker.pkg.dev
    

    Where

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

    Windows

    Run the following command:

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

    Or, for older Docker clients which don't support --password-stdin:

    set /p PASS=<KEY-FILE
    docker login -u KEY-TYPE -p "%PASS%" https://LOCATION-docker.pkg.dev
    

    Where

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