ARN, ou Amazon Resource Name, é o identificador único que a AWS usa para apontar para um recurso específico, como um bucket, uma função ou um usuário. Sempre que você escreve uma política de IAM, configura um gatilho ou referência um recurso em outro serviço, o ARN entra em cena. Neste guia você entende a estrutura do ARN campo a campo, vê exemplos de serviços comuns e aprende os cuidados ao copiar e compartilhar. Para separar e validar o formato de um ARN, use as ferramentas DevOps, que fazem a análise localmente, sem consultar a AWS.
Resposta rápida
- ARN = Amazon Resource Name, o identificador único de um recurso na AWS.
- Formato: arn:partition:service:region:account-id:resource.
- O IAM é global e deixa a região vazia. O S3 tem região, mas o ARN do bucket omite região e conta porque o nome do bucket já é único na partição.
- O ARN é identificador, não permissão: o acesso depende das políticas. A AWS diz que ARN não é segredo; o perigo é publicá-lo ao lado de uma credencial.
O que é ARN
Na AWS, há milhões de recursos espalhados por contas e regiões. O ARN é a forma padronizada de nomear cada um deles sem ambiguidade. Ele é usado em políticas de permissão (para dizer a quais recursos uma ação se aplica), em integrações entre serviços e em logs. Ler um ARN com fluência ajuda a depurar permissões e a entender de qual recurso, conta e região algo está falando.
Estrutura geral
O formato é:
arn:partition:service:region:account-id:resourceOs campos são separados por dois pontos. O último campo, o resource, pode conter barras e dois pontos internos, e às vezes inclui um tipo de recurso antes do identificador.
Partition
Indica o conjunto de regiões, e cada conta da AWS pertence a uma única partition. Quase sempre é aws, das regiões padrão. Há também aws-cn, das regiões da China, aws-us-gov, do GovCloud dos Estados Unidos, e aws-eusc, do European Sovereign Cloud. As partições são isoladas entre si: credencial, endpoint e ARN de uma não valem na outra, e é por isso que copiar uma política entre ambientes sem trocar a partition não funciona. Uma partition fora dessas quatro merece conferência, porque a documentação pública da AWS lista só elas.
Service
O serviço dono do recurso, como s3, iam, lambda, sqs, dynamodb ou kms. É um dos campos mais úteis para entender rapidamente sobre o que o ARN trata.
Region
A região onde o recurso existe, como us-east-1 ou sa-east-1. O IAM é global de verdade: usuário, grupo, papel e política não vivem em uma região, e por isso o campo fica vazio no ARN deles.
O S3 é o caso em que quase todo mundo erra. Todo bucket é criado em uma região que você escolhe, e os objetos não saem dela, mas o ARN do bucket não traz a região mesmo assim. O motivo é o formato, não a natureza do recurso: o nome do bucket já é único entre todas as contas e regiões da mesma partição, então ele sozinho resolve para qual recurso o ARN aponta. Campo vazio ali quer dizer "o formato não precisa deste dado", e nunca "o recurso não tem região". Para descobrir a região de um bucket, use a subresource de localização (na linha de comando, aws s3api get-bucket-location).
Account ID
O identificador numérico da conta AWS dona do recurso, com 12 dígitos. Alguns serviços, como o S3, deixam esse campo vazio no ARN. Quando ele aparece com um número diferente de 12 dígitos, vale desconfiar de um erro de cópia.
Resource e resource type
O resource identifica o item. Dependendo do serviço, vem acompanhado de um tipo. Há três formas comuns: só o resource; resourcetype/resource (separado por barra); e resourcetype:resource (separado por dois pontos). Saber qual formato o serviço usa evita interpretar errado, por exemplo confundir o nome de um bucket do S3 com um tipo de recurso.
Exemplos por serviço
| Serviço | Exemplo de ARN |
|---|---|
| S3 (bucket) | arn:aws:s3:::meu-bucket |
| S3 (objeto) | arn:aws:s3:::meu-bucket/pasta/arquivo.txt |
| IAM (usuário) | arn:aws:iam::123456789012:user/Joao |
| Lambda | arn:aws:lambda:us-east-1:123456789012:function:minhaFuncao |
| CloudWatch Logs | arn:aws:logs:us-east-1:123456789012:log-group:/aws/lambda/minhaFuncao |
| KMS | arn:aws:kms:us-east-1:123456789012:key/abcd-1234 |
Repare que o S3 deixa region e account vazios, enquanto Lambda e KMS trazem os dois preenchidos e usam tipo de recurso antes do identificador.
Erros comuns ao copiar ARN
- Cortar parte do resource que contém barras ou dois pontos.
- Trocar a region por engano ao reaproveitar um ARN de outro ambiente.
- Confundir o nome do bucket do S3 com um tipo de recurso.
- Deixar espaços invisíveis no início ou no fim ao colar.
ARN não é segredo, credencial é
A documentação de ARN da AWS é explícita: ARNs devem ser usados e compartilhados com cuidado, como qualquer informação de identificação, mas não são considerados secretos, sensíveis ou confidenciais. Vale repetir porque muita gente inverte isso: um ARN vazado não concede acesso, e um ARN escondido não protege recurso nenhum. Quem concede acesso é a política.
O perigo real é o ARN aparecer ao lado de uma chave de acesso, de um token de sessão ou de uma senha, em repositório público, print de tela ou mensagem. Aí o que vazou foi a credencial, e o ARN só disse ao atacante onde usá-la. Existe uma ressalva de higiene, que é diferente de sigilo: o ID da conta facilita enumerar recursos e montar uma tentativa de engenharia social mais convincente, então não saia espalhando sem motivo. Tokens, por exemplo, têm sua própria anatomia: veja o decodificador de JWT para entender o que um token revela ao ser decodificado.
ARN em políticas de IAM e curingas
O uso mais frequente de ARN é em políticas de permissão do IAM, onde o campo Resource diz a quais recursos uma ação se aplica. É aí que aparecem os curingas. O asterisco substitui qualquer sequência, então arn:aws:s3:::meu-bucket/* representa todos os objetos dentro do bucket. Um Resource igual a apenas um asterisco significa qualquer recurso, o que costuma ser amplo demais e deve ser evitado fora de casos bem específicos.
A confusão mais cara do S3 é achar que o ARN do bucket cobre os objetos. Não cobre, e os dois precisam aparecer na política. Ação de bucket, como s3:ListBucket, s3:GetBucketLocation e s3:GetBucketPolicy, é avaliada contra arn:aws:s3:::meu-bucket, sem barra e sem asterisco. Ação de objeto, como s3:GetObject, s3:PutObject e s3:DeleteObject, é avaliada contra arn:aws:s3:::meu-bucket/*. Uma política que só traz o ARN com barra e asterisco deixa a listagem falhar com acesso negado; uma que só traz o ARN do bucket deixa a leitura do arquivo falhar. Quando as duas coisas são necessárias, o campo Resource lista os dois ARNs, ou a política é dividida em duas instruções, cada uma com a sua ação e o seu recurso.
Entender essa estrutura ajuda a aplicar o princípio do menor privilégio: conceder só o acesso necessário, ao recurso necessário. Em vez de liberar um serviço inteiro, restrinja ao bucket, à função ou à tabela específica pelo ARN. Erros comuns incluem usar curingas amplos por preguiça, ou apontar para a região errada ao reaproveitar uma política entre ambientes de desenvolvimento e produção.
Vale também distinguir o ARN do recurso do ARN de algo dentro dele. Um bucket do S3 tem um ARN; cada objeto dentro dele tem outro, com o caminho após a barra. Uma função Lambda tem um ARN; uma versão específica ou um alias têm ARNs próprios. Confundir esses níveis é uma fonte clássica de políticas que não funcionam como esperado. Ler o ARN com atenção, parte por parte, resolve a maioria desses enganos antes que virem um incidente.
Como encontrar o ARN de um recurso
Na prática, há várias formas de obter o ARN. No console da AWS, a maioria das telas de recurso mostra o ARN em algum painel de detalhes, pronto para copiar. Pela linha de comando, comandos de descrição e de listagem retornam o ARN no resultado. Em modelos de infraestrutura como código, funções específicas devolvem o ARN de um recurso recém-criado para você referenciar em outro lugar do mesmo modelo, evitando copiar valores manualmente.
Ao copiar de telas, cuidado com espaços extras e com o recurso ser cortado quando ele contém barras. Ao reutilizar um ARN entre ambientes, troque a região e o ID da conta conforme o destino, em vez de assumir que o mesmo ARN serve para tudo. E lembre que o ARN é a forma canônica de se referir ao recurso: usar o nome simples em vez do ARN, onde a AWS espera um ARN, é uma causa frequente de erro silencioso em políticas e integrações.
Por fim, lembre que o ARN é só o identificador, não a permissão em si. Ter o ARN de um recurso não dá acesso a ele; o acesso depende das políticas associadas a quem faz a chamada. Por isso, ao depurar um problema de permissão, confira duas coisas: se o ARN no campo Resource está correto e se a ação no campo Action corresponde ao que você está tentando fazer. Comece sempre por esses dois campos: são baratos de conferir e não exigem abrir política nenhuma. Se o ARN e a ação estiverem corretos e o acesso continuar negado, o IAM Policy Simulator e o evento de negação registrado no CloudTrail mostram qual instrução barrou a chamada.
Quando usar a ferramenta do ValorFinal
Use as ferramentas DevOps para colar um ARN e ver cada parte separada (partition, service, region, account e resource), com avisos de formato, sem nenhuma consulta à AWS. Para redes, veja a calculadora de sub-rede IPv4. Conheça as demais ferramentas de tecnologia.
Fontes e referências
- AWS Documentation (Amazon Resource Names): estrutura e formatos de ARN.
- AWS IAM (elemento Resource): uso de ARN em políticas e curingas.
- Amazon S3 (visão geral dos buckets de uso geral): as quatro partitions da AWS, a unicidade do nome do bucket dentro da partição e a região escolhida na criação.
Conclusão
O ARN é a forma canônica de a AWS nomear recursos: arn:partition:service:region:account-id:resource. Ler cada parte com atenção evita erros em políticas e integrações, e lembrar que o ARN é identificador, não permissão, ajuda a depurar acessos. Para separar e validar um ARN, use as ferramentas DevOps e conheça as demais ferramentas de tecnologia.