Skapa en token med behörigheter med lagringsplatsomfattning

Artikel
12/09/2023

Den här artikeln beskriver hur du skapar token och omfångskartor för att hantera åtkomst till lagringsplatser i containerregistret. Genom att skapa token kan en registerägare ge användare eller tjänster begränsad åtkomst till lagringsplatser för att hämta eller push-överföra avbildningar eller utföra andra åtgärder. En token ger mer detaljerade behörigheter än andra alternativ för registerautentisering, som omfångsbehörigheter till ett helt register.

Vanliga scenarier för att skapa en token är:

Tillåt att IoT-enheter med enskilda token hämtar en avbildning från en lagringsplats.
Ge en extern organisation behörighet till en lagringsplatssökväg.
Begränsa lagringsplatsens åtkomst till olika användargrupper i din organisation. Ge till exempel skriv- och läsåtkomst till utvecklare som skapar avbildningar som riktar sig mot specifika lagringsplatser och läsåtkomst till team som distribuerar från dessa lagringsplatser.

Den här funktionen är tillgänglig på alla tjänstnivåer. Information om registertjänstnivåer och -gränser finns i Tjänstnivåer för Azure Container Registry

Begränsningar

Du kan för närvarande inte tilldela behörigheter med lagringsplatsomfattning till en Microsoft Entra-identitet, till exempel tjänstens huvudnamn eller hanterade identitet.

Begrepp

Om du vill konfigurera behörigheter med lagringsplatsomfattning skapar du en token med en associerad omfångskarta.

Med en token tillsammans med ett genererat lösenord kan användaren autentisera med registret. Du kan ange ett förfallodatum för ett tokenlösenord eller inaktivera en token när som helst.

När du har autentiserat med en token kan användaren eller tjänsten utföra en eller flera åtgärder som är begränsade till en eller flera lagringsplatser.

Åtgärd	Beskrivning	Exempel
`content/delete`	Ta bort data från lagringsplatsen	Ta bort en lagringsplats eller ett manifest
`content/read`	Läsa data från lagringsplatsen	Hämta en artefakt
`content/write`	Skriva data till lagringsplatsen	Använd med `content/read` för att push-överföra en artefakt
`metadata/read`	Läsa metadata från lagringsplatsen	Lista taggar eller manifest
`metadata/write`	Skriva metadata till lagringsplatsen	Aktivera eller inaktivera läs-, skriv- eller borttagningsåtgärder

Kommentar

Behörigheter med lagringsplatsomfattning stöder inte möjligheten att lista katalogen över alla lagringsplatser i registret.

En omfångskarta grupperar lagringsplatsens behörigheter som du tillämpar på en token och kan tillämpas på andra token igen. Varje token är associerad med en enda omfångskarta. Med en omfångskarta kan du:
- Konfigurera flera token med identiska behörigheter till en uppsättning lagringsplatser.
- Uppdatera tokenbehörigheter när du lägger till eller tar bort lagringsplatsåtgärder i omfångskartan eller tillämpar en annan omfångskarta.
Azure Container Registry innehåller också flera systemdefinierade omfångskartor som du kan använda när du skapar token. Behörigheterna för systemdefinierade omfångskartor gäller för alla lagringsplatser i registret. De enskilda åtgärderna motsvarar gränsen för lagringsplatser per omfångskarta.

Följande bild visar relationen mellan token och omfångskartor.

Registry tokens and scope maps

Förutsättningar

Azure CLI – Azure CLI-kommandoexempel i den här artikeln kräver Azure CLI version 2.17.0 eller senare. Kör az --version för att hitta versionen. Om du behöver installera eller uppgradera kan du läsa Installera Azure CLI.
Docker – Om du vill autentisera med registret för att hämta eller push-överföra avbildningar behöver du en lokal Docker-installation. I Docker finns installationsanvisningar för macOS, Windows och Linux.
Containerregister – Om du inte har något skapar du ett containerregister i din Azure-prenumeration. Du kan till exempel använda Azure-portalen eller Azure CLI.

Skapa token – CLI

Skapa token och ange lagringsplatser

Skapa en token med kommandot az acr token create . När du skapar en token kan du ange en eller flera lagringsplatser och associerade åtgärder på varje lagringsplats. Lagringsplatserna behöver inte finnas i registret än. Information om hur du skapar en token genom att ange en befintlig omfångskarta finns i nästa avsnitt.

I följande exempel skapas en token i registrets myregistry med följande behörigheter på lagringsplatsen samples/hello-world : content/write och content/read. Som standard anger kommandot standardtokens status till enabled, men du kan uppdatera statusen till disabled när som helst.

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

Utdata visar information om token. Som standard genereras två lösenord som inte upphör att gälla, men du kan också ange ett förfallodatum. Vi rekommenderar att du sparar lösenorden på en säker plats för senare autentisering. Lösenorden kan inte hämtas igen, men nya kan genereras.

{
  "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"
}

Kommentar

Information om hur du återskapar tokenlösenord och förfalloperioder finns i Återskapa tokenlösenord senare i den här artikeln.

Utdata innehåller information om omfångskartan som kommandot skapade. Du kan använda omfångskartan, här med namnet MyToken-scope-map, för att tillämpa samma lagringsplatsåtgärder på andra token. Eller uppdatera omfångskartan senare för att ändra behörigheterna för de associerade token.

Skapa token och ange omfångskarta

Ett annat sätt att skapa en token är att ange en befintlig omfångskarta. Om du inte redan har en omfångskarta skapar du först en genom att ange lagringsplatser och associerade åtgärder. Ange sedan omfångskartan när du skapar en token.

Om du vill skapa en omfångskarta använder du kommandot az acr scope-map create . Följande kommando skapar en omfångskarta med samma behörigheter på lagringsplatsen samples/hello-world som användes tidigare.

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

Kör az acr token create för att skapa en token och ange omfångskartan MyScopeMap . Precis som i föregående exempel anger kommandot standardtokens status till enabled.

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

Utdata visar information om token. Som standard genereras två lösenord. Vi rekommenderar att du sparar lösenorden på en säker plats för senare autentisering. Lösenorden kan inte hämtas igen, men nya kan genereras.

Kommentar

Information om hur du återskapar tokenlösenord och förfalloperioder finns i Återskapa tokenlösenord senare i den här artikeln.

Så här använder du omfångskartor för att definiera och tilldela behörigheter för flera lagringsplatser

Med en omfångskarta kan ett jokertecken användas för att definiera och bevilja liknande behörigheter för flera lagringsplatser som delar ett gemensamt prefix. Lagringsplatser med specifika behörigheter, lagringsplatser med jokertecken kan också användas i samma omfångskarta. Detta ger flexibilitet när det gäller att hantera behörigheter för flera lagringsplatser i en enda omfångskarta.

Lagringsplatsens behörigheter kan skapas när en omfångskarta skapas och tilldelas till en token. Alternativt kan en token skapas och tilldelas direkt till en lagringsplats.

I följande exempel skapas en omfångskarta med jokertecken och tilldelas sedan till en 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

I följande exempel skapas en token med ett jokertecken.

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

Jokerteckenbehörigheterna är additiva, vilket innebär att när en specifik lagringsplats används innehåller de resulterande behörigheterna behörigheterna för alla omfångskartaregler som matchar jokerteckenprefixet.

I det här exemplet definierar omfångskartan behörigheter för tre olika typer av lagringsplatser:

Lagringsplats	Behörighet
`sample/*`	`content/read`
`sample/teamA/*`	`content/write`
`sample/teamA/projectB`	`content/delete`

Token tilldelas en omfångskarta för att bevilja [content/read, content/write, content/delete] behörigheter för åtkomst till lagringsplatsen sample/teamA/projectB. Men när samma token används för att komma åt sample/teamA/projectC lagringsplatsen har [content/read, content/write] den bara behörigheter.

Viktigt!

Lagringsplatser som använder jokertecken i omfångskartan bör alltid sluta med att ett /* suffix är giltigt och ha ett enda jokertecken i lagringsplatsens namn. Här är några exempel på ogiltiga jokertecken:

sample/*/teamA med ett jokertecken i mitten av lagringsplatsens namn.
sample/teamA* med ett jokertecken slutar inte med '/*'.
sample/teamA/*/projectB/* med flera jokertecken i lagringsplatsens namn.

Jokertecken på rotnivå

Jokertecken kan också tillämpas på rotnivå. Det innebär att alla behörigheter som har tilldelats till lagringsplatsen som definierats som *, tillämpas i hela registret.

Exemplet visar hur du skapar en token med ett jokertecken på rotnivå som ger tokenbehörighet [content/read, content/write] till alla lagringsplatser i registret. Detta ger ett enkelt sätt att bevilja behörigheter till alla lagringsplatser i registret utan att behöva ange varje lagringsplats individuellt.

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

Viktigt!

Om en jokerteckenregel omfattar en lagringsplats som ännu inte finns gäller jokerteckenregelns behörigheter fortfarande för lagringsplatsens namn. Till exempel en token som har tilldelats till en omfångskarta som beviljar [content/write, metadata/write] behörigheter för sample/* lagringsplatser. Anta dessutom att lagringsplatsen sample/teamC/teamCimage inte finns ännu. Token har behörighet att push-överföra avbildningar till lagringsplatsen sample/teamC/teamCimage, vilket samtidigt skapar lagringsplatsen vid lyckad push-överföring.

Skapa token – portalen

Du kan använda Azure-portalen för att skapa token och omfångskartor. Precis som med az acr token create CLI-kommandot kan du använda en befintlig omfångskarta eller skapa en omfångskarta när du skapar en token genom att ange en eller flera lagringsplatser och associerade åtgärder. Lagringsplatserna behöver inte finnas i registret än.

I följande exempel skapas en token och en omfångskarta skapas med följande behörigheter på lagringsplatsen samples/hello-world : content/write och content/read.

Gå till containerregistret i portalen.
Under Lagringsplatsens behörigheter väljer du Token + > Lägg till.
Ange ett tokennamn.
Under Omfångskarta väljer du Skapa ny.
Konfigurera omfångskartan:
1. Ange ett namn och en beskrivning för omfångskartan.
2. Under Lagringsplatser anger du samples/hello-worldoch under Behörigheter väljer du content/read och content/write. Välj sedan +Lägg till.
3. När du har lagt till lagringsplatser och behörigheter väljer du Lägg till för att lägga till omfångskartan.
Acceptera standardtoken Status för Aktiverad och välj sedan Skapa.

När token har verifierats och skapats visas tokeninformation på skärmen Tokens .

Lägga till tokenlösenord

Om du vill använda en token som skapats i portalen måste du generera ett lösenord. Du kan generera ett eller två lösenord och ange ett förfallodatum för var och en. Nya lösenord som skapats för token är tillgängliga omedelbart. Det tar 60 sekunder att replikera och vara tillgänglig om du återskapar nya lösenord för token.

Gå till containerregistret i portalen.
Under Lagringsplatsbehörigheter väljer du Tokens och väljer en token.
I tokeninformationen väljer du password1 eller password2 och väljer ikonen Generera.
På lösenordsskärmen kan du ange ett förfallodatum för lösenordet och välja Generera. Vi rekommenderar att du anger ett förfallodatum.
När du har genererat ett lösenord kopierar du och sparar det på en säker plats. Du kan inte hämta ett genererat lösenord när du har stängt skärmen, men du kan generera ett nytt.

Autentisera med token

När en användare eller tjänst använder en token för att autentisera med målregistret tillhandahåller den tokennamnet som användarnamn och ett av dess genererade lösenord.

Autentiseringsmetoden är beroende av den konfigurerade åtgärden eller åtgärderna som är associerade med token.

Åtgärd	Autentisera
`content/delete`	`az acr repository delete` i Azure CLI Exempel: `az acr repository delete --name myregistry --repository myrepo --username MyToken --password xxxxxxxxxx`
`content/read`	`docker login` `az acr login` i Azure CLI Exempel: `az acr login --name myregistry --username MyToken --password xxxxxxxxxx`
`content/write`	`docker login` `az acr login` i Azure CLI
`metadata/read`	`az acr repository show` `az acr repository show-tags` `az acr manifest list-metadata` i Azure CLI
`metadata/write`	`az acr repository untag` `az acr repository update` i Azure CLI

Exempel: Använd token

I följande exempel används token som skapades tidigare i den här artikeln för att utföra vanliga åtgärder på en lagringsplats: push- och pull-avbildningar, ta bort bilder och lista lagringsplatstaggar. Token konfigurerades ursprungligen med push-behörigheter (content/write och content/read åtgärder) på lagringsplatsen samples/hello-world .

Dra och tagga testbilder

I följande exempel hämtar du offentliga hello-world filer och nginx avbildningar från Microsoft Container Registry och taggar dem för ditt register och din lagringsplats.

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

Autentisera med token

Kör docker login eller az acr login autentisera med registret för att skicka eller hämta avbildningar. Ange tokennamnet som användarnamn och ange ett av dess lösenord. Token måste ha statusen Enabled .

Följande exempel är formaterat för bash-gränssnittet och innehåller värdena med hjälp av miljövariabler.

TOKEN_NAME=MyToken
TOKEN_PWD=<token password>

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

Utdata bör visa lyckad autentisering:

Login Succeeded

Push-överför avbildningar till registret

När inloggningen har slutförts försöker du skicka de taggade avbildningarna till registret. Eftersom token har behörighet att skicka avbildningar till samples/hello-world lagringsplatsen lyckas följande push-överföring:

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

Token har inte behörighet till samples/nginx lagringsplatsen, så följande push-försök misslyckas med ett fel som liknar requested access to the resource is denied:

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

Uppdatera tokenbehörigheter

Uppdatera behörigheterna för en token genom att uppdatera behörigheterna i den associerade omfångskartan. Den uppdaterade omfångskartan tillämpas omedelbart på alla associerade token.

Du kan till exempel uppdatera med och åtgärder på samples/ngnx lagringsplatsen och ta bort content/write åtgärden på lagringsplatsensamples/hello-world.content/readcontent/writeMyToken-scope-map

Om du vill använda Azure CLI kör du az acr scope-map update för att uppdatera omfångskartan:

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

I Azure-portalen:

Gå till containerregistret.
Under Lagringsplatsbehörigheter väljer du Omfångskartor och väljer den omfångskarta som ska uppdateras.
Under Lagringsplatser anger du samples/nginxoch under Behörigheter väljer du content/read och content/write. Välj sedan +Lägg till.
Under Lagringsplatser väljer du samples/hello-world och under Behörigheter avmarkerar du content/write. Välj sedan Spara.

När du har uppdaterat omfångskartan lyckas följande push-överföring:

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

Eftersom omfångskartan bara har behörigheten content/readsamples/hello-world på lagringsplatsen misslyckas nu ett push-försök till lagringsplatsen samples/hello-world :

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

Det går att hämta bilder från båda lagringsplatserna eftersom omfångskartan ger content/read behörigheter på båda lagringsplatserna:

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

Ta bort avbildningar

Uppdatera omfångskartan genom att lägga till åtgärden content/delete på lagringsplatsen nginx . Den här åtgärden tillåter borttagning av bilder på lagringsplatsen eller borttagning av hela lagringsplatsen.

För korthet visar vi bara kommandot az acr scope-map update för att uppdatera omfångskartan:

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

Information om hur du uppdaterar omfångskartan med hjälp av portalen finns i föregående avsnitt.

Använd följande az acr repository delete-kommando för att ta bort lagringsplatsen samples/nginx . Om du vill ta bort bilder eller lagringsplatser skickar du tokens namn och lösenord till kommandot. I följande exempel används miljövariablerna som skapades tidigare i artikeln:

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

Visa lagringsplatsens taggar

Uppdatera omfångskartan genom att lägga till åtgärden metadata/read på lagringsplatsen hello-world . Med den här åtgärden kan du läsa manifest- och taggdata på lagringsplatsen.

För korthet visar vi bara kommandot az acr scope-map update för att uppdatera omfångskartan:

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

Information om hur du uppdaterar omfångskartan med hjälp av portalen finns i föregående avsnitt.

Om du vill läsa metadata på lagringsplatsen kör du kommandot az acr manifest list-metadata eller az acr repository show-tags.samples/hello-world

Om du vill läsa metadata skickar du tokens namn och lösenord till något av kommandona. I följande exempel används miljövariablerna som skapades tidigare i artikeln:

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

Exempel på utdata:

[
  "v1"
]

Hantera token och omfångskartor

Lista omfångskartor

Använd kommandot az acr scope-map list eller skärmen Omfångskartor i portalen för att visa en lista över alla omfångskartor som konfigurerats i ett register. Till exempel:

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

Utdata består av de tre systemdefinierade omfångskartor och andra omfångskartor som genereras av dig. Token kan konfigureras med någon av dessa omfångskartor.

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

Visa tokeninformation

Om du vill visa information om en token, till exempel dess status och förfallodatum för lösenord, kör du kommandot az acr token show eller väljer token på skärmen Tokens i portalen. Till exempel:

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

Använd kommandot az acr token list eller skärmen Tokens i portalen för att visa en lista över alla token som konfigurerats i ett register. Till exempel:

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

Återskapa tokenlösenord

Om du inte har genererat ett tokenlösenord , eller om du vill generera nya lösenord, kör du kommandot az acr token credential generate . Det tar 60 sekunder att replikera och vara tillgänglig om du återskapar nya lösenord för token.

I följande exempel genereras ett nytt värde för password1 för MyToken-token med en giltighetstid på 30 dagar. Lösenordet lagras i miljövariabeln TOKEN_PWD. Det här exemplet är formaterat för bash-gränssnittet.

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

Information om hur du använder Azure-portalen för att generera ett tokenlösenord finns i stegen i Skapa token – portal tidigare i den här artikeln.

Uppdatera token med ny omfångskarta

Om du vill uppdatera en token med en annan omfångskarta kör du az acr token update och anger den nya omfångskartan. Till exempel:

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

I portalen går du till skärmen Tokens och väljer token. Under Omfångskarta väljer du en annan omfångskarta.

Dricks

När du har uppdaterat en token med en ny omfångskarta kanske du vill generera nya tokenlösenord. Använd kommandot az acr token credential generate eller återskapa ett tokenlösenord i Azure-portalen.

Inaktivera eller ta bort token

Du kan tillfälligt behöva inaktivera användningen av tokenautentiseringsuppgifterna för en användare eller tjänst.

Använd Azure CLI och kör kommandot az acr token update för att ange status till disabled:

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

I portalen väljer du token på skärmen Tokens och väljer Inaktiverad under Status.

Om du vill ta bort en token för att permanent ogiltigförklara åtkomsten för alla som använder dess autentiseringsuppgifter kör du kommandot az acr token delete .

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

I portalen väljer du token på skärmen Tokens och väljer Ignorera.

Nästa steg

Om du vill hantera omfångskartor och token använder du ytterligare kommandon i kommandogrupperna az acr scope-map och az acr token .
Se autentiseringsöversikten för andra alternativ för att autentisera med ett Azure-containerregister, inklusive att använda en Microsoft Entra-identitet, ett tjänsthuvudnamn eller ett administratörskonto.
Lär dig mer om anslutna register och hur du använder token för åtkomst.

Skapa en token med behörigheter med lagringsplatsomfattning

Begränsningar

Begrepp

Förutsättningar

Skapa token – CLI

Skapa token och ange lagringsplatser

Skapa token och ange omfångskarta

Så här använder du omfångskartor för att definiera och tilldela behörigheter för flera lagringsplatser

Jokertecken på rotnivå

Skapa token – portalen

Lägga till tokenlösenord

Autentisera med token

Exempel: Använd token

Dra och tagga testbilder

Autentisera med token

Push-överför avbildningar till registret

Uppdatera tokenbehörigheter

Ta bort avbildningar

Visa lagringsplatsens taggar

Hantera token och omfångskartor

Lista omfångskartor

Visa tokeninformation

Återskapa tokenlösenord

Uppdatera token med ny omfångskarta

Inaktivera eller ta bort token

Nästa steg

Ytterligare resurser