Creare un token con autorizzazioni con ambito repository

Questo articolo descrive come creare token e mappe di ambito per gestire l'accesso ai repository nel registro contenitori. Con la creazione dei token, il proprietario di un registro può offrire a utenti o servizi un accesso con ambito a tempo limitato ai repository per effettuare il pull o il push di immagini o eseguire altre azioni. Un token offre autorizzazioni più specifiche rispetto ad altre opzioni di autenticazione del registro, che definiscono come ambito delle autorizzazioni un intero registro.

Gli scenari comuni per la creazione di un token includono:

  • Consentire ai dispositivi IoT con singoli token di eseguire il pull di un'immagine da un repository.
  • Fornire a un'organizzazione esterna le autorizzazioni per un percorso del repository.
  • Limitare l'accesso al repository a diversi gruppi di utenti dell'organizzazione. Ad esempio, si può concedere l'accesso in lettura e scrittura agli sviluppatori che creano immagini destinate a repository specifici e l'accesso in lettura ai team che effettuano distribuzioni da tali repository.

Questa funzionalità è disponibile in tutti i livelli di servizio. Per informazioni sui livelli di servizio e sui limiti del Registro di sistema, vedere Registro Azure Container livelli di servizio

Limiti

  • Non è attualmente possibile assegnare autorizzazioni con ambito repository a un'identità Microsoft Entra, ad esempio un'entità servizio o un'identità gestita.

Concetti

Per configurare le autorizzazioni con ambito repository, è necessario creare un token con un mapping di ambito associato.

  • Un token insieme a una password generata consente all'utente di eseguire l'autenticazione con il registro. È possibile impostare una data di scadenza per una password del token o disabilitare un token in qualsiasi momento.

    Dopo l'autenticazione con un token, l'utente o il servizio può eseguire una o più azioni nell'ambito di uno o più repository.

    Azione Descrizione Esempio
    content/delete Rimuovere i dati dal repository Eliminare un repository o un manifesto
    content/read Leggere i dati dal repository Eseguire il pull di un artefatto
    content/write Scrivere dati nel repository Usare con content/read per eseguire il push di un artefatto
    metadata/read Leggere i metadati dal repository Elencare tag o manifesti
    metadata/write Scrivere i metadati nel repository Abilitare o disabilitare le operazioni di lettura, scrittura o eliminazione

Nota

Le autorizzazioni con ambito repository non supportano la possibilità di elencare il catalogo di tutti i repository nel Registro di sistema.

  • Un mapping dell'ambito raggruppa le autorizzazioni del repository applicate a un token e può riapplicare ad altri token. Ogni token è associato a un singolo mapping di ambito. Con una mappa dell'ambito, è possibile:

    • Configurare più token con autorizzazioni identiche per un set di repository.
    • Aggiornare le autorizzazioni del token quando si aggiungono o si rimuovono azioni del repository nella mappa dell'ambito o si applica una mappa di ambito diversa.

    Registro Azure Container fornisce anche diverse mappe di ambito definite dal sistema che è possibile applicare durante la creazione di token. Le autorizzazioni delle mappe dell'ambito definite dal sistema si applicano a tutti i repository nel Registro di sistema. Le singole azioni corrispondono al limite dei repository per ogni mappa di ambito.

L'immagine seguente illustra la relazione tra token e mapping di ambito.

Registry tokens and scope maps

Prerequisiti

  • Interfaccia della riga di comando di Azure - Esempi di comandi dell'interfaccia della riga di comando di Azure in questo articolo richiedono l'interfaccia della riga di comando di Azure versione 2.17.0 o successiva. Eseguire az --version per trovare la versione. Se è necessario eseguire l'installazione o l'aggiornamento, vedere Installare l'interfaccia della riga di comando di Azure.
  • Docker: per eseguire l'autenticazione con il registro per effettuare il pull o il push di immagini, è necessaria un'installazione locale di Docker. Docker offre istruzioni di installazione per sistemi macOS, Windows e Linux.
  • Registro Contenitori: se non è disponibile, creare un registro contenitori nella sottoscrizione di Azure. Ad esempio usare il portale di Azure oppure l'interfaccia della riga di comando di Azure.

Creare il token - interfaccia della riga di comando

Creare il token e specificare i repository

Creare un token usando il comando az acr token create. Quando si crea un token, è possibile specificare uno o più repository e le azioni associate in ogni repository. Non è necessario che i repository siano già nel registro. Per creare un token specificando una mappa di ambito esistente, vedere la sezione successiva.

Nell'esempio seguente viene creato un token nel registro myregistry con le seguenti autorizzazioni per il repository samples/hello-world: content/write e content/read. Per impostazione predefinita, il comando imposta lo stato del token predefinito su enabled, ma è possibile aggiornare lo stato impostandolo su disabled in qualsiasi momento.

az acr token create --name MyToken --registry myregistry \
  --repository samples/hello-world \
  content/write content/read \
  --output json

L'output mostra i dettagli sul token. Per impostazione predefinita, vengono generate due password che non scadono, ma facoltativamente è possibile impostare una data di scadenza. È consigliabile salvare le password in un luogo sicuro per usarle in un secondo momento per l'autenticazione. Le password non possono essere nuovamente recuperate, ma è possibile generarne di nuove.

{
  "creationDate": "2020-01-18T00:15:34.066221+00:00",
  "credentials": {
    "certificates": [],
    "passwords": [
      {
        "creationTime": "2020-01-18T00:15:52.837651+00:00",
        "expiry": null,
        "name": "password1",
        "value": "uH54BxxxxK7KOxxxxRbr26dAs8JXxxxx"
      },
      {
        "creationTime": "2020-01-18T00:15:52.837651+00:00",
        "expiry": null,
        "name": "password2",
        "value": "kPX6Or/xxxxLXpqowxxxxkA0idwLtmxxxx"
      }
    ],
    "username": "MyToken"
  },
  "id": "/subscriptions/xxxxxxxx-adbd-4cb4-c864-xxxxxxxxxxxx/resourceGroups/myresourcegroup/providers/Microsoft.ContainerRegistry/registries/myregistry/tokens/MyToken",
  "name": "MyToken",
  "objectId": null,
  "provisioningState": "Succeeded",
  "resourceGroup": "myresourcegroup",
  "scopeMapId": "/subscriptions/xxxxxxxx-adbd-4cb4-c864-xxxxxxxxxxxx/resourceGroups/myresourcegroup/providers/Microsoft.ContainerRegistry/registries/myregistry/scopeMaps/MyToken-scope-map",
  "status": "enabled",
  "type": "Microsoft.ContainerRegistry/registries/tokens"
}

Nota

Per rigenerare le password dei token e i periodi di scadenza, vedere Rigenerare le password dei token più avanti in questo articolo.

L'output include i dettagli sul mapping di ambito creato dal comando. È possibile usare il mapping di ambito, qui denominato MyToken-scope-map, per applicare le stesse azioni del repository ad altri token. Oppure aggiornare il mapping di ambito in seguito per modificare le autorizzazioni dei token associati.

Creare il token e specificare il mapping di ambito

Un metodo alternativo per creare un token è specificare un mapping di ambito esistente. Se non si ha un mapping di ambito, per prima cosa crearne uno specificando i repository e le azioni associate. Quindi, specificare il mapping di ambito quano si crea un token.

Per creare un mapping di ambito, usare il comando az acr scope-map create. Il comando seguente crea un mapping di ambito con le stesse autorizzazioni per il repository samples/hello-world usato in precedenza.

az acr scope-map create --name MyScopeMap --registry myregistry \
  --repository samples/hello-world \
  content/write content/read \
  --description "Sample scope map"

Eseguire az acr token create per creare un token, specificando il mapping di ambito MyScopeMap. Come nell'esempio precedente, il comando imposta lo stato predefinito del token su enabled.

az acr token create --name MyToken \
  --registry myregistry \
  --scope-map MyScopeMap

L'output mostra i dettagli sul token. Per impostazione predefinita, vengono generate due password. È consigliabile salvare le password in un luogo sicuro per usarle in un secondo momento per l'autenticazione. Le password non possono essere nuovamente recuperate, ma è possibile generarne di nuove.

Nota

Per rigenerare le password dei token e i periodi di scadenza, vedere Rigenerare le password dei token più avanti in questo articolo.

Come usare le mappe dell'ambito per definire e assegnare autorizzazioni per più repository

Una mappa di ambito consente l'uso di un carattere jolly per definire e concedere autorizzazioni simili per più repository che condividono un prefisso comune. I repository con autorizzazioni specifiche, i repository con un carattere jolly possono essere usati anche nella stessa mappa di ambito. Ciò offre flessibilità nella gestione delle autorizzazioni per un set multiplo di repository in una singola mappa di ambito.

Le autorizzazioni del repository possono essere create quando viene creata una mappa dell'ambito e assegnata a un token. In alternativa, è possibile creare e assegnare direttamente un token a un repository.

Nell'esempio seguente viene creata una mappa dell'ambito con un carattere jolly e quindi la si assegna a un token.

az acr scope-map create --name MyScopeMapWildcard --registry myregistry \
  --repository samples/* \
  content/write content/read \
  --description "Sample scope map with wildcards"
az acr token create --name MyTokenWildcard \
  --registry myregistry \
  --scope-map MyScopeMapWildcard

Nell'esempio seguente viene creato un token con un carattere jolly.

 az acr token create --name MyTokenWildcard --registry myregistry \
  --repository samples/* \
  content/write content/read \

Le autorizzazioni con caratteri jolly sono aggiuntive, ovvero quando si accede a un repository specifico, le autorizzazioni risultanti includono le autorizzazioni per tutte le regole della mappa dell'ambito che corrispondono al prefisso con caratteri jolly.

In questo esempio, la mappa dell'ambito definisce le autorizzazioni per tre diversi tipi di repository:

Repository Autorizzazione
sample/* content/read
sample/teamA/* content/write
sample/teamA/projectB content/delete

Al token viene assegnato un mapping dell'ambito per concedere [content/read, content/write, content/delete] le autorizzazioni per l'accesso al repository sample/teamA/projectB. Tuttavia, quando lo stesso token viene usato per accedere al sample/teamA/projectC repository, dispone [content/read, content/write] solo delle autorizzazioni.

Importante

I repository che usano caratteri jolly nella mappa dell'ambito devono sempre terminare con un /* suffisso per essere validi e avere un singolo carattere jolly nel nome del repository. Ecco alcuni esempi di caratteri jolly non validi:

  • sample/*/teamA con un carattere jolly al centro del nome del repository.
  • sample/teamA* con un carattere jolly non termina con "/*".
  • sample/teamA/*/projectB/* con più caratteri jolly nel nome del repository.

Caratteri jolly a livello radice

I caratteri jolly possono essere applicati anche a livello radice. Ciò significa che tutte le autorizzazioni assegnate al repository definito come *, verranno applicate a livello del Registro di sistema.

Nell'esempio viene illustrato come creare un token con un carattere jolly a livello radice che assegna le autorizzazioni del token [content/read, content/write] a tutti i repository nel Registro di sistema. In questo modo è possibile concedere autorizzazioni a tutti i repository nel Registro di sistema senza dover specificare singolarmente ogni repository.

 az acr token create --name MyTokenWildcard --registry myregistry \
  --repository * \
  content/write content/read \

Importante

Se una regola con caratteri jolly include un repository che non esiste ancora, le autorizzazioni della regola con caratteri jolly verranno comunque applicate al nome del repository. Ad esempio, un token assegnato a una mappa dell'ambito che concede [content/write, metadata/write] le autorizzazioni per sample/* i repository. Si supponga inoltre che il repository sample/teamC/teamCimage non esista ancora. Il token avrà le autorizzazioni per il push delle immagini nel repository sample/teamC/teamCimage, che creerà contemporaneamente il repository al completamento del push.

Creare il token - portale

È possibile usare il portale di Azure per creare token e mapping di ambito. Come per il comando az acr token create dell'interfaccia della riga di comando, è possibile applicare un mapping di ambito esistente o creare un mapping di ambito quando si crea un token specificando uno o più repository e le azioni associate. Non è necessario che i repository siano già nel registro.

Nell'esempio seguente vengono creati un token e un mapping di ambito con le seguenti autorizzazioni per il repository samples/hello-world: content/write e content/read.

  1. Nel portale passare al registro contenitori.

  2. In Autorizzazioni repository selezionare Token > +Aggiungi.

    Create token in portal

  3. Immettere un nome di token.

  4. In Mapping di ambito selezionare Crea nuovo.

  5. Configurare il mapping di ambito:

    1. Immettere un nome e una descrizione per il mapping di ambito.

    2. In Repository immettere samples/hello-world e in Autorizzazioni selezionare content/read e content/write. Quindi selezionare +Aggiungi.

      Create scope map in portal

    3. Dopo l'aggiunta di repository e autorizzazioni, selezionare Aggiungi per aggiungere il mapping di ambito.

  6. Accettare lo stato predefinito del token Abilitato e quindi selezionare Crea.

Dopo che il token è stato convalidato e creato, i dettagli del token vengono visualizzati nella schermata Token.

Aggiungere la password del token

Per usare un token creato nel portale, è necessario generare una password. È possibile generare una o due password e impostare una data di scadenza per ciascuna di esse. Le nuove password create per i token sono immediatamente disponibili. La rigenerazione di nuove password per i token richiederà 60 secondi per la replica e sarà disponibile.

  1. Nel portale passare al registro contenitori.

  2. In Autorizzazioni repository selezionare Token e selezionare un token.

  3. Nei dettagli del token selezionare password1 o password2 e selezionare l'icona Genera.

  4. Nella schermata della password, se necessario impostare una data di scadenza per la password e selezionare Genera. È consigliabile impostare una data di scadenza.

  5. Dopo aver generato una password, copiarla e salvarla in una posizione sicura. Non è possibile recuperare una password generata dopo aver chiuso la schermata, ma è possibile generarne una nuova.

    Create token password in portal

Eseguire l'autenticazione con un token

Quando un utente o un servizio usa un token per l'autenticazione con il registro di destinazione, specifica il nome del token come nome utente e una delle password generate.

Il metodo di autenticazione dipende dall'azione o dalle azioni configurate associate al token.

Azione Come eseguire l'autenticazione
content/delete az acr repository delete nell'interfaccia della riga di comando di Azure

Esempio: az acr repository delete --name myregistry --repository myrepo --username MyToken --password xxxxxxxxxx
content/read docker login

az acr login nell'interfaccia della riga di comando di Azure

Esempio: az acr login --name myregistry --username MyToken --password xxxxxxxxxx
content/write docker login

az acr login nell'interfaccia della riga di comando di Azure
metadata/read az acr repository show

az acr repository show-tags

az acr manifest list-metadata nell'interfaccia della riga di comando di Azure
metadata/write az acr repository untag

az acr repository update nell'interfaccia della riga di comando di Azure

Esempi: Usare il token

Gli esempi seguenti usano il token creato in precedenza in questo articolo per eseguire operazioni comuni su un repository: push e pull di immagini, eliminazione di immagini ed elenco dei tag del repository. Il token è stato configurato inizialmente con le autorizzazioni push (azioni content/write e content/read) per il repository samples/hello-world.

Eseguire il pull e contrassegnare le immagini di test

Per gli esempi seguenti, eseguire il pull di immagini e nginx pubbliche hello-world da Registro Contenitori Microsoft e contrassegnarle per il registro e il repository.

docker pull mcr.microsoft.com/hello-world
docker pull mcr.microsoft.com/oss/nginx/nginx:1.15.5-alpine
docker tag mcr.microsoft.com/hello-world myregistry.azurecr.io/samples/hello-world:v1
docker tag mcr.microsoft.com/oss/nginx/nginx:1.15.5-alpine myregistry.azurecr.io/samples/nginx:v1

Eseguire l'autenticazione con il token

Eseguire docker login o az acr login per eseguire l'autenticazione con il Registro di sistema per eseguire il push o il pull delle immagini. Specificare il nome del token come nome utente e specificare una delle relative password. Lo stato del token deve essere Enabled.

L'esempio seguente è formattato per la shell Bash e specifica i valori usando le variabili di ambiente.

TOKEN_NAME=MyToken
TOKEN_PWD=<token password>

echo $TOKEN_PWD | docker login --username $TOKEN_NAME --password-stdin myregistry.azurecr.io

L'output dovrebbe indicare che l'autenticazione è riuscita:

Login Succeeded

Eseguire il push delle immagini nel registro

Dopo aver eseguito l'accesso, provare a eseguire il push delle immagini contrassegnate nel registro. Poiché il token ha le autorizzazioni per eseguire il push delle immagini nel repository samples/hello-world, il push seguente ha esito positivo:

docker push myregistry.azurecr.io/samples/hello-world:v1

Il token non ha le autorizzazioni per il repository samples/nginx, quindi il tentativo di push seguente ha esito negativo con un errore simile a requested access to the resource is denied:

docker push myregistry.azurecr.io/samples/nginx:v1

Aggiornare le autorizzazioni del token

Per aggiornare le autorizzazioni di un token, aggiornare le autorizzazioni nel mapping di ambito associato. Il mapping di ambito aggiornato viene applicato immediatamente a tutti i token associati.

Ad esempio, aggiornare MyToken-scope-map con le azioni content/write e content/read per il repository samples/ngnx e rimuovere l'azione content/write per il repository samples/hello-world.

Per usare l'interfaccia della riga di comando di Azure, eseguire az acr scope-map update per aggiornare il mapping di ambito:

az acr scope-map update \
  --name MyScopeMap \
  --registry myregistry \
  --add-repository samples/nginx content/write content/read \
  --remove-repository samples/hello-world content/write 

Nel portale di Azure:

  1. Passare al registro contenitori.
  2. In Autorizzazioni repository selezionare Mappe ambito e selezionare la mappa dell'ambito da aggiornare.
  3. In Repository immettere samples/nginx e in Autorizzazioni selezionare content/read e content/write. Quindi selezionare +Aggiungi.
  4. In Repository selezionare samples/hello-world e in Autorizzazioni deselezionare content/write. Quindi selezionare Salva.

Dopo aver aggiornato il mapping di ambito, il push seguente viene eseguito correttamente:

docker push myregistry.azurecr.io/samples/nginx:v1

Poiché il mapping di ambito ha solo l'autorizzazione content/read per il repository samples/hello-world, un tentativo di push al repository samples/hello-world ora non riesce:

docker push myregistry.azurecr.io/samples/hello-world:v1

Il pull di immagini da entrambi i repository ha esito positivo, perché il mapping di ambito concede autorizzazioni content/read per entrambi i repository:

docker pull myregistry.azurecr.io/samples/nginx:v1
docker pull myregistry.azurecr.io/samples/hello-world:v1

Eliminare le immagini

Aggiornare il mapping di ambito aggiungendo l'azione content/delete al repository nginx. Questa azione consente di eliminare immagini nel repository o l'intero repository.

Per brevità, viene visualizzato solo il comando az acr scope-map update per l'aggiornamento del mapping di ambito:

az acr scope-map update \
  --name MyScopeMap \
  --registry myregistry \
  --add-repository samples/nginx content/delete

Per aggiornare la mappa dell'ambito usando il portale, vedere la sezione precedente.

Usare il seguente comando az acr repository delete per eliminare il repository samples/nginx. Per eliminare immagini o repository, passare il nome e la password del token al comando. L'esempio seguente usa le variabili di ambiente create in precedenza nell'articolo:

az acr repository delete \
  --name myregistry --repository samples/nginx \
  --username $TOKEN_NAME --password $TOKEN_PWD

Visualizzare i tag del repository

Aggiornare il mapping di ambito aggiungendo l'azione metadata/read al repository hello-world. Questa azione consente di leggere i dati del manifesto e dei tag nel repository.

Per brevità, viene visualizzato solo il comando az acr scope-map update per l'aggiornamento del mapping di ambito:

az acr scope-map update \
  --name MyScopeMap \
  --registry myregistry \
  --add-repository samples/hello-world metadata/read 

Per aggiornare la mappa dell'ambito usando il portale, vedere la sezione precedente.

Per leggere i metadati nel samples/hello-world repository, eseguire il comando az acr manifest list-metadata o az acr repository show-tags .

Per leggere i metadati, passare il nome e la password del token a uno dei due comandi. L'esempio seguente usa le variabili di ambiente create in precedenza nell'articolo:

az acr repository show-tags \
  --name myregistry --repository samples/hello-world \
  --username $TOKEN_NAME --password $TOKEN_PWD

Output di esempio:

[
  "v1"
]

Gestire i token e i mapping di ambito

Elenco dei mapping di ambito

Usare il comando az acr scope-map list o la schermata Mappe ambito nel portale per elencare tutte le mappe di ambito configurate in un registro. Ad esempio:

az acr scope-map list \
  --registry myregistry --output table

L'output è costituito dalle tre mappe di ambito definite dal sistema e da altre mappe di ambito generate dall'utente. I token possono essere configurati con una qualsiasi di queste mappe di ambito.

NAME                 TYPE           CREATION DATE         DESCRIPTION
-------------------  -------------  --------------------  ------------------------------------------------------------
_repositories_admin  SystemDefined  2020-01-20T09:44:24Z  Can perform all read, write and delete operations on the ...
_repositories_pull   SystemDefined  2020-01-20T09:44:24Z  Can pull any repository of the registry
_repositories_push   SystemDefined  2020-01-20T09:44:24Z  Can push to any repository of the registry
MyScopeMap           UserDefined    2019-11-15T21:17:34Z  Sample scope map

Visualizzare i dettagli del token

Per visualizzare i dettagli di un token, ad esempio le date di scadenza dello stato e della password, eseguire il comando az acr token show oppure selezionare il token nella schermata Token del portale. Ad esempio:

az acr scope-map show \
  --name MyScopeMap --registry myregistry

Usare il comando az acr token list o la schermata Token nel portale per elencare tutti i token configurati in un registro. Ad esempio:

az acr token list --registry myregistry --output table

Rigenerare le password dei token

Se non è stata generata una password del token o si vogliono generare nuove password, eseguire il comando az acr token credential generate . La rigenerazione di nuove password per i token richiederà 60 secondi per la replica e sarà disponibile.

Nell'esempio seguente viene generato un nuovo valore per password1 per il token MyToken, con un periodo di scadenza di 30 giorni. La password viene archiviata nella variabile di ambiente TOKEN_PWD. Questo esempio è formattato per la shell Bash.

TOKEN_PWD=$(az acr token credential generate \
  --name MyToken --registry myregistry --expiration-in-days 30 \
  --password1 --query 'passwords[0].value' --output tsv)

Per usare il portale di Azure per generare una password del token, vedere i passaggi in Creare il token - portale più indietro in questo articolo.

Aggiornare il token con un nuovo mapping di ambito

Se si vuole aggiornare un token con un altro mapping di ambito, eseguire az acr token update e specificare il nuovo mapping di ambito. Ad esempio:

az acr token update --name MyToken --registry myregistry \
  --scope-map MyNewScopeMap

Nella schermata Token del portale selezionare il token e in Mappa ambito selezionare una mappa di ambito diversa.

Suggerimento

Dopo l'aggiornamento di un token con un nuovo mapping di ambito, potrebbe essere necessario generare nuove password per il token. Usare il comando az acr token credential generate o rigenerare una password del token nel portale di Azure.

Disabilitare o eliminare il token

Potrebbe essere necessario disabilitare temporaneamente l'uso delle credenziali del token per un utente o un servizio.

Usando l'interfaccia della riga di comando di Azure, eseguire il comando az acr token update per impostare status su disabled:

az acr token update --name MyToken --registry myregistry \
  --status disabled

Nel portale selezionare il token nella schermata Token e selezionare Disabilitato in Stato.

Per eliminare un token e invalidare in modo permanente l'accesso da parte di chiunque usi le relative credenziali, eseguire il comando az acr token delete.

az acr token delete --name MyToken --registry myregistry

Nel portale selezionare il token nella schermata Token e selezionare Ignora.

Passaggi successivi

  • Per gestire i mapping di ambito e i token, usare i comandi aggiuntivi dei gruppi az acr scope-map e az acr token.
  • Vedere la panoramica dell'autenticazione per altre opzioni per l'autenticazione con un Registro Azure Container, tra cui l'uso di un'identità di Microsoft Entra, un'entità servizio o un account amministratore.
  • Informazioni sui registri connessi e sull'uso dei token per l'accesso.