Criar um token com permissões no escopo do repositório

Artigo
10/16/2024

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

Cenários comuns para criação de um token incluem:

Permitir que dispositivos IoT com tokens individuais efetuem pull uma imagem de um repositório.
Fornecer a uma organização externa permissões para um caminho de repositório.
Limitar o acesso ao repositório a diferentes grupos de usuários em sua organização. Por exemplo, fornecer acesso de gravação e leitura aos desenvolvedores que criam imagens direcionadas a repositórios específicos e acesso de leitura às equipes que fazem implantação desses repositórios.

Esse recurso está disponível em todos os níveis de serviço. Para saber mais sobre os limites e níveis do serviço de registro, confira Níveis 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 no escopo do repositório, você cria 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 validade 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	Efetuar pull de um artefato
`content/write`	Gravar dados no repositório	Usar com `content/read` para efetuar push de 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

Observação

Permissões com escopo de repositório não dão suporte à 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 é associado a um único mapa de escopo. Com um mapa de escopo, você pode:
- Configurar vários tokens com permissões idênticas para um conjunto de repositórios.
- Atualizar as permissões de token ao adicionar ou remover ações de repositório no mapa de escopo ou aplicar um mapa de escopo diferente.
O Registro de Contêiner do Azure também conta com diversos mapas de escopo definidos pelo sistema que podem ser aplicados durante a criação de tokens. As permissões de mapas de escopo definidos pelo sistema se aplicam a todos os repositórios no 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.

Tokens de registro e mapas de escopo

Pré-requisitos

CLI do Azure: os exemplos de comando da CLI do Azure neste artigo exigem a CLI do Azure versão 2.17.0 ou posterior. Execute az --version para encontrar a versão. Se você precisa instalar ou atualizar, consulte Instalar a CLI do Azure.
Docker - Para autenticar com o registro para efetuar pull ou push de imagens, você precisa de uma instalação local do Docker. O Docker fornece instruções de instalação para sistemas macOS, Windows e Linux.
Registro de contêiner: se ainda não tiver um, crie um registro de contêiner na 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

Para criar um token, use 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 não precisam ainda 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 repositório samples/hello-world: 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ê tem a opção de definir uma data de validade. É recomendável salvar as senhas em um local seguro para usar posteriormente para autenticação. As senhas não podem ser recuperadas, 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"
}

Observação

Para regenerar senhas de token e períodos de validade, confira 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 de MyToken-scope-map, para aplicar as mesmas ações de repositório a outros tokens. Ou atualize o mapa de escopo depois 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 comandoaz acr scope-map create. O comando a seguir cria um mapa de escopo com as mesmas permissões no repositório 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"

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. É recomendável salvar as senhas em um local seguro para usar posteriormente para autenticação. As senhas não podem ser recuperadas, mas novas podem ser geradas.

Observação

Para regenerar senhas de token e períodos de validade, confira 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 proporciona flexibilidade na gestão de permissões para um conjunto múltiplo 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. Alternativamente, um token pode ser criado e diretamente atribuído 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 de todas as regras de 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 é atribuído a 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 repositório sample/teamA/projectC, ele só tem permissões [content/read, content/write].

Importante

Repositórios que usam curingas no mapa de escopo devem sempre terminar com um sufixo /* para serem válidos e ter 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 que não termina com `/*``.
sample/teamA/*/projectB/* com vários curingas no nome do repositório.

Curingas de nível raiz

Curingas também podem ser aplicados em um nível raiz. Isso significa que quaisquer 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 ao token [content/read, content/write] permissões para todos os repositórios no registro. Isso oferece uma maneira simples de conceder permissões para todos os repositórios no registro sem ter que especificar cada repositório individualmente.

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

Importante

Se uma regra curinga abranger 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 que é atribuído a um mapa de escopo que concede permissões [content/write, metadata/write] para repositórios sample/*. Além disso, suponha que o repositório sample/teamC/teamCimage ainda não exista. O token terá permissões para enviar imagens ao repositório sample/teamC/teamCimage, o que criará simultaneamente o repositório com o push bem-sucedido.

Criar token - portal

Você pode usar o portal do Azure para criar tokens e mapas de escopo. Assim como ocorre com o comando CLI az acr token create, 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 não precisam ainda estar no registro.

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

No portal, navegue até o registro de contêiner.
Em Permissões do repositório, selecione Tokens > +Adicionar.
Insira um nome do token.
Em Mapa de escopo, selecione Criar novo.
Configurar o mapa de escopo:
1. Insira um nome e descrição para o mapa de escopo.
2. Em Repositórios, insira samples/hello-world e, em Permissões, selecione content/read e content/write. Em seguida, selecione +Adicionar.
3. Depois de adicionar repositórios e permissões, selecione Adicionar para adicionar o mapa de escopo.
Aceite o Status de token padrão de Habilitado e, em seguida, selecione Criar.

Depois que o token for validado e criado, os detalhes do token serão exibidos na tela Tokens.

Adicionar senha do 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 ficam disponíveis imediatamente. A regeneração de senhas para tokens levará 60 segundos para replicar e ficar disponível.

No portal, navegue até o registro de contêiner.
Em Permissões do repositório, clique em Tokens e selecione um token.
Nos detalhes do token, selecione password1 ou password2 e selecione o ícone Gerar.
Na tela da senha, defina uma data de validade para a senha, se quiser, e selecione Gerar. É recomendável definir uma data de validade.
Depois de gerar uma senha, copie-a e salve-a em um local seguro. Não é possível recuperar uma senha gerada após fechar a tela, mas você pode gerar uma nova.

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 configurada ou das ações 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: efetuar push e pull de imagens, excluir imagens e listar tags de repositório. O token foi configurado inicialmente com permissões de push (ações content/write e content/read) no repositório samples/hello-world.

Efetuar pull e marcar imagens de teste

Para os exemplos a seguir, efetue pull das imagens hello-world e nginx do Microsoft Container Registry e marque-as para o Registro e o 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 az acr login para se autenticar com o Registro para efetuar push ou pull de imagens. Informe o nome do token como o nome de usuário e uma de suas senhas. O token deve ter o status de Enabled.

O exemplo a seguir é formatado para o shell do 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

Efetuar push de imagens para registro

Após o logon bem-sucedido, tente efetuar push das imagens marcadas para o registro. Como o token tem permissões para efetuar push das imagens para o repositório de samples/hello-world, o seguinte push é executado com sucesso:

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

O token não tem permissões para o repositório de samples/nginx, 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 ações content/write e content/read no repositório samples/ngnx e remova a ação content/write no repositório samples/hello-world.

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:

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

Depois de atualizar o mapa de escopo, o push a seguir será efetuado:

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

Como o mapa de escopo tem apenas a permissão content/read no repositório samples/hello-world, uma tentativa de efetuar push para o repositório samples/hello-world agora falhará:

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

O pull de imagens de ambos os repositórios é efetuado com sucesso, porque o mapa de escopo fornece permissões content/read em ambos os repositórios:

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

Excluir imagens

Para atualizar o mapa de escopo, adicione a ação content/delete ao repositório nginx. Essa ação permite excluir imagens no repositório ou todo o repositório.

Para resumir, mostraremos apenas o comando az acr scope-map update para atualizar o mapa do 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 comando a seguir az acr repository delete para excluir o repositório samples/nginx. 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 neste artigo:

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

Mostrar tags do repositório

Para atualizar o mapa de escopo, adicione a ação metadata/read ao repositório hello-world. Essa ação permite a leitura de dados de manifesto e tags no repositório.

Para resumir, mostraremos apenas o comando az acr scope-map update para atualizar o mapa do 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 repositório samples/hello-world, 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 comando. O exemplo a seguir usa as variáveis de ambiente criadas anteriormente neste 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 Mapas de escopo 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 é formada por 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 tiver uma senha de token ou se quiser gerar novas senhas, execute o comando az acr token credential generate. A regeneração de senhas para tokens levará 60 segundos para replicar e ficar 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 de ambiente TOKEN_PWD. Este exemplo é formatado para o shell do 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 o token - portal anteriormente explicadas neste artigo.

Atualizar o token com o 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.

Dica

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 gere novamente uma senha de token no portal do Azure.

Desabilitar 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 comandoaz 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 Desabilitado em Status.

Para excluir um token para invalidar permanentemente o acesso por qualquer pessoa que use 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óximas etapas

Para gerenciar tokens e mapas de escopo, use comandos adicionais em grupos de comando az acr scope-map e az acr token.
Confira a visão geral da autenticação para ver outras opções de autenticação 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.

Compartilhar via

Criar um token com permissões no escopo do repositório

Limitações

Conceitos

Pré-requisitos

Criar token - CLI

Criar token e especificar repositórios

Criar token e especificar mapa de escopo

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

Curingas de nível raiz

Criar token - portal

Adicionar senha do token

Autenticar com token

Exemplos: Usar token

Efetuar pull e marcar imagens de teste

Autenticar usando token

Efetuar push de imagens para registro

Atualizar permissões de token

Excluir imagens

Mostrar tags do repositório

Gerenciar tokens e mapas de escopo

Listar mapas de escopo

Mostrar detalhes do token

Regenerar senhas de token

Atualizar o token com o novo mapa de escopo

Desabilitar ou excluir token

Próximas etapas

Comentários

Recursos adicionais