Criar um token com permissões com escopo de repositório

  • Artigo

Este artigo descreve como criar tokens e mapas de escopo para gerenciar o acesso a repositórios em seu registro de contêiner. Ao criar tokens, um proprietário de registro pode fornecer aos usuários ou serviços acesso com escopo e tempo limitado a repositórios para extrair ou enviar imagens ou executar outras ações. Um token fornece permissões mais refinadas do que outras opções de autenticação do Registro, que abrangem permissões para um registro inteiro.

Os cenários comuns para a criação de um token incluem:

  • Permita que dispositivos IoT com tokens individuais extraiam uma imagem de um repositório.
  • Forneça a uma organização externa permissões para um caminho de repositório.
  • Limite o acesso ao repositório a diferentes grupos de usuários em sua organização. Por exemplo, forneça acesso de gravação e leitura para desenvolvedores que criam imagens destinadas a repositórios específicos e acesso de leitura a equipes que implantam a partir desses repositórios.

Esse recurso está disponível em todas as camadas de serviço. Para obter informações sobre camadas e limites de serviço do Registro, consulte Camadas de serviço do Registro de Contêiner do Azure

Limitações

  • No momento, não é possível atribuir permissões com escopo de repositório a uma identidade do Microsoft Entra, como uma entidade de serviço ou identidade gerenciada.

Conceitos

Para configurar permissões com escopo de repositório, crie um token com um mapa de escopo associado.

  • Um token junto com uma senha gerada permite que o usuário se autentique com o registro. Você pode definir uma data de expiração para uma senha de token ou desabilitar um token a qualquer momento.

    Depois de autenticar com um token, o usuário ou serviço pode executar uma ou mais ações com escopo para um ou mais repositórios.

    Ação Descrição Exemplo
    content/delete Remover dados do repositório Excluir um repositório ou um manifesto
    content/read Ler dados do repositório Puxe um artefato
    content/write Gravar dados no repositório Use com content/read para empurrar um artefato
    metadata/read Ler metadados do repositório Listar tags ou manifestos
    metadata/write Gravar metadados no repositório Habilitar ou desabilitar operações de leitura, gravação ou exclusão

Nota

As permissões com escopo de repositório não suportam a capacidade de listar o catálogo de todos os repositórios no Registro.

  • Um mapa de escopo agrupa as permissões de repositório que você aplica a um token e pode reaplicar a outros tokens. Cada token está associado a um único mapa de escopo. Com um mapa de escopo, você pode:

    • Configure vários tokens com permissões idênticas para um conjunto de repositórios.
    • Atualize as permissões de token ao adicionar ou remover ações do repositório no mapa de escopo ou aplique um mapa de escopo diferente.

    O Registro de Contêiner do Azure também fornece vários mapas de escopo definidos pelo sistema que você pode aplicar ao criar tokens. As permissões dos mapas de escopo definidos pelo sistema aplicam-se a todos os repositórios no seu registro. As ações individuais correspondem ao limite de Repositórios por mapa de escopo.

A imagem a seguir mostra a relação entre tokens e mapas de escopo.

Registry tokens and scope maps

Pré-requisitos

  • Azure CLI - Os exemplos de comando da CLI do Azure neste artigo exigem a CLI do Azure versão 2.17.0 ou posterior. Executar az --version para localizar a versão. Se precisar de instalar ou atualizar, veja Install Azure CLI (Instalar o Azure CLI).
  • Docker - Para autenticar com o registro para extrair ou enviar imagens, você precisa de uma instalação local do Docker . O Docker fornece instruções de instalação para os sistemas macOS, Windows e Linux.
  • Registro de contêiner - Se você não tiver um, crie um registro de contêiner em sua assinatura do Azure. Por exemplo, use o portal do Azure ou a CLI do Azure.

Criar token - CLI

Criar token e especificar repositórios

Crie um token usando o comando az acr token create . Ao criar um token, você pode especificar um ou mais repositórios e ações associadas em cada repositório. Os repositórios ainda não precisam estar no registro. Para criar um token especificando um mapa de escopo existente, consulte a próxima seção.

O exemplo a seguir cria um token no registro myregistry com as seguintes permissões no samples/hello-world repo: content/write e content/read. Por padrão, o comando define o status do token padrão como enabled, mas você pode atualizar o status para disabled a qualquer momento.

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

A saída mostra detalhes sobre o token. Por padrão, são geradas duas senhas que não expiram, mas você pode, opcionalmente, definir uma data de validade. Recomenda-se guardar as palavras-passe num local seguro para utilizar mais tarde para autenticação. As senhas não podem ser recuperadas novamente, mas novas podem ser geradas.

{
  "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 regenerar senhas de token e períodos de expiração, consulte Regenerar senhas de token mais adiante neste artigo.

A saída inclui detalhes sobre o mapa de escopo que o comando criou. Você pode usar o mapa de escopo, aqui chamado MyToken-scope-map, para aplicar as mesmas ações de repositório a outros tokens. Ou atualize o mapa de escopo posteriormente para alterar as permissões dos tokens associados.

Criar token e especificar mapa de escopo

Uma maneira alternativa de criar um token é especificar um mapa de escopo existente. Se você ainda não tiver um mapa de escopo, primeiro crie um especificando repositórios e ações associadas. Em seguida, especifique o mapa de escopo ao criar um token.

Para criar um mapa de escopo, use o comando az acr scope-map create . O comando a seguir cria um mapa de escopo com as mesmas permissões no samples/hello-world repositório usado anteriormente.

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

Execute az acr token create para criar um token, especificando o mapa de escopo MyScopeMap. Como no exemplo anterior, o comando define o status do token padrão como enabled.

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

A saída mostra detalhes sobre o token. Por padrão, duas senhas são geradas. Recomenda-se guardar as palavras-passe num local seguro para utilizar mais tarde para autenticação. As senhas não podem ser recuperadas novamente, mas novas podem ser geradas.

Nota

Para regenerar senhas de token e períodos de expiração, consulte Regenerar senhas de token mais adiante neste artigo.

Como usar mapas de escopo para definir e atribuir permissões para vários repositórios

Um mapa de escopo permite o uso de um caractere curinga para definir e conceder permissões semelhantes para vários repositórios que compartilham um prefixo comum. Repositórios com permissões específicas, repositórios com um caractere curinga também podem ser usados no mesmo mapa de escopo. Isso fornece flexibilidade no gerenciamento de permissões para vários conjuntos de repositórios em um único mapa de escopo.

As permissões de repositório podem ser criadas quando um mapa de escopo é criado e atribuído a um token. Como alternativa, um token pode ser criado e atribuído diretamente a um repositório.

O exemplo a seguir cria um mapa de escopo com um caractere curinga e, em seguida, o atribui a um 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

O exemplo a seguir cria um token com um curinga.

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

As permissões curinga são aditivas, o que significa que, quando um repositório específico é acessado, as permissões resultantes incluirão as permissões para todas as regras do mapa de escopo que correspondem ao prefixo curinga.

Neste exemplo, o mapa de escopo define permissões para três tipos diferentes de repositórios:

Repositório Permissão
sample/* content/read
sample/teamA/* content/write
sample/teamA/projectB content/delete

O token recebe um mapa de escopo para conceder [content/read, content/write, content/delete] permissões para acessar o repositório sample/teamA/projectB. No entanto, quando o mesmo token é usado para acessar o sample/teamA/projectC repositório, ele só tem [content/read, content/write] permissões.

Importante

Os repositórios que usam curingas no mapa de escopo devem sempre terminar com um sufixo para serem válidos e terem um /* único caractere curinga no nome do repositório. Aqui estão alguns exemplos de curingas inválidos:

  • sample/*/teamA com um curinga no meio do nome do repositório.
  • sample/teamA* com um curinga não termina com '/*''.
  • sample/teamA/*/projectB/* com vários curingas no nome do repositório.

Curingas de nível raiz

Os curingas também podem ser aplicados em um nível raiz. Isso significa que todas as permissões atribuídas ao repositório definido como *, serão aplicadas em todo o registro.

O exemplo mostra como criar um token com um curinga de nível raiz que daria permissões de token [content/read, content/write] a todos os repositórios no Registro. Isso fornece uma maneira simples de conceder permissões a todos os repositórios no registro sem precisar especificar cada repositório individualmente.

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

Importante

Se uma regra curinga englobar um repositório que ainda não existe, as permissões da regra curinga ainda se aplicarão a esse nome de repositório. Por exemplo, um token atribuído a um mapa de escopo que concede [content/write, metadata/write] permissões para sample/* repositórios. Além disso, suponha que o repositório sample/teamC/teamCimage ainda não existe. O token terá permissões para enviar imagens por push para o repositório, que criará simultaneamente o repositório sample/teamC/teamCimageem push bem-sucedido.

Criar token - portal

Você pode usar o portal do Azure para criar tokens e mapas de escopo. Assim como no az acr token create comando CLI, você pode aplicar um mapa de escopo existente ou criar um mapa de escopo ao criar um token especificando um ou mais repositórios e ações associadas. Os repositórios ainda não precisam estar no registro.

O exemplo a seguir cria um token e cria um mapa de escopo com as samples/hello-world seguintes permissões no repositório: content/write e content/read.

  1. No portal, navegue até o registro do contêiner.

  2. Em Permissões do repositório, selecione Tokens > +Adicionar.

    Create token in portal

  3. Insira um nome de token.

  4. Em Mapa de escopo, selecione Criar novo.

  5. Configure o mapa de escopo:

    1. Insira um nome e uma descrição para o mapa de escopo.

    2. Em Repositórios, insira samples/hello-worlde, em Permissões, selecione content/read e content/write. Em seguida, selecione +Adicionar.

      Create scope map in portal

    3. Depois de adicionar repositórios e permissões, selecione Adicionar para adicionar o mapa de escopo.

  6. Aceite o status do token padrão de Habilitadoe selecione Criar.

Depois que o token é validado e criado, os detalhes do token aparecem na tela Tokens .

Adicionar senha de token

Para usar um token criado no portal, você deve gerar uma senha. Você pode gerar uma ou duas senhas e definir uma data de validade para cada uma. Novas senhas criadas para tokens estão disponíveis imediatamente. Regenerar novas senhas para tokens levará 60 segundos para ser replicado e estar disponível.

  1. No portal, navegue até o registro do contêiner.

  2. Em Permissões do repositório, selecione Tokens e selecione um token.

  3. Nos detalhes do token, selecione password1 ou password2 e selecione o ícone Gerar.

  4. Na tela de senha, opcionalmente, defina uma data de validade para a senha e selecione Gerar. Recomenda-se definir uma data de validade.

  5. Depois de gerar uma senha, copie-a e salve-a em um local seguro. Não é possível recuperar uma senha gerada depois de fechar a tela, mas é possível gerar uma nova.

    Create token password in portal

Autenticar com token

Quando um usuário ou serviço usa um token para autenticar com o registro de destino, ele fornece o nome do token como um nome de usuário e uma de suas senhas geradas.

O método de autenticação depende da ação ou ações configuradas associadas ao token.

Ação Como autenticar
content/delete az acr repository delete na CLI do Azure

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

az acr login na CLI do Azure

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

az acr login na CLI do Azure
metadata/read az acr repository show

az acr repository show-tags

az acr manifest list-metadata na CLI do Azure
metadata/write az acr repository untag

az acr repository update na CLI do Azure

Exemplos: Usar token

Os exemplos a seguir usam o token criado anteriormente neste artigo para executar operações comuns em um repositório: enviar e extrair imagens, excluir imagens e listar tags de repositório. O token foi configurado inicialmente com permissões de push (content/writecontent/read e ações) no samples/hello-world repositório.

Puxar e marcar imagens de teste

Para os exemplos a seguir, extraia público hello-world e imagens do Microsoft Container Registry e marque-os para seu registro e nginx repositório.

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

Autenticar usando token

Execute docker login ou autentique-se com o registro para enviar ou az acr login extrair imagens. Forneça o nome do token como o nome de usuário e forneça uma de suas senhas. O token deve ter o Enabled status.

O exemplo a seguir é formatado para o shell bash e fornece os valores usando variáveis de ambiente.

TOKEN_NAME=MyToken
TOKEN_PWD=<token password>

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

A saída deve mostrar a autenticação bem-sucedida:

Login Succeeded

Enviar imagens para o registo

Após o login bem-sucedido, tente enviar as imagens marcadas para o registro. Como o token tem permissões para enviar imagens por push para o repositório, o samples/hello-world seguinte envio é bem-sucedido:

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

O token não tem permissões para o samples/nginx repositório, portanto, a seguinte tentativa de push falha com um erro semelhante a requested access to the resource is denied:

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

Atualizar permissões de token

Para atualizar as permissões de um token, atualize as permissões no mapa de escopo associado. O mapa de escopo atualizado é aplicado imediatamente a todos os tokens associados.

Por exemplo, atualize MyToken-scope-map com content/write e ações no repositório e content/read remova a content/write ação no samples/ngnxsamples/hello-world repositório.

Para usar a CLI do Azure, execute az acr scope-map update para atualizar o mapa de escopo:

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

No portal do Azure:

  1. Navegue até o registro do contêiner.
  2. Em Permissões do repositório, selecione Mapas de escopo e selecione o mapa de escopo a ser atualizado.
  3. Em Repositórios, insira samples/nginxe, em Permissões, selecione content/read e content/write. Em seguida, selecione +Adicionar.
  4. Em Repositórios, selecione samples/hello-world e, em Permissões, desmarque content/write. Em seguida, selecione Guardar.

Depois de atualizar o mapa de escopo, o seguinte push é bem-sucedido:

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

Como o mapa de escopo só tem a content/read permissão no samples/hello-world repositório, uma tentativa de envio por push para o samples/hello-world repositório agora falha:

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

A extração de imagens de ambos os repositórios é bem-sucedida, porque o mapa de escopo fornece content/read permissões em ambos os repositórios:

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

Eliminar imagens

Atualize o mapa de escopo adicionando a content/delete ação ao nginx repositório. Esta ação permite a exclusão de imagens no repositório, ou a exclusão de todo o repositório.

Para maior brevidade, mostramos apenas o comando az acr scope-map update para atualizar o mapa de escopo:

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

Para atualizar o mapa de escopo usando o portal, consulte a seção anterior.

Use o seguinte comando az acr repository delete para excluir o samples/nginx repositório. Para excluir imagens ou repositórios, passe o nome e a senha do token para o comando. O exemplo a seguir usa as variáveis de ambiente criadas anteriormente no artigo:

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

Mostrar tags de repositório

Atualize o mapa de escopo adicionando a metadata/read ação ao hello-world repositório. Esta ação permite ler dados de manifesto e tag no repositório.

Para maior brevidade, mostramos apenas o comando az acr scope-map update para atualizar o mapa de escopo:

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

Para atualizar o mapa de escopo usando o portal, consulte a seção anterior.

Para ler metadados no samples/hello-world repositório, execute o comando az acr manifest list-metadata ou az acr repository show-tags .

Para ler metadados, passe o nome e a senha do token para qualquer um dos comandos. O exemplo a seguir usa as variáveis de ambiente criadas anteriormente no artigo:

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

Saída de exemplo:

[
  "v1"
]

Gerenciar tokens e mapas de escopo

Listar mapas de escopo

Use o comando az acr scope-map list ou a tela Scope maps no portal para listar todos os mapas de escopo configurados em um registro. Por exemplo:

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

A saída consiste nos três mapas de escopo definidos pelo sistema e outros mapas de escopo gerados por você. Os tokens podem ser configurados com qualquer um desses mapas de escopo.

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

Mostrar detalhes do token

Para exibir os detalhes de um token, como seu status e datas de expiração de senha, execute o comando az acr token show ou selecione o token na tela Tokens no portal. Por exemplo:

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

Use o comando az acr token list, ou a tela Tokens no portal, para listar todos os tokens configurados em um registro. Por exemplo:

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

Regenerar senhas de token

Se você não gerou uma senha de token ou deseja gerar novas senhas, execute o comando az acr token credential generate . Regenerar novas senhas para tokens levará 60 segundos para ser replicado e estar disponível.

O exemplo a seguir gera um novo valor para password1 para o token MyToken , com um período de expiração de 30 dias. Ele armazena a senha na variável TOKEN_PWDde ambiente . Este exemplo está formatado para o shell 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 o portal do Azure para gerar uma senha de token, consulte as etapas em Criar token - portal anteriormente neste artigo.

Atualizar token com novo mapa de escopo

Se você quiser atualizar um token com um mapa de escopo diferente, execute az acr token update e especifique o novo mapa de escopo. Por exemplo:

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

No portal, na tela Tokens , selecione o token e, em Mapa de escopo, selecione um mapa de escopo diferente.

Gorjeta

Depois de atualizar um token com um novo mapa de escopo, talvez você queira gerar novas senhas de token. Use o comando az acr token credential generate ou regenere uma senha de token no portal do Azure.

Desativar ou excluir token

Talvez seja necessário desabilitar temporariamente o uso das credenciais de token para um usuário ou serviço.

Usando a CLI do Azure, execute o comando az acr token update para definir o status como disabled:

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

No portal, selecione o token na tela Tokens e selecione Desativado em Status.

Para excluir um token para invalidar permanentemente o acesso de qualquer pessoa usando suas credenciais, execute o comando az acr token delete .

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

No portal, selecione o token na tela Tokens e selecione Descartar.

Próximos passos

  • Para gerenciar mapas de escopo e tokens, use comandos adicionais nos grupos de comandos az acr scope-map e az acr token .
  • Consulte a visão geral da autenticação para obter outras opções para autenticar com um registro de contêiner do Azure, incluindo o uso de uma identidade do Microsoft Entra, uma entidade de serviço ou uma conta de administrador.
  • Saiba mais sobre registros conectados e o uso de tokens para acesso.