Pull images from a connected registry

2025-05-21

To pull images from a connected registry, configure a client token and pass the token credentials to access registry content.

Prerequisites

Use the Bash environment in Azure Cloud Shell. For more information, see Get started with Azure Cloud Shell.
If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.
- If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Authenticate to Azure using Azure CLI.
- When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use and manage extensions with the Azure CLI.
- Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

Connected registry resource in Azure. For deployment steps, see Quickstart: Create a connected registry using the Azure CLI. In the commands in this article, the connected registry name is stored in the environment variable $CONNECTED_REGISTRY_RW.

Create a scope map

Use the az acr scope-map create command to create a scope map for read access to the hello-world repository:

# Use the REGISTRY_NAME variable in the following Azure CLI commands to identify the registry
REGISTRY_NAME=<container-registry-name>

az acr scope-map create \
  --name hello-world-scopemap \
  --registry $REGISTRY_NAME \
  --repository hello-world content/read \
  --description "Scope map for the connected registry."

Create a client token

Use the az acr token create command to create a client token and associate it with the newly created scope map:

az acr token create \
  --name myconnectedregistry-client-token \
  --registry $REGISTRY_NAME \
  --scope-map hello-world-scopemap

This command returns details about the newly generated token, including passwords.

Important

Make sure that you save the generated passwords. These passwords are one-time passwords and can't be retrieved. You can generate new passwords using the az acr token credential generate command.

Update the connected registry with the client token

Use the az acr connected-registry update command to update the connected registry with the newly created client token.

az acr connected-registry update \
  --name $CONNECTED_REGISTRY_RW \
  --registry $REGISTRY_NAME \
  --add-client-token myconnectedregistry-client-token

Pull an image from the connected registry

From a machine with access to connected registry on-premises device, use the following example command to sign into the connected registry, using the client token credentials. For best practices to manage login credentials, see the docker login command reference.

Caution

If you set up your connected registry as an insecure registry, update the insecure registries list in the Docker daemon configuration to include the IP address or FQDN (Fully Qualified Domain Name) and port of your connected registry on your device. This configuration should only be used for testing purposes. For more information, see Test an insecure registry.

docker login --username myconnectedregistry-client-token \
  --password <token_password> <IP_address_or_FQDN_of_connected_registry>:<port>

Then, use the following command to pull the hello-world image:

docker pull <IP_address_or_FQDN_of_connected_registry>:<port>/hello-world

Next steps

Learn more about non-Microsoft Entra repository-scoped tokens.
Learn more about accessing a connected registry.

Share via