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 spécifiques 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 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 référentiel spécifique
  • 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 uniquement au niveau de service Premium de registre de conteneurs. Pour plus d’informations sur les niveaux de service et les limites de registre, consultez Niveaux de service d’Azure Container Registry.

Important

Cette fonctionnalité est actuellement en préversion et certaines limitations s’appliquent. Les préversions sont à votre disposition, à condition que vous acceptiez les conditions d’utilisation supplémentaires. Certains aspects de cette fonctionnalité sont susceptibles d’être modifiés avant la mise à disposition générale.

Limitations de la version préliminaire

  • Vous ne pouvez pas actuellement attribuer des autorisations délimites par le référentiel à une identité Azure Active Directory telle qu’un principal de service ou une identité managée.
  • Vous ne pouvez pas créer de mappage d’étendue dans un registre activé pour l’accès en extraction anonyme.

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 :

    • 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 appliquer 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.

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

Jetons de registre et 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 Premium dans votre abonnement Azure si vous n’en avez pas ou mettez à niveau un registre existant. 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"

Notes

Pour régénérer les mots de passe des jetons et les périodes d’expiration, consultez Régénérer les mots de passe de jeton plus loin dans cet article.

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.

Notes

Pour régénérer les mots de passe des jetons et les périodes d’expiration, consultez Régénérer les mots de passe de jeton plus loin dans cet article.

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 (préversion) > +Ajouter.

    Créer un jeton dans le portail

  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).

      Créer un mappage d’étendue dans le portail

    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.

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

  2. Sous Autorisations du référentiel, sélectionnez Jetons (préversion) et sélectionnez 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.

    Créer un mot de passe de jeton dans le portail

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.

Action Comment s’authentifier
content/delete az acr repository delete dans Azure CLI

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

az acr login dans Azure CLI

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

az acr login dans Azure CLI
metadata/read az acr repository show

az acr repository show-tags

az acr repository show-manifests dans Azure CLI
metadata/write az acr repository untag

az acr repository update dans Azure CLI

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 de référentiel, sélectionnez Mappages d’étendues (préversion) s, 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érentiel samples/hello-world, exécutez la commande az acr repository show-manifests 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 (Preview) [Mappages d’étendue (préversion)] 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 de ses mots de passe, exécutez la commande az acr token show ou sélectionnez le jeton dans l’écran Tokens (Preview) [Jetons (préversion)] 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 (Preview) [Jetons (préversion)] 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.

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

Sur le portail, dans l’écran Tokens (preview) [Jetons (préversion)], sélectionnez le jeton, puis sous Scope map (Mappage d’étendue), sélectionnez un autre mappage d’étendue.

Conseil

Après la mise à jour d’un jeton avec un nouveau mappage d’étendue, vous souhaiterez peut-être générer de nouveaux mots de passe de jeton. Utilisez la commande az acr token credential generate ou régénérez un mot de passe de jeton dans le Portail Azure.

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 dans l’écran Tokens (Preview) [Jetons (préversion)], 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 dans l’écran Tokens (Preview) [Jetons (préversion)], 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é Azure Active Directory, d’un principal de service ou d’un compte administrateur.