Creare un token con autorizzazioni con ambito repository
Questo articolo descrive come creare token e mappe dell'ambito per gestire l’accesso a 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 effettuare il pull di un'immagine da un repository.
- Rendere disponibili per un'organizzazione esterna le autorizzazioni per un 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 contenitori, vedere Livelli di servizio del Registro Azure Container
Limiti
- Attualmente, non è possibile assegnare autorizzazioni con ambito repository a un'identità di 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 artefattometadata/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 di ambito raggruppa le autorizzazioni del repository che si applicano a un token e possono essere riapplicate 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 rimuovono azioni del repository nel mapping di ambito o si applica un mapping di ambito diverso.
Registro Azure Container offre anche diverse mappe di ambito definite dal sistema che possono essere applicate durante la creazione di token. Le autorizzazioni di mappe di ambito definite dal sistema si applicano a tutti i repository nel registro. 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.
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 successive. 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 si dispone già di uno, 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 senza scadenza; tuttavia, è 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 password dei token e periodi di scadenza, vedere Rigenerare 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 password dei token e periodi di scadenza, vedere Rigenerare password dei token più avanti in questo articolo.
Come usare mappe di 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. Repository con autorizzazioni specifiche, repository con un carattere jolly possono essere usati anche nella stessa mappa di ambito. Ciò offre flessibilità nella gestione delle autorizzazioni per un set di più repository in una singola mappa di ambito.
Le autorizzazioni di repository possono essere create durante la creazione e l’assegnazione a un token di una mappa di ambito. In alternativa, è possibile creare e assegnare direttamente un token a un repository.
Nell'esempio seguente viene creata una mappa di ambito con un carattere jolly che viene quindi assegnata 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, il che significa che quando si accede a un repository specifico, le autorizzazioni risultanti includeranno le autorizzazioni per tutte le regole della mappa di ambito che corrispondono al prefisso con carattere jolly.
In questo esempio, la mappa di 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 a [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 repository sample/teamA/projectC
, dispone solo di autorizzazioni [content/read, content/write]
.
Importante
I repository che usano caratteri jolly nella mappa di 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 di radice
I caratteri jolly possono essere applicati anche a livello di radice. Ciò significa che tutte le autorizzazioni assegnate al repository definito come *
verranno applicate a livello di registro.
Nell'esempio viene illustrato come creare un token con un carattere jolly a livello di radice che assegna le autorizzazioni del token [content/read, content/write]
a tutti i repository nel registro. In questo modo, è possibile concedere autorizzazioni a tutti i repository nel registro senza dover specificare ogni repository singolarmente.
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 è ancora esistente, le autorizzazioni della regola con caratteri jolly saranno comunque applicate al nome del repository.
Ad esempio, un token assegnato a una mappa dell'ambito che concede a [content/write, metadata/write]
le autorizzazioni per i repository sample/*
.
Si supponga inoltre che il repository sample/teamC/teamCimage
non sia ancora esistente.
Il token avrà le autorizzazioni per eseguire il push di immagini nel repository sample/teamC/teamCimage
, il 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
.
Nel portale passare al registro contenitori.
In Autorizzazioni repository, selezionare Token > +Aggiungi.
Immettere un nome di token.
In Mapping di ambito selezionare Crea nuovo.
Configurare il mapping di ambito:
Immettere un nome e una descrizione per il mapping di ambito.
In Repository immettere
samples/hello-world
e in Autorizzazioni selezionarecontent/read
econtent/write
. Quindi selezionare +Aggiungi.Dopo l'aggiunta di repository e autorizzazioni, selezionare Aggiungi per aggiungere il mapping di ambito.
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 completare la replica e risultare disponibile.
Nel portale passare al registro contenitori.
In Autorizzazioni repository, selezionare Token e quindi selezionare un token.
Nei dettagli del token selezionare password1 o password2 e selezionare l'icona Genera.
Nella schermata della password, se necessario impostare una data di scadenza per la password e selezionare Genera. È consigliabile impostare una data di scadenza.
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.
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 AzureEsempio: 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 AzureEsempio: 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 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 pubbliche hello-world
e nginx
dal 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 per eseguire il push o il pull di 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 autorizzazioni di 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:
- Passare al registro contenitori.
- In Autorizzazioni repository, selezionare Mappe di ambito e quindi selezionare la mappa di ambito da aggiornare.
- In Repository immettere
samples/nginx
e in Autorizzazioni selezionarecontent/read
econtent/write
. Quindi selezionare +Aggiungi. - In Repository selezionare
samples/hello-world
e in Autorizzazioni deselezionarecontent/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 di 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 di ambito usando il portale, vedere la sezione precedente.
Per leggere metadati nel repository samples/hello-world
, eseguire il comando az acr manifest list-metadata o az acr repository show-tags.
Per leggere 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
Per elencare tutte le mappe di ambito configurate in un registro, usare il comando az acr scope-map list o la schermata Mappe di ambito nel portale. 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 lo stato e le date di scadenza delle password, eseguire il comando az acr token show oppure selezionare il token nella schermata Token nel portale. Ad esempio:
az acr scope-map show \
--name MyScopeMap --registry myregistry
Per elencare tutti i token configurati in un registro, usare il comando az acr token list o la schermata Token nel portale. Ad esempio:
az acr token list --registry myregistry --output table
Rigenerare password dei token
Se non è già stata generata una password del token o se si vuole generare nuove password, eseguire il comando az acr token credential generate. La rigenerazione di nuove password per i token richiederà 60 secondi per completare la replica e risultare 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 quindi un’altra mappa di ambito in Mappa di ambito.
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 Rimuovi.
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 sull'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 su registri connessi e sull'uso di token per l'accesso.