Creación de un token con permisos orientados al repositorio

En este artículo se describe cómo crear tokens y asignaciones de ámbito para administrar el acceso a los repositorios del registro de contenedor. Mediante la creación de tokens, los propietarios del registro pueden proporcionar a los usuarios o servicios acceso de tiempo limitado y orientado a los repositorios con el fin de extraer o insertar imágenes o de realizar otras acciones. Un token proporciona permisos más específicos que otras opciones de autenticación del registro, que limitan el ámbito de los permisos a un registro completo.

Entre los escenarios comunes para crear un token se incluyen:

• Permitir que los dispositivos IoT con tokens individuales extraen una imagen de un repositorio.
• Proporcione a una organización externa permisos para una ruta de acceso del repositorio.
• Limitar el acceso del repositorio a diferentes grupos de usuarios de la organización. Por ejemplo, proporcione acceso de lectura y escritura a los desarrolladores que compilan imágenes destinadas a repositorios específicos, y acceso de lectura a los equipos que realizan implementaciones desde estos repositorios.

Esta característica está disponible en todos los niveles de servicio. Para obtener información sobre los límites y los niveles de servicio de los registros, consulte Niveles de servicio de Azure Container Registry

Limitaciones

• Actualmente no se pueden asignar permisos con ámbito de repositorio a una identidad de Microsoft Entra, como una entidad de servicio o una identidad administrada.

Conceptos

Para configurar los permisos orientados al repositorio, debe crear un token con una asignación de ámbito asociada.

• Un token junto con una contraseña generada permiten al usuario autenticarse con el registro. Puede establecer una fecha de expiración para la contraseña del token o deshabilitar un token en cualquier momento.

  Después de autenticarse con un token, el usuario o el servicio pueden realizar una o varias acciones que tengan como ámbito uno o varios repositorios.

  Acción	Descripción	Ejemplo
  content/delete	Quitar datos del repositorio	Eliminar un repositorio o un manifiesto
  content/read	Leer datos del repositorio	Extracción de un artefacto
  content/write	Escribir datos en el repositorio	Úsela con content/read para insertar un artefacto.
  metadata/read	Leer metadatos del repositorio	Enumerar etiquetas o manifiestos
  metadata/write	Escribir metadatos en el repositorio	Habilitar o deshabilitar operaciones de lectura, escritura o eliminación

Nota:

Los permisos con ámbito de repositorio no admiten la capacidad de enumerar el catálogo de todos los repositorios del Registro.

• Un mapa de ámbito agrupa los permisos de repositorio que se aplican a un token y se puede volver a aplicar a otros tokens. Cada token está asociado con una única asignación de ámbito. Con un mapa de ámbito, puede hacer lo siguiente:

  • Configure varios tokens con permisos idénticos a un conjunto de repositorios.
  • Actualice los permisos de token al agregar o quitar acciones del repositorio en el mapa de ámbito o aplique otro mapa de ámbito.

  Azure Container Registry también proporciona varias asignaciones de ámbito definidas por el sistema que se pueden aplicar al crear tokens. Los permisos de las asignaciones de ámbito definidas por el sistema se aplican a todos los repositorios del registro. Las acciones individuales corresponden al límite de repositorios por asignación de ámbito.

En la imagen siguiente se muestra la relación entre los tokens y las asignaciones de ámbito.

Requisitos previos

• CLI de Azure: los ejemplos de comandos de la CLI de Azure de este artículo requieren la versión 2.17.0, o cualquier versión posterior de la CLI de Azure. Ejecute az --version para encontrar la versión. Si necesita instalarla o actualizarla, vea Instalación de la CLI de Azure.
• Docker: para autenticarse con el registro para insertar o extraer imágenes, necesita una instalación local de Docker. Docker ofrece instrucciones de instalación para sistemas macOS, Windows y Linux.
• Registro de contenedor: si no tiene uno, cree un registro de contenedor en la suscripción de Azure. Por ejemplo, use Azure Portal o la CLI de Azure.

Creación de un token: CLI

Creación de un token y especificación de los repositorios

Cree un token con el comando az acr token create. Al crear un token, puede especificar uno o varios repositorios y acciones asociadas en cada uno. No es necesario que los repositorios estén todavía en el registro. Para crear un token mediante la especificación de una asignación de ámbito existente, consulte la sección siguiente.

En el ejemplo siguiente se crea un token en el registro myregistry con los permisos siguientes en el repositorio samples/hello-world: content/write y content/read. De forma predeterminada, el comando establece el estado predeterminado del token en enabled, pero puede actualizarlo a disabled en cualquier momento.

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

La salida muestra detalles sobre el token. De forma predeterminada, se generan dos contraseñas que no expiran, pero también se puede establecer una fecha de expiración. Se recomienda guardar las contraseñas en un lugar seguro para usarlas más adelante para la autenticación. Las contraseñas no se pueden recuperar de nuevo, pero se pueden generar otras.

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

Para volver a generar contraseñas de token y períodos de expiración, consulte el apartado Regeneración de contraseñas de token de este mismo artículo.

La salida incluye detalles sobre la asignación de ámbito que creó el comando. Puede usar la asignación de ámbito, llamada aquí MyToken-scope-map, para aplicar las mismas acciones de repositorio a otros tokens. También, puede actualizar la asignación de ámbito más adelante para cambiar los permisos de los tokens asociados.

Creación de un token y especificación de la asignación de ámbito

Una manera alternativa de crear un token es especificar una asignación de ámbito existente. Si aún no tiene una asignación de ámbito, primero debe crear una especificando los repositorios y las acciones asociadas. Luego, especifique la asignación de ámbito al crear un token.

Para crear una asignación de ámbito, use el comando az acr scope-map create. El siguiente comando crea una asignación de ámbito con los mismos permisos en el repositorio samples/hello-world usado anteriormente.

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

Ejecute az acr token create para crear un token y especifique la asignación de ámbito MyScopeMap. Como en el ejemplo anterior, el comando establece el estado predeterminado del token en enabled.

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

La salida muestra detalles sobre el token. De manera predeterminada, se generan dos contraseñas. Se recomienda guardar las contraseñas en un lugar seguro para usarlas más adelante para la autenticación. Las contraseñas no se pueden recuperar de nuevo, pero se pueden generar otras.

Nota

Para volver a generar contraseñas de token y períodos de expiración, consulte el apartado Regeneración de contraseñas de token de este mismo artículo.

Uso de asignaciones de ámbito para definir y asignar permisos para varios repositorios

Un mapa de ámbito permite el uso de un carácter comodín para definir y conceder permisos similares para varios repositorios que comparten un prefijo común. Los repositorios con permisos específicos, los repositorios con un carácter comodín también se pueden usar en el mismo mapa de ámbito. Esto proporciona flexibilidad para administrar permisos para varios conjuntos de repositorios en un único mapa de ámbito.

Los permisos de repositorio se pueden crear cuando se crea un mapa de ámbito y se asignan a un token. Como alternativa, se puede crear un token y asignarse directamente a un repositorio.

En el ejemplo siguiente se crea un mapa de ámbito con un carácter comodín y, a continuación, se asigna 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

En el ejemplo siguiente se crea un token con un carácter comodín.

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

Los permisos comodín son aditivos, lo que significa que cuando se accede a un repositorio específico, los permisos resultantes incluirán los permisos para todas las reglas de mapa de ámbito que coinciden con el prefijo comodín.

En este ejemplo, el mapa de ámbito define los permisos para tres tipos diferentes de repositorios:

Repositorio	Permiso
sample/*	content/read
sample/teamA/*	content/write
sample/teamA/projectB	content/delete

Al token se le asigna un mapa de ámbito para conceder [content/read, content/write, content/delete] permisos para acceder al repositorio sample/teamA/projectB. Sin embargo, cuando se usa el mismo token para acceder al sample/teamA/projectC repositorio, solo tiene [content/read, content/write] permisos.

Importante

Los repositorios que usan caracteres comodín en el mapa de ámbito siempre deben terminar con un /* sufijo para que sea válido y tener un único carácter comodín en el nombre del repositorio. Estos son algunos ejemplos de caracteres comodín no válidos:

• sample/*/teamA con un carácter comodín en el centro del nombre del repositorio.
• sample/teamA* con un carácter comodín no termina con '/*'.
• sample/teamA/*/projectB/* con varios caracteres comodín en el nombre del repositorio.

Caracteres comodín de nivel raíz

Los caracteres comodín también se pueden aplicar en un nivel raíz. Esto significa que los permisos asignados al repositorio definido como *, se aplicarán en todo el registro.

En el ejemplo se muestra cómo crear un token con un carácter comodín de nivel raíz que concedería permisos de token [content/read, content/write] a todos los repositorios del registro. Esto proporciona una manera sencilla de conceder permisos a todos los repositorios del registro sin tener que especificar individualmente cada repositorio.

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

Importante

Si una regla de caracteres comodín abarca un repositorio que aún no existe, los permisos de la regla de caracteres comodín se seguirán aplicando a ese nombre de repositorio. Por ejemplo, un token asignado a un mapa de ámbito que concede [content/write, metadata/write] permisos para sample/* repositorios. Además, supongamos que el repositorio sample/teamC/teamCimage aún no existe. El token tendrá permisos para insertar imágenes en el repositorio sample/teamC/teamCimage, lo que creará simultáneamente el repositorio en una inserción correcta.

Creación de un token: portal

Puede usar Azure Portal para crear tokens y asignaciones de ámbito. Al igual que con el comando de la CLI az acr token create, puede aplicar una asignación de ámbito existente o crear una al crear un token mediante la especificación de uno o varios repositorios y acciones asociadas. No es necesario que los repositorios estén todavía en el registro.

En el ejemplo siguiente se crea un token y se crea una asignación de ámbito con los siguientes permisos en el repositorio samples/hello-world: content/write y content/read.

1. En el portal, vaya al registro de contenedor.

2. En Permisos del repositorio, seleccione Tokens > +Agregar.

   

3. Escriba un nombre de token.

4. En Asignación de ámbito, seleccione Crear nuevo.

5. Configure la asignación de ámbito:

   1. Escriba un nombre y una descripción para la asignación de ámbito.

   2. En Repositorios, escriba samples/hello-world y, en Permisos, seleccione content/read y content/write. Luego, seleccione +Agregar.

      

   3. Después de agregar los repositorios y los permisos, seleccione Agregar para agregar la asignación de ámbito.

6. Acepte el valor de Estado del token predeterminado de Habilitado y seleccione Crear.

Después de validar y crear el token, los detalles del token aparecen en la pantalla Tokens.

Adición de la contraseña del token

Para usar un token creado en el portal, debe generar una contraseña. Puede generar una o dos contraseñas y establecer una fecha de expiración para cada una de ellas. Las nuevas contraseñas creadas para los tokens están disponibles inmediatamente. La regeneración de contraseñas nuevas para tokens llevará 60 segundos en replicarse y estará disponible.

1. En el portal, vaya al registro de contenedor.

2. En Permisos del repositorio, seleccione Tokens y seleccione un token.

3. En los detalles del token, seleccione password1 o password2, y elija el icono Generar.

4. En la pantalla de contraseña, establezca opcionalmente una fecha de expiración para la contraseña y seleccione Generar. Se recomienda establecer una fecha de expiración.

5. Después de generar una contraseña, cópiela y guárdela en una ubicación segura. No se puede recuperar una contraseña generada después de cerrar la pantalla, pero se puede generar una nueva.

   

Autenticación con un token

Cuando un usuario o un servicio usan un token para autenticarse con registro de destino, se proporciona el nombre del token como un nombre de usuario y una de sus contraseñas generadas.

El método de autenticación depende de las acciones configuradas asociadas con el token.

Acción	Cómo autenticarse
content/delete	az acr repository delete en la CLI de Azure Ejemplo: az acr repository delete --name myregistry --repository myrepo --username MyToken --password xxxxxxxxxx
content/read	docker login az acr login en la CLI de Azure Ejemplo: az acr login --name myregistry --username MyToken --password xxxxxxxxxx
content/write	docker login az acr login en la CLI de Azure
metadata/read	az acr repository show az acr repository show-tags az acr manifest list-metadata en la CLI de Azure
metadata/write	az acr repository untag az acr repository update en la CLI de Azure

Ejemplos: Uso del token

En los siguientes ejemplos se usa el token creado anteriormente en este artículo para realizar operaciones comunes en un repositorio: insertar y extraer imágenes, eliminar imágenes y mostrar etiquetas del repositorio. El token se configuró inicialmente con permisos de extracción (acciones content/write y content/read) en el repositorio samples/hello-world.

Inserción y etiquetado de imágenes de prueba

En los siguientes ejemplos, extraiga las imágenes hello-world y nginx públicas de Microsoft Container Registry y etiquételas para su registro y repositorio.

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

Autenticación mediante el token

Ejecute docker login o az acr login para autenticarse con el registro para insertar o extraer imágenes. Proporcione el nombre del token como el nombre de usuario y proporcione una de sus contraseñas. El token debe tener el estado Enabled.

El siguiente ejemplo tiene el formato para el shell de Bash y se proporcionan los valores mediante variables de entorno.

TOKEN_NAME=MyToken
TOKEN_PWD=<token password>

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

La salida debería mostrar la autenticación correcta:

Login Succeeded

Inserción de imágenes en el registro

Después iniciar sesión correctamente, intente insertar las imágenes etiquetadas en el registro. Como el token tiene permisos para insertar imágenes en el repositorio samples/hello-world, la siguiente operación de inserción se realiza correctamente:

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

El token no tiene permisos para el repositorio samples/nginx, así que el siguiente intento de inserción produce un error similar a requested access to the resource is denied:

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

Actualización de permisos de token

Para actualizar los permisos de un token, actualice los permisos en la asignación de ámbito asociada. La asignación de ámbito actualizada se aplica inmediatamente a todos los tokens asociados.

Por ejemplo, actualice MyToken-scope-map con acciones content/write y content/read en el repositorio samples/ngnx, y elimine la acción content/write en el repositorio samples/hello-world.

Para usar la CLI de Azure, ejecute az acr scope-map update para actualizar la asignación de ámbito:

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

En Azure Portal:

1. Vaya al registro de contenedor.
2. En Permisos del repositorio, seleccione Asignaciones de ámbito y seleccione la asignación de ámbito que se va a actualizar.
3. En Repositorios, escriba samples/nginx y, en Permisos, seleccione content/read y content/write. Luego, seleccione +Agregar.
4. En Repositorios, seleccione samples/hello-world y, en Permisos, anule la selección de content/write. Después, seleccione Guardar.

Después de actualizar la asignación de ámbito, la siguiente inserción se realiza correctamente:

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

Dado que la asignación de ámbito solo tiene el permiso content/read en el repositorio samples/hello-world, el intento de inserción en el repositorio samples/hello-world ahora genera un error:

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

La extracción de imágenes de ambos repositorios se realiza correctamente, porque la asignación de ámbito proporciona permisos content/read en ambos repositorios:

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

Eliminación de imágenes

Para actualizar la asignación de ámbito, agregue la acción content/delete al repositorio nginx. Esta acción permite la eliminación de imágenes en el repositorio o la eliminación de todo el repositorio.

Por motivos de brevedad, solo se muestra el comando az acr scope-map update para actualizar la asignación de ámbito:

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

Para actualizar la asignación de ámbito mediante el portal, consulte la sección anterior.

Use el siguiente comando az acr repository delete para eliminar el repositorio samples/nginx. Para eliminar las imágenes o los repositorios, pase el nombre y la contraseña del token al comando. En el ejemplo siguiente se usan las variables de entorno creadas anteriormente en el artículo:

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

Presentación de las etiquetas de repositorio

Para actualizar la asignación de ámbito, agregue la acción metadata/read al repositorio hello-world. Esta acción permite leer los datos de manifiesto y etiqueta en el repositorio.

Por motivos de brevedad, solo se muestra el comando az acr scope-map update para actualizar la asignación de ámbito:

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

Para actualizar la asignación de ámbito mediante el portal, consulte la sección anterior.

Para leer los metadatos del repositorio samples/hello-world, ejecute el comando az acr manifest list-metadata o az acr repository show-tags.

Para leer los metadatos, pase el nombre y la contraseña del token a cualquiera de los comandos. En el ejemplo siguiente se usan las variables de entorno creadas anteriormente en el artículo:

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

Salida del ejemplo:

[
  "v1"
]

Administración de tokens y asignaciones de ámbito

Presentación de asignaciones de ámbito

Use el comando az acr scope-map list o la pantalla Asignaciones de ámbito en el portal para mostrar todas las asignaciones de ámbito configuradas en un registro. Por ejemplo:

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

La salida consta de las tres asignaciones de ámbito definidas por el sistema y otras asignaciones generadas por el usuario. Los tokens se pueden configurar con cualquiera de estas asignaciones de ámbito.

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

Presentación de los detalles del token

Para ver los detalles de un token, como su estado o las fechas de expiración de la contraseña, ejecute el comando az acr token show o seleccione el token en la pantalla Tokens en el portal. Por ejemplo:

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

Use el comando az acr token list o la pantalla Tokens en el portal para mostrar todos los tokens configurados en un Registro. Por ejemplo:

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

Regeneración de contraseñas de token

Si no generó una contraseña de token o quiere generar otras nuevas, ejecute el comando az acr token credential generate. La regeneración de contraseñas nuevas para tokens llevará 60 segundos en replicarse y estará disponible.

En el ejemplo siguiente se genera un nuevo valor para password1 para el token MyToken, con un período de expiración de 30 días. La contraseña se almacena en la variable de entorno TOKEN_PWD. El fragmento de código tiene el formato para el shell de Bash.

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

Para usar Azure Portal para generar una contraseña de token, consulte los pasos descritos en Creación de un token: portal anteriormente en este artículo.

Actualización de un token con una nueva asignación de ámbito

Si quiere actualizar un token con una asignación de ámbito diferente, ejecute az acr token update y especifique la nueva asignación de ámbito. Por ejemplo:

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

En el portal, en la pantalla Tokens, seleccione el token y, en Asignación de ámbito, seleccione una asignación de ámbito diferente.

Sugerencia

Después de actualizar un token con una nueva asignación de ámbito, podría querer generar nuevas contraseñas de token. Use el comando az acr token credential generate o vuelva a generar una contraseña de token en Azure Portal.

Deshabilitación o eliminación de un token

Puede que tenga que deshabilitar temporalmente el uso de las credenciales de token para un usuario o un servicio.

Mediante la CLI de Azure, ejecute el comando az acr token update para establecer status en disabled:

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

En el portal, seleccione el token en la pantalla Tokens y, en Estado, seleccione Deshabilitado.

Para eliminar un token a fin de invalidar de forma permanente el acceso por parte de cualquiera que use sus credenciales, ejecute el comando az acr token delete.

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

En el portal, seleccione el token en la pantalla Tokens y elija Descartar.

Pasos siguientes

• Para administrar asignaciones de ámbito y tokens, use otros comandos de los grupos de comandos az acr scope-map y az acr token.
• Consulte la información general sobre la autenticación para conocer otras opciones para autenticarse con un registro de contenedor de Azure, como el uso de una identidad de Microsoft Entra, una entidad de servicio o una cuenta de administrador.
• Obtenga información sobre los registros conectados y el uso de tokens para el acceso.