Autenticazione al Registro Azure Container con entità servizioAzure Container Registry authentication with service principals

È possibile usare un'entità servizio Azure Active Directory (Azure AD) per fornire l'accesso docker push e pull dell'immagine del contenitore al registro contenitori.You can use an Azure Active Directory (Azure AD) service principal to provide container image docker push and pull access to your container registry. Se si usa un'entità servizio, è possibile fornire l'accesso ai servizi e alle applicazioni "headless".By using a service principal, you can provide access to "headless" services and applications.

Che cos'è un'entità servizio?What is a service principal?

Le entità servizio di Azure AD forniscono accesso alle risorse Azure all'interno della sottoscrizione.Azure AD service principals provide access to Azure resources within your subscription. È possibile considerare un'entità servizio come identità utente per un servizio, dove "servizio" è qualsiasi applicazione, servizio o piattaforma che deve accedere alle risorse.You can think of a service principal as a user identity for a service, where "service" is any application, service, or platform that needs to access the resources. È possibile configurare un'entità servizio con diritti di accesso limitati solo alle risorse specificate.You can configure a service principal with access rights scoped only to those resources you specify. Configurare quindi l'applicazione o il servizio in modo che usi le credenziali dell'entità servizio per accedere a tali risorse.Then, configure your application or service to use the service principal's credentials to access those resources.

Nel contesto del Registro Azure Container è possibile creare un'entità servizio Azure AD con autorizzazioni pull, push e pull o con altre autorizzazioni per il registro Docker privato in Azure.In the context of Azure Container Registry, you can create an Azure AD service principal with pull, push and pull, or other permissions to your private registry in Azure. Per l'elenco completo, vedere Azure Container Registry roles and permissions (Ruoli e autorizzazioni del Registro Azure Container).For a complete list, see Azure Container Registry roles and permissions.

Perché usare un'entità servizio?Why use a service principal?

Usando un'entità servizio Azure AD, è possibile fornire un accesso limitato al registro di sistema del contenitore privato.By using an Azure AD service principal, you can provide scoped access to your private container registry. Creare entità servizio diverse per ogni applicazione o servizio, ciascuna con diritti di accesso personalizzati al registro di sistema.Create different service principals for each of your applications or services, each with tailored access rights to your registry. Poiché è possibile evitare di condividere le credenziali tra servizi e applicazioni, è possibile ruotare le credenziali o revocare l'accesso solamente all'entità servizio (e quindi all'applicazione) scelta.And, because you can avoid sharing credentials between services and applications, you can rotate credentials or revoke access for only the service principal (and thus the application) you choose.

Ad esempio, configurare l'applicazione Web in modo che utilizzi un'entità servizio che la fornisca solo l'accesso con immagine pull, mentre il sistema di compilazione usa un'entità servizio che fornisce l'accesso sia push che pull.For example, configure your web application to use a service principal that provides it with image pull access only, while your build system uses a service principal that provides it with both push and pull access. Se lo sviluppo dell'applicazione cambia mano, è possibile ruotare le credenziali dell'entità servizio senza influire sul sistema di compilazione.If development of your application changes hands, you can rotate its service principal credentials without affecting the build system.

Quando usare un'entità servizioWhen to use a service principal

Usare un'entità servizio per fornire accesso al registro negli scenari headless,You should use a service principal to provide registry access in headless scenarios. ovvero per qualsiasi applicazione, servizio o script che deve eseguire le operazioni di push o pull delle immagini del contenitore in modo automatico.That is, any application, service, or script that must push or pull container images in an automated or otherwise unattended manner. Ad esempio:For example:

  • Pull: distribuire i contenitori da un registro ai sistemi di orchestrazione, tra cui KUBERNETES, DC/OS e Docker Swarm.Pull: Deploy containers from a registry to orchestration systems including Kubernetes, DC/OS, and Docker Swarm. È anche possibile eseguire il pull da registri contenitori a servizi di Azure correlati, ad esempio Azure Kubernetes Service (AKS), istanze di contenitore di Azure, servizio app, batch, Service Fabrice altri.You can also pull from container registries to related Azure services such as Azure Kubernetes Service (AKS), Azure Container Instances, App Service, Batch, Service Fabric, and others.

  • Push: compilare immagini del contenitore ed eseguirne il push in un registro usando soluzioni di distribuzione e integrazione continua come Azure Pipelines o Jenkins.Push: Build container images and push them to a registry using continuous integration and deployment solutions like Azure Pipelines or Jenkins.

Per l'accesso singolo a un registro di sistema, ad esempio quando si esegue il pull manuale di un'immagine del contenitore nella workstation di sviluppo, è consigliabile usare la propria identità di Azure ad invece per l'accesso al registro di sistema, ad esempio con AZ ACR login.For individual access to a registry, such as when you manually pull a container image to your development workstation, we recommend using your own Azure AD identity instead for registry access (for example, with az acr login).

Creare un'entità servizioCreate a service principal

Per creare un'entità servizio con accesso al registro contenitori, eseguire lo script seguente in Azure Cloud Shell o in un'installazione locale dell'interfaccia della riga di comando di Azure.To create a service principal with access to your container registry, run the following script in the Azure Cloud Shell or a local installation of the Azure CLI. Lo script viene formattato per la shell Bash.The script is formatted for the Bash shell.

Prima di eseguire lo script, aggiornare la variabile ACR_NAME con il nome del registro contenitori.Before running the script, update the ACR_NAME variable with the name of your container registry. Il valore SERVICE_PRINCIPAL_NAME deve essere univoco all'interno del tenant di Azure Active Directory.The SERVICE_PRINCIPAL_NAME value must be unique within your Azure Active Directory tenant. Se si riceve un errore "'http://acr-service-principal' already exists.", specificare un nome diverso per l'entità servizio.If you receive an "'http://acr-service-principal' already exists." error, specify a different name for the service principal.

Facoltativamente, è possibile modificare --role il valore nel comando AZ ad SP create-for-RBAC se si desidera concedere autorizzazioni diverse.You can optionally modify the --role value in the az ad sp create-for-rbac command if you want to grant different permissions. Per un elenco completo dei ruoli, vedere ACR roles and permissions (Ruoli e autorizzazioni del registro Azure Container).For a complete list of roles, see ACR roles and permissions.

Dopo aver eseguito lo script, prendere nota dell'ID e della password dell'entità servizio.After you run the script, take note of the service principal's ID and password. Dopo aver ottenuto le credenziali, è possibile configurare le applicazioni e i servizi per l'autenticazione nel registro contenitori come entità servizio.Once you have its credentials, you can configure your applications and services to authenticate to your container registry as the service principal.

#!/bin/bash

# Modify for your environment.
# ACR_NAME: The name of your Azure Container Registry
# SERVICE_PRINCIPAL_NAME: Must be unique within your AD tenant
ACR_NAME=<container-registry-name>
SERVICE_PRINCIPAL_NAME=acr-service-principal

# Obtain the full registry ID for subsequent command args
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv)

# Create the service principal with rights scoped to the registry.
# Default permissions are for docker pull access. Modify the '--role'
# argument value as desired:
# acrpull:     pull only
# acrpush:     push and pull
# owner:       push, pull, and assign roles
SP_PASSWD=$(az ad sp create-for-rbac --name http://$SERVICE_PRINCIPAL_NAME --scopes $ACR_REGISTRY_ID --role acrpull --query password --output tsv)
SP_APP_ID=$(az ad sp show --id http://$SERVICE_PRINCIPAL_NAME --query appId --output tsv)

# Output the service principal's credentials; use these in your services and
# applications to authenticate to the container registry.
echo "Service principal ID: $SP_APP_ID"
echo "Service principal password: $SP_PASSWD"

Usare un'entità servizio esistenteUse an existing service principal

Per concedere al registro l'accesso a un'entità servizio esistente, è necessario assegnare un nuovo ruolo all'entità servizio.To grant registry access to an existing service principal, you must assign a new role to the service principal. Come per la creazione di una nuova entità servizio, è possibile concedere, tra gli altri, l'accesso pull, push e pull e proprietario.As with creating a new service principal, you can grant pull, push and pull, and owner access, among others.

Lo script seguente usa il comando AZ Role Assignment create per concedere le SERVICE_PRINCIPAL_ID autorizzazioni pull a un'entità servizio specificata nella variabile.The following script uses the az role assignment create command to grant pull permissions to a service principal you specify in the SERVICE_PRINCIPAL_ID variable. Modificare il valore --role se si vuole concedere un livello di accesso diverso.Adjust the --role value if you'd like to grant a different level of access.

#!/bin/bash

# Modify for your environment. The ACR_NAME is the name of your Azure Container
# Registry, and the SERVICE_PRINCIPAL_ID is the service principal's 'appId' or
# one of its 'servicePrincipalNames' values.
ACR_NAME=mycontainerregistry
SERVICE_PRINCIPAL_ID=<service-principal-ID>

# Populate value required for subsequent command args
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv)

# Assign the desired role to the service principal. Modify the '--role' argument
# value as desired:
# acrpull:     pull only
# acrpush:     push and pull
# owner:       push, pull, and assign roles
az role assignment create --assignee $SERVICE_PRINCIPAL_ID --scope $ACR_REGISTRY_ID --role acrpull

Script di esempioSample scripts

È possibile trovare gli script di esempio precedenti per l'interfaccia della riga di comando di Azure in GitHub, nonché le versioni per Azure PowerShell:You can find the preceding sample scripts for Azure CLI on GitHub, as well as versions for Azure PowerShell:

Eseguire l'autenticazione con l'entità servizioAuthenticate with the service principal

Quando si dispone di un'entità servizio a cui è stato concesso l'accesso al registro contenitori, è possibile configurarne le credenziali per l'accesso a servizi e applicazioni "privi di intestazioni" oppure immetterli usando il comando docker login.Once you have a service principal that you've granted access to your container registry, you can configure its credentials for access to "headless" services and applications, or enter them using the docker login command. Usare i valori seguenti:Use the following values:

  • Nome utente : ID dell'applicazione dell'entità servizio (noto anche come ID client)User name - service principal application ID (also called client ID)
  • Password : password dell'entità servizio (detta anche segreto client)Password - service principal password (also called client secret)

Ogni valore è un GUID del form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.Each value is a GUID of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Suggerimento

È possibile rigenerare la password di un'entità servizio eseguendo il comando az ad sp reset-credentials.You can regenerate the password of a service principal by running the az ad sp reset-credentials command.

Usare le credenziali con i servizi di AzureUse credentials with Azure services

È possibile usare le credenziali dell'entità servizio da qualsiasi servizio di Azure che esegue l'autenticazione con un registro contenitori di Azure.You can use service principal credentials from any Azure service that authenticates with an Azure container registry. Usare le credenziali dell'entità servizio al posto delle credenziali di amministratore del registro di sistema per diversi scenari.Use service principal credentials in place of the registry's admin credentials for a variety of scenarios.

Ad esempio, usare le credenziali per eseguire il pull di un'immagine da un registro contenitori di Azure a istanze di contenitore di Azure.For example, use the credentials to pull an image from an Azure container registry to Azure Container Instances.

Usare con l'account di accesso di DockerUse with docker login

È possibile eseguire docker login usando un'entità servizio.You can run docker login using a service principal. Nell'esempio seguente l'ID applicazione dell'entità servizio viene passato nella variabile di ambiente $SP_APP_IDe la password nella variabile $SP_PASSWD.In the following example, the service principal application ID is passed in the environment variable $SP_APP_ID, and the password in the variable $SP_PASSWD. Per le procedure consigliate per gestire le credenziali Docker, vedere la Guida di riferimento al comando Docker login .For best practices to manage Docker credentials, see the docker login command reference.

# Log in to Docker with service principal credentials
docker login myregistry.azurecr.io --username $SP_APP_ID --password $SP_PASSWD

Una volta effettuato l'accesso, Docker memorizza nella cache le credenziali.Once logged in, Docker caches the credentials.

USA con certificatoUse with certificate

Se è stato aggiunto un certificato all'entità servizio, è possibile accedere all'interfaccia della riga di comando di Azure con l'autenticazione basata su certificati, quindi usare il comando AZ ACR login per accedere a un registro.If you've added a certificate to your service principal, you can sign into the Azure CLI with certificate-based authentication, and then use the az acr login command to access a registry. Quando si usa l'interfaccia della riga di comando, l'uso di un certificato come segreto anziché una password fornisce sicurezza aggiuntiva.Using a certificate as a secret instead of a password provides additional security when you use the CLI.

Quando si Crea un'entità servizio, è possibile creare un certificato autofirmato.A self-signed certificate can be created when you create a service principal. In alternativa, aggiungere uno o più certificati a un'entità servizio esistente.Or, add one or more certificates to an existing service principal. Se ad esempio si usa uno degli script in questo articolo per creare o aggiornare un'entità servizio con diritti per eseguire il pull o il push di immagini da un registro, aggiungere un certificato usando il comando AZ ad SP Credential Reset .For example, if you use one of the scripts in this article to create or update a service principal with rights to pull or push images from a registry, add a certificate using the az ad sp credential reset command.

Per usare l'entità servizio con il certificato per accedere all'interfaccia dellariga di comando di Azure, il certificato deve essere in formato PEM e includere la chiave privata.To use the service principal with certificate to sign into the Azure CLI, the certificate must be in PEM format and include the private key. Se il certificato non è nel formato richiesto, usare uno strumento come openssl per convertirlo.If your certificate isn't in the required format, use a tool such as openssl to convert it. Quando si esegue AZ login per accedere all'interfaccia della riga di comando usando l'entità servizio, specificare anche l'ID applicazione dell'entità servizio e l'ID del tenant Active Directory.When you run az login to sign into the CLI using the service principal, also provide the service principal's application ID and the Active Directory tenant ID. Nell'esempio seguente vengono illustrati questi valori come variabili di ambiente:The following example shows these values as environment variables:

az login --service-principal --username $SP_APP_ID --tenant $SP_TENANT_ID  --password /path/to/cert/pem/file

Eseguire quindi AZ ACR login per l'autenticazione con il registro di sistema:Then, run az acr login to authenticate with the registry:

az acr login --name myregistry

L'interfaccia della riga di comando usa il token creato quando è stato eseguito az login per autenticare la sessione con il registro di sistema.The CLI uses the token created when you ran az login to authenticate your session with the registry.

Passaggi successiviNext steps