Básico

Anatomia de uma policy

Lição 3 · Módulo 1 — Átomos do IAM

Policies são JSON

Uma policy é um documento JSON. Parece intimidante na primeira vez, mas tem só 6 campos principais. Conhecendo cada um, você lê qualquer policy da AWS.

JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PermitirLeituraDoBucketRelatorios",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::relatorios",
        "arn:aws:s3:::relatorios/*"
      ]
    }
  ]
}

Os campos em detalhe

Vamos dissecar cada campo, o que ele significa, quais valores aceita e armadilhas comuns. Se precisar de uma consulta rápida depois, veja a página de referência.

Version

Obrigatório

É a versão da linguagem de policies da AWS, não da sua policy. Use sempre "2012-10-17" — a versão mais nova, que todas as features modernas (como variáveis ${aws:username}) requerem.

A versão antiga "2008-10-17" existe por compatibilidade; nunca escreva uma policy nova com ela.

Docs: Version

Id

Opcional

Identificador único da policy inteira. Só aparece em algumas resource-based policies (ex.: SQS, SNS). Ignorado em identity-based policies. Na prática, raro.

Docs: Id

Statement

Obrigatório

O coração da policy: uma lista de statements, cada um com sua combinação de Effect/Action/Resource/Condition. Pode ser um único objeto ou um array.

Regra importante: cada statement é avaliado independentemente. O resultado final da policy é a combinação de todos — não há ordem nem prioridade. Um Deny em qualquer statement vence todos os Allows.

Docs: Statement

Sid

Opcional

Statement ID — um rótulo legível para você. Não afeta a avaliação, mas aparece em logs e facilita o debugging ("qual statement permitiu/negou essa ação?"). Deve ser único dentro da mesma policy. Use letras e números, sem espaços.

Docs: Sid

Effect

Obrigatório

Só aceita dois valores: "Allow" ou "Deny". Nada além disso — escrever "allow" (minúsculo) ou "Permit" é erro de sintaxe.

Dica: Deny sempre vence. Se um statement com Deny casa com a request, a request é negada, mesmo que 100 outros statements tenham Allow.

Docs: Effect

Principal / NotPrincipal

Só em resource-based

Define quem pode fazer a ação. Identity-based policies não têm Principal — o principal é implicitamente a identidade a que a policy está anexada.

Tipos de valor:

  • "AWS": "arn:aws:iam::111:user/alice" — um IAM User/Role específico.
  • "AWS": "arn:aws:iam::111:root" — qualquer identidade da conta 111.
  • "Service": "lambda.amazonaws.com" — um serviço AWS.
  • "Federated": "accounts.google.com" — um provedor de identidade federado.
  • "*" — qualquer principal (incluindo anônimo). Perigoso.

Docs: Principal

Action / NotAction

Obrigatório

Action define o que está sendo permitido/negado. String única ou array. Formato servico:Operacao, sempre em PascalCase: s3:GetObject, ec2:StartInstances.

Wildcards:

  • "s3:*" — todas as ações do S3.
  • "s3:Get*" — todas as ações que começam com Get.
  • "*" — todas as ações de todos os serviços. Admin total.

NotAction é o oposto: "todas as ações exceto estas". Raramente é o que você realmente quer — veja o alerta abaixo. Aprofundamos Action na próxima lição.

Docs: Action · Docs: NotAction

Resource / NotResource

Obrigatório em identity-based

Define sobre o quê a ação se aplica. Valor é um ARN ou lista de ARNs. Aceita * como wildcard.

Em resource-based policies, o campo é opcional — o recurso é implicitamente aquele onde a policy está anexada (ex.: o bucket).

Aprofundamos ARNs e padrões de Resource na próxima lição.

Docs: Resource · Docs: NotResource

Condition

Opcional

Adiciona uma quarta dimensão à policy: sob quais circunstâncias. Permite exigir MFA, restringir IP de origem, limitar região, comparar tags e muito mais.

Estrutura: "Condition": { operador: { context-key: valor } }. Cobrimos a fundo na Lição 12.

Docs: Condition

O que é obrigatório?

CampoIdentity-basedResource-based
Version✅ obrigatório✅ obrigatório
Id— ignorado⭕ opcional
Statement✅ obrigatório✅ obrigatório
Sid⭕ opcional⭕ opcional
Effect✅ obrigatório✅ obrigatório
Principal— proibido✅ obrigatório
Action✅ obrigatório*✅ obrigatório*
Resource✅ obrigatório*⭕ opcional (implícito)
Condition⭕ opcional⭕ opcional

* Action/NotAction e Resource/NotResource — exatamente um dos dois deve estar presente.

Deny por padrão

Princípio fundamental: se nada permite, o resultado é Deny. Você não precisa escrever Deny para bloquear; só precisa não escrever Allow. Deny explícito existe para sobrepor um Allow — e sempre vence.

Esse é o coração do modelo de avaliação IAM — que vamos detalhar no Módulo 2.

Teste rápido

Uma policy tem Allow s3:GetObject em * e outra tem Deny s3:GetObject em * (mesmo principal). Qual é o resultado de uma chamada s3:GetObject?

Uma policy tem apenas Allow s3:PutObject. O que acontece com uma chamada s3:GetObject?

Resumo

Decore o esqueleto Version → Statement → [Sid, Effect, Action, Resource]. Todo o resto são variações e extensões. A próxima lição foca em como Action e Resource funcionam de verdade, com wildcards e ARNs.

Para consulta rápida de todos os campos em um único lugar, veja a página de referência.

Referência Well-Architected

Esta lição é pré-requisito para todas as boas práticas de gestão de permissões do Well-Architected Framework: você não escreve boas policies sem dominar a anatomia do documento.

Referências

Terminou esta lição?

Seu progresso fica salvo apenas neste navegador.