Criar um token com permissões com escopo de repositório
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 artefatometadata/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.
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 salvar as senhas em um local seguro para usar 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 salvar as senhas em um local seguro para usar 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 sample/teamC/teamCimage
, que criará simultaneamente o repositório em 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
.
No portal, navegue até o registro do contêiner.
Em Permissões do repositório, selecione Tokens > +Adicionar.
Insira um nome de token.
Em Mapa de escopo, selecione Criar novo.
Configure o mapa de escopo:
Insira um nome e uma descrição para o mapa de escopo.
Em Repositórios, insira
samples/hello-world
e, em Permissões, selecionecontent/read
econtent/write
. Em seguida, selecione +Adicionar.Depois de adicionar repositórios e permissões, selecione Adicionar para adicionar o mapa de escopo.
Aceite o status do token padrão de Habilitado e 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.
No portal, navegue até o registro do contêiner.
Em Permissões do repositório, selecione Tokens e selecione um token.
Nos detalhes do token, selecione password1 ou password2 e selecione o ícone Gerar.
Na tela de senha, opcionalmente, defina uma data de validade para a senha e selecione Gerar. Recomenda-se 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 depois de fechar a tela, mas é possível 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 ou ações configuradas associadas ao token.
Ação | Como autenticar |
---|---|
content/delete |
az acr repository delete na CLI do AzureExemplo: az acr repository delete --name myregistry --repository myrepo --username MyToken --password xxxxxxxxxx |
content/read |
docker login az acr login na CLI do AzureExemplo: 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/write
content/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 nginx
imagens do Microsoft Container Registry e marque-os para seu registro e 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
autentique-se com o registro para enviar ou 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 samples/hello-world
repositório, o 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 content/read
ações no samples/ngnx
repositório e remova a content/write
ação no samples/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:
- Navegue até o registro do 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, selecionecontent/read
econtent/write
. Em seguida, selecione +Adicionar. - Em Repositórios, selecione
samples/hello-world
e, em Permissões, desmarquecontent/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_PWD
de 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.