Créer un jeton avec des autorisations délimitées par le référentiel

Cet article explique comment créer des jetons et des mappages d’étendue pour gérer l’accès à des référentiels dans votre registre de conteneurs. En créant des jetons, le propriétaire du registre peut fournir aux utilisateurs ou aux services un accès étendu et limité dans le temps aux référentiels pour tirer (pull) ou envoyer (push) des images ou effectuer d’autres actions. Un jeton fournit des autorisations plus précises que les autres options d’authentification du registre, qui délimitent les autorisations à un registre entier.

Les scénarios courants de création d’un jeton sont les suivants :

• Autoriser les appareils IoT dotés de jetons individuels pour tirer (pull) une image d’un référentiel.
• Fournir à une organisation externe des autorisations sur un chemin d'accès au référentiel.
• Limiter l’accès au référentiel à différents groupes d’utilisateurs de votre organisation. Par exemple, fournissez un accès en écriture et en lecture aux développeurs qui génèrent des images ciblant des référentiels spécifiques, ainsi qu’un accès en lecture aux équipes qui déploient à partir de ces référentiels.

Cette fonctionnalité est disponible à tous les niveaux de service. Si vous souhaitez en savoir plus, sur les niveaux de service de registre et les limites, veuillez consulter la rubrique Niveaux de service d’Azure Container Registry

Limites

• Vous ne pouvez pas actuellement attribuer des autorisations délimitées par le référentiel à une identité Microsoft Entra telle qu’un principal de service ou une identité managée.

Concepts

Pour configurer des autorisations délimitées par le référentiel, vous créez un jeton avec un mappage d’étendue associé.

• Un jeton accompagné d’un mot de passe généré permet à l’utilisateur de s’authentifier auprès du registre. Vous pouvez définir une date d’expiration pour un mot de passe de jeton ou désactiver un jeton à tout moment.

  Après l’authentification à l’aide d’un jeton, l’utilisateur ou le service peut effectuer une ou plusieurs actions délimitées par un ou plusieurs référentiels.

  Action	Description	Exemple
  content/delete	Supprimer des données du référentiel	Supprimer un référentiel ou un manifeste
  content/read	Lire des données du référentiel	Tirer (pull) un artefact
  content/write	Écrire des données dans le référentiel	Utiliser avec content/read pour envoyer (push) un artefact
  metadata/read	Lire des métadonnées du référentiel	Répertorier des balises ou des manifestes
  metadata/write	Écrire des métadonnées dans le référentiel	Activer ou désactiver les opérations de lecture, d’écriture ou de suppression

• Un mappage d’étendue regroupe les autorisations de référentiel que vous appliquez à un jeton et peut s’appliquer à nouveau à d’autres jetons. Chaque jeton est associé à un mappage d’étendue unique. Avec un mappage d’étendue, vous pouvez :

  • Configurer plusieurs jetons avec des autorisations identiques sur un ensemble de référentiels.
  • Mettre à jour les autorisations de jeton lorsque vous ajoutez ou supprimez des actions de référentiel dans le mappage d’étendue, ou appliquez un autre mappage d’étendue.

  Azure Container Registry fournit également des mappages d’étendues définis par le système que vous pouvez appliquer lors de la création de jetons. Les autorisations des mappages d’étendues définis par le système s’appliquent à tous les référentiels de votre registre. Les actions individuelles correspondent à la limite des référentiels par mappage d’étendue.

L’image suivante illustre la relation entre les jetons et les mappages d’étendue.

Prérequis

• Azure CLI : les exemples de commandes Azure CLI de cet article nécessitent Azure CLI version 2.17.0 ou ultérieure. Exécutez az --version pour trouver la version. Si vous devez installer ou mettre à niveau, voir Installer Azure CLI.
• Docker : pour vous authentifier auprès du registre afin de tirer (pull) ou d’envoyer (push) des images, vous avez besoin d’une installation locale de Docker. Docker fournit des instructions d’installation pour les systèmes macOS, Windows et Linux.
• Registre de conteneurs : créez un registre de conteneurs dans votre abonnement Azur, si vous n’en avez pas. Par exemple, utilisez le portail Azure ou Azure CLI.

Créer un jeton – CLI

Créer un jeton et spécifier des référentiels

Créez un jeton à l’aide de la commande az acr token create. Lorsque vous créez un jeton, vous pouvez spécifier un ou plusieurs référentiels et actions associées sur chaque référentiel. Il n’est pas nécessaire que les référentiels soient déjà dans le registre de conteneurs. Pour créer un jeton en spécifiant un mappage d’étendues existant, consultez la section suivante.

L’exemple suivant crée un jeton dans le registre myregistry avec les autorisations suivantes sur le référentiel samples/hello-world : content/write et content/read. Par défaut, la commande définit l’état du jeton sur enabled par défaut, mais vous pouvez mettre à jour l’état sur disabled à tout moment.

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

La sortie affiche des détails sur le jeton. Par défaut, deux mots de passe qui n’expirent pas sont générés, mais vous pouvez également définir une date d’expiration. Il est recommandé d’enregistrer les mots de passe dans un endroit sûr pour les utiliser ultérieurement à des fins d’authentification. Les mots de passe ne peuvent pas être récupérés à nouveau, mais d’autres peuvent être générés.

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

La sortie contient des détails sur le mappage d’étendue que la commande a créé. Vous pouvez utiliser le mappage d’étendue, nommé ici MyToken-scope-map, pour appliquer les mêmes actions de référentiel à d’autres jetons. Ou mettez à jour le mappage d’étendue ultérieurement pour modifier les autorisations des jetons associés.

Créer un jeton et spécifier le mappage d’étendue

Une autre façon de créer un jeton consiste à spécifier un mappage d’étendue existant. Si vous n’avez pas encore de mappage d’étendue, commencez par en créer un en spécifiant des référentiels et des actions associées. Ensuite, spécifiez le mappage d’étendue lors de la création d’un jeton.

Pour créer un mappage d’étendue, utilisez la commande az acr scope-map create. La commande suivante crée un mappage d’étendue avec les mêmes autorisations que celles du référentiel samples/hello-world utilisé précédemment.

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

Exécutez la commande az acr token create pour créer un jeton, en spécifiant le mappage d’étendue MyScopeMap. Comme dans l’exemple précédent, la commande définit l’état du jeton sur enabled par défaut.

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

La sortie affiche des détails sur le jeton. Par défaut, deux mots de passe sont générés. Il est recommandé d’enregistrer les mots de passe dans un endroit sûr pour les utiliser ultérieurement à des fins d’authentification. Les mots de passe ne peuvent pas être récupérés à nouveau, mais d’autres peuvent être générés.

Guide pratique pour utiliser des mappages d’étendue pour définir et attribuer des autorisations pour plusieurs référentiels

Un mappage d’étendue permet d’utiliser un caractère générique pour définir et accorder des autorisations similaires pour plusieurs référentiels qui partagent un préfixe commun. Les référentiels disposant d’autorisations spécifiques, les référentiels avec un caractère générique peuvent également être utilisés dans le même mappage d’étendue. Cela offre une flexibilité de gestion des autorisations pour un ensemble multiple de référentiels dans un seul mappage d’étendue.

Les autorisations de référentiel peuvent être créées lorsqu’un mappage d’étendue est créé et affecté à un jeton. Vous pouvez également créer et affecter directement un jeton à un référentiel.

L’exemple suivant crée un mappage d’étendue avec un caractère générique, puis l’affecte à un jeton.

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

L’exemple suivant crée un jeton avec un caractère générique.

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

Les autorisations génériques sont additives, ce qui signifie que lorsqu’un référentiel spécifique est accessible, les autorisations obtenues incluent les autorisations pour toutes les règles de mappage d’étendue qui correspondent au préfixe générique.

Dans cet exemple, le mappage d’étendue définit les autorisations pour trois types de référentiels différents :

Le jeton est affecté à un mappage d’étendue pour accorder des autorisations [content/read, content/write, content/delete] pour l’accès au référentiel sample/teamA/projectB. Toutefois, lorsque le même jeton est utilisé pour accéder au référentiel sample/teamA/projectC, il dispose uniquement d’autorisations [content/read, content/write].

Caractères génériques au niveau racine

Les caractères génériques peuvent également être appliqués au niveau racine. Cela signifie que toutes les autorisations affectées au référentiel défini comme *, seront appliquées à l’échelle du registre.

L’exemple montre comment créer un jeton avec un caractère générique de niveau racine qui accorderait les autorisations de jeton [content/read, content/write] à tous les référentiels du registre. Cela offre un moyen simple d’accorder des autorisations à tous les référentiels du registre sans avoir à spécifier chaque référentiel individuellement.

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

Créer un jeton – Portail

Vous pouvez utiliser le Portail Azure pour créer des jetons et des mappages d’étendue. Comme avec la commande CLI az acr token create, vous pouvez appliquer un mappage d’étendue existant ou en créer un lorsque vous créez un jeton en spécifiant un ou plusieurs référentiels et actions associées. Il n’est pas nécessaire que les référentiels soient déjà dans le registre de conteneurs.

L’exemple suivant crée un jeton, puis crée un mappage d’étendue avec les autorisations suivantes sur le référentiel samples/hello-world : content/write et content/read.

1. Dans le portail, accédez à votre registre de conteneurs.

2. Sous Autorisations du référentiel, sélectionnez Jetons > +Ajouter.

   

3. Entrez un nom de jeton.

4. Sous Scope map (Mappage d’étendue), sélectionnez Create new (Créer).

5. Configurer le mappage d’étendue :

   1. Entrez un nom et une description pour le mappage d’étendue.

   2. Sous Repositories (Référentiels), entrez samples/hello-world et, sous Permissions (Autorisations), sélectionnez content/read et content/write. Sélectionnez ensuite +Add (+Ajouter).

      

   3. Après avoir ajouté des référentiels et des autorisations, sélectionnez Add (Ajouter) pour ajouter le mappage d’étendue.

6. Acceptez le Status (État) par défaut Enabled (Activé) du jeton, puis sélectionnez Create (Créer).

Une fois le jeton validé et créé, les détails du jeton s’affichent dans l’écran Tokens (Jetons).

Ajouter un mot de passe de jeton

Pour utiliser un jeton créé dans le portail, vous devez générer un mot de passe. Vous pouvez générer un ou deux mots de passe et définir une date d’expiration pour chacun d’entre eux. Les nouveaux mots de passe créés pour les jetons sont immédiatement disponibles. Il faut compter 60 secondes pour que les mots de passe des jetons soient répliqués et deviennent disponibles suite à leur régénération.

1. Dans le portail, accédez à votre registre de conteneurs.

2. Sous Autorisations du référentiel, sélectionnez Jetons et sélectionnez un jeton.

3. Dans les détails du jeton, sélectionnez password1 ou password2, puis sélectionnez l’icône de génération.

4. Dans l’écran du mot de passe, définissez éventuellement une date d’expiration pour le mot de passe, puis sélectionnez Generate (Générer). Il est recommandé de définir une date d’expiration.

5. Après avoir généré un mot de passe, copiez-le et enregistrez-le dans un emplacement sûr. Vous ne pouvez pas récupérer un mot de passe généré après avoir fermé l’écran, mais vous pouvez en générer un nouveau.

   

S’authentifier avec un jeton

Lorsqu’un utilisateur ou un service utilise un jeton pour s’authentifier auprès du registre cible, il fournit le nom du jeton comme nom d’utilisateur et l’un de ses mots de passe générés.

La méthode d’authentification utilisée dépend des actions configurées associées au jeton.

Exemples : Utiliser un jeton

Les exemples suivants utilisent le jeton créé plus haut dans cet article pour effectuer des opérations courantes sur un référentiel : envoyer (push) et tirer (pull) des images, supprimer des images et répertorier des balises de référentiel. Le jeton a été configuré initialement avec des autorisations d’envoi (push) [actions content/write et content/read] sur le référentiel samples/hello-world.

Tirer (pull) et baliser des images de test

Pour les exemples suivants, tirez (pull) les images publiques hello-world et nginx de Microsoft Container Registry, puis balisez-les pour votre registre et votre référentiel.

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

Authentifier à l'aide du jeton

Exécutez docker login ou az acr login pour vous authentifier auprès du registre afin d’envoyer (push) ou de tirer (pull) des images. Entrez le nom du jeton en tant que nom d’utilisateur et fournissez l’un de ses mots de passe. Le jeton doit avoir l’état Enabled.

L’exemple suivant est mis en forme pour l’interpréteur de commandes Bash et fournit les valeurs à l’aide de variables d’environnement.

TOKEN_NAME=MyToken
TOKEN_PWD=<token password>

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

La sortie doit afficher l’authentification réussie :

Login Succeeded

Envoyer des images au registre

Une fois la connexion établie, tentez d’envoyer (push) les images balisées dans le registre. Étant donné que le jeton dispose d’autorisations pour envoyer (push) des images vers le référentiel samples/hello-world, l’envoi (push) suivant fonctionne :

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

Le jeton ne dispose pas des autorisations d’accès au samples/nginx. Par conséquent, la tentative d’envoi (push) suivant échoue avec une erreur semblable à requested access to the resource is denied :

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

Mettre à jour des autorisations de jeton

Pour mettre à jour les autorisations d’un jeton, mettez à jour les autorisations dans le mappage d’étendue associé. Le mappage d’étendue mis à jour est appliqué immédiatement à tous les jetons associés.

Par exemple, mettez à jour MyToken-scope-map avec les actions content/write et content/read sur le référentiel samples/ngnx, et supprimez l’action content/write sur le référentiel samples/hello-world.

Pour utiliser Azure CLI, exécutez az acr scope-map update pour mettre à jour le mappage d’étendue :

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

Dans le portail Azure :

1. Accédez à votre registre de conteneurs.
2. Sous Autorisations du référentiel, sélectionnez Mappages d’étendues, puis sélectionnez le mappage d’étendue à mettre à jour.
3. Sous Repositories (Référentiels), entrez samples/nginx et, sous Permissions (Autorisations), sélectionnez content/read et content/write. Sélectionnez ensuite +Add (+Ajouter).
4. Sous Repositories (Référentiels), sélectionnez samples/hello-world et, sous Permissions (Autorisations), désélectionnez content/write. Ensuite, sélectionnez Enregistrer.

Après la mise à jour du mappage d’étendue, l’envoi (push) suivant est réussi :

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

Étant donné que le mappage d’étendue dispose uniquement de l’autorisation content/read sur le référentiel samples/hello-world, une tentative d’envoi (push) vers le référentiel samples/hello-world échoue désormais :

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

L’extraction d’images des deux pensions est réussie, car le mappage d’étendue fournit des autorisations content/read sur les deux référentiels :

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

Supprimer des images

Mettez à jour le mappage d’étendue en ajoutant l’action content/delete au référentiel nginx. Cette action permet de supprimer des images dans le référentiel ou de supprimer l’intégralité du référentiel.

Par souci de concision, nous affichons uniquement la commande az acr scope-map update pour mettre à jour le mappage d’étendue :

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

Pour mettre à jour le mappage d’étendues à l’aide du portail, consultez la section précédente.

Utilisez la commande az acr repository delete suivante pour supprimer le référentiel samples/nginx. Pour supprimer des images ou des référentiels, transmettez le nom et le mot de passe du jeton à la commande. L’exemple suivant utilise les variables d’environnement créées plus haut dans l’article :

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

Afficher les balises de référentiel

Mettez à jour le mappage d’étendue en ajoutant l’action metadata/read au référentiel hello-world. Cette action permet de lire les données de manifeste et de balise dans le référentiel.

Par souci de concision, nous affichons uniquement la commande az acr scope-map update pour mettre à jour le mappage d’étendue :

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

Pour mettre à jour le mappage d’étendues à l’aide du portail, consultez la section précédente.

Pour lire les métadonnées dans le référentielsamples/hello-world, exécutez la commande az acr manifest list-metadata ou az acr repository show-tags.

Pour lire des métadonnées, transmettez le nom et le mot de passe du jeton à l’une ou l’autre des commandes. L’exemple suivant utilise les variables d’environnement créées plus haut dans l’article :

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

Exemple de sortie :

[
  "v1"
]

Gérer les jetons et les mappages d’étendue

Répertorier les mappages d’étendue

Utilisez la commande az acr scope-map list ou l’écran Scope maps (Mappages d’étendue) dans le portail pour répertorier tous les mappages d’étendue configurés dans un registre. Par exemple :

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

La sortie se compose des trois mappages d’étendues définis par le système et d’autres mappages d’étendues générés par vous. Les jetons peuvent être configurés avec l’un de ces mappages d’étendues.

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

Afficher les détails du jeton

Pour afficher les détails d’un jeton, tels que son état et les dates d’expiration des mots de passe, exécutez la commande az acr token show ou sélectionnez le jeton sur l’écran Tokens (Jetons) dans le portail. Par exemple :

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

Utilisez la commande az acr token list ou l’écran Tokens (Jetons) dans le portail pour répertorier tous les jetons configurés dans un registre. Par exemple :

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

Régénérer les mots de passe des jetons

Si vous n’avez pas généré de mot de passe de jeton ou si vous souhaitez générer de nouveaux mots de passe, exécutez la commande az acr token credential generate. Il faut compter 60 secondes pour que les mots de passe des jetons soient répliqués et deviennent disponibles suite à leur régénération.

L’exemple suivant génère une nouvelle valeur password1 pour le jeton MyToken, avec une période d’expiration de 30 jours. Cela stocke le mot de passe dans la variable d’environnement TOKEN_PWD. Cet exemple est mis en forme pour l’interpréteur de commandes Bash.

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

Pour utiliser le Portail Azure afin de générer un mot de passe de jeton, consultez les étapes décrites dans Créer un jeton – Portail plus haut dans cet article.

Mettre à jour le jeton avec le nouveau mappage d’étendue

Si vous souhaitez mettre à jour un jeton avec un mappage d’étendue différent, exécutez la commande az acr token update et spécifiez le nouveau mappage d’étendue. Par exemple :

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

Dans le portail, sur l’écran Tokens (Jetons), sélectionnez le jeton, puis sous Scope map (Mappage d’étendue), sélectionnez un autre mappage d’étendue.

Désactiver ou supprimer un jeton

Vous devrez peut-être désactiver temporairement l’utilisation des informations d’identification du jeton pour un utilisateur ou un service.

À l’aide d’Azure CLI, exécutez la commande az acr token update pour définir le paramètre status sur disabled :

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

Dans le portail, sélectionnez le jeton sur l’écran Tokens (Jetons), puis sélectionnez Disabled (Désactivé) sous Status (État).

Pour supprimer un jeton afin d’invalider l’accès de manière permanente pour toute personne utilisant ses informations d’identification, exécutez la commande az acr token delete.

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

Dans le portail, sélectionnez le jeton sur l’écran Tokens (Jetons), puis sélectionnez Discard (Abandonner).

Étapes suivantes

• Pour gérer les mappages d’étendue et les jetons, utilisez des commandes supplémentaires dans les groupes de commande az acr scope-map et az acr token.
• Consultez la page de présentation de l’authentification pour obtenir d’autres options d’authentification avec un registre de conteneurs Azure, notamment à l’aide d’une identité Microsoft Entra, d’un principal de service ou d’un compte administrateur.
• Découvrez-en plus sur les registres connectés et l’utilisation de jetons pour l’accès.