Elementos de política do IAM: variáveis e etiquetas
Use variáveis de política do AWS Identity and Access Management (IAM) como espaços reservados quando você não souber o valor exato de um recurso ou uma chave de condição ao escrever a política.
nota
Se a AWS não puder resolver uma variável, isso poderá invalidar toda a instrução. Por exemplo, se você usar a variável aws:TokenIssueTime, a variável será resolvida como um valor somente quando o solicitante tiver sido autenticado com credenciais temporárias (uma função do IAM). Para evitar que as variáveis provoquem instruções inválidas, use o operador de condição ...IfExists.
Tópicos
Introdução
Nas políticas do IAM, muitas ações permitem que você forneça um nome para os recursos específicos cujo acesso deseja controlar. For exemplo, a política a seguir permite que o usuário liste, leia e grave objetos no bucket do S3 DOC-EXAMPLE-BUCKET para projetos de marketing.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": ["arn:aws:s3:::DOC-EXAMPLE-BUCKET"], "Condition": {"StringLike": {"s3:prefix": ["marketing/*"]}} }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject" ], "Resource": ["arn:aws:s3:::DOC-EXAMPLE-BUCKET/marketing/*"] } ] }
Em alguns casos, talvez você saiba o nome exato do recurso ao elaborar a política. Talvez você queira generalizar a política para que ele funcione para muitos usuários sem a necessidade de fazer uma cópia exclusiva da política para cada usuário. Em vez de criar uma política específica para cada usuário, recomendamos criar uma única política de grupo que funcione para qualquer usuário desse grupo.
Usar variáveis em políticas
É possível definir valores dinâmicos dentro das políticas usando variáveis de política que definem espaços reservados em uma política.
As variáveis são marcadas usando um prefixo $ seguido por um par de chaves ({ }) que incluem o nome da variável do valor da solicitação.
Quando a política for avaliada, suas variáveis serão substituídas por valores provenientes das chaves de contexto condicionais passadas na solicitação. As variáveis podem ser usadas em políticas baseadas em identidade, políticas de recursos, políticas de controle de serviços, políticas de sessão e políticas de endpoint da VPC. As políticas baseadas em identidade usadas como limites de permissões também são compatíveis com variáveis de política.
As chaves de contexto de condição globais podem ser usadas como variáveis em solicitações entre serviços da AWS. As chaves de condição específicas do serviço também podem ser usadas como variáveis ao interagir com recursos da AWS, mas só estão disponíveis quando as solicitações são baseadas em recursos compatíveis com elas. Para obter uma lista das chaves de contexto disponíveis para cada serviço e recurso da AWS, consulte a Referência de autorização de serviço. Em certas circunstâncias, não é possível preencher chaves de contexto de condição globais com um valor. Para saber mais, consulte Chaves de contexto de condição globais da AWS.
Importante
-
Os nomes das chaves não diferenciam maiúsculas de minúsculas. Por exemplo,
aws:CurrentTimeequivale aAWS:currenttime. -
É possível usar qualquer chave de condição de valor único disponível como uma variável. Você não pode usar uma chave de condição de valores múltiplos como uma variável.
O exemplo a seguir mostra uma política para um perfil ou usuário do IAM que substitui um nome do recurso específico por uma variável de política. Você pode reutilizar essa política aproveitando a chave de condição aws:PrincipalTag. Quando esta política é avaliada, ${aws:PrincipalTag/team} permitirá ações somente se o nome do bucket terminar com o nome da equipe da tag team da entidade principal.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": ["arn:aws:s3:::DOC-EXAMPLE-BUCKET"], "Condition": {"StringLike": {"s3:prefix": ["${aws:PrincipalTag/team}/*"]}} }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject" ], "Resource": ["arn:aws:s3:::DOC-EXAMPLE-BUCKET/${aws:PrincipalTag/team}/*"] } ] }
A variável é marcada usando um $ prefixo seguido por um par de chaves ({ }). Dentro dos caracteres ${ }, você pode incluir o nome do valor da solicitação que você deseja usar na política. Os valores que você pode usar serão abordados posteriormente nesta página.
Para obter uma lista desta chave de condição global, consulte aws:PrincipalTag/tag-key na lista de chaves condição globais.
nota
Para usar variáveis de política, você deve incluir o elemento Version em uma instrução, e a versão deve ser definida como uma versão que oferece suporte às variáveis de política. As variáveis foram apresentadas na versão 2012-10-17. Versões anteriores da linguagem da política não são compatíveis com variáveis de política. Se você não incluir o elemento Version e defini-lo como uma data de versão apropriada, variáveis como ${aws:username} serão tratadas como strings literais na política.
Um elemento de política Version é diferente de uma versão de política. O elemento de política Version é usado em uma política e define a versão da linguagem da política. Uma versão da política, por outro lado, é criada quando você altera uma política gerenciada pelo cliente no IAM. A política alterada não substitui a política existente. Em vez disso, o IAM cria uma nova versão da política gerenciada. Para saber mais sobre o elemento de política Version, consulte Elementos de política JSON do IAM: Version. Para saber mais sobre as versões de política, consulte Versionamento de políticas do IAM.
Uma política que permite que uma entidade principal obtenha objetos do caminho /David de um bucket do S3 tem a seguinte aparência:
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["s3:GetObject"], "Resource": ["arn:aws:s3::DOC-EXAMPLE-BUCKET/David/*"] }] }
Se essa política estiver anexada ao usuário David, esse usuário terá objetos do seu próprio bucket do S3, mas você teria que criar uma política específica para cada usuário que incluísse o nome do usuário. Você pode anexar cada política aos usuários individuais.
Ao usar uma variável de política, você pode criar políticas que podem ser reutilizadas. A política a seguir permite que um usuário obtenha objetos de um bucket do Amazon S3 se o valor da chave de tag aws:PrincipalTag corresponder ao valor da chave de tag owner passado na solicitação.
{ "Version": "2012-10-17", "Statement": [{ "Sid": "AllowUnlessOwnedBySomeoneElse", "Effect": "Allow", "Action": ["s3:GetObject"], "Resource": ["*"], "Condition": { "StringEquals": { "s3:ExistingObjectTag/owner": "${aws:PrincipalTag/owner}" } } } ] }
Ao usar uma variável de política para um usuário dessa forma, você não precisa ter uma política específica para cada usuário individual. No exemplo a seguir, a política é anexada a um perfil do IAM que é assumido pelos gerentes de produto usando credenciais de segurança temporárias. Quando um usuário faz uma solicitação para adicionar um objeto do Amazon S3, o IAM substituísse o valor da tag dept da solicitação atual para a variável ${aws:PrincipalTag} e avalia a política.
{ "Version": "2012-10-17", "Statement": [{ "Sid": "AllowOnlyDeptS3Prefix", "Effect": "Allow", "Action": ["s3:GetObject"], "Resource": ["arn:aws:s3:::DOC-EXAMPLE-BUCKET/${aws:PrincipalTag/dept}/*"], } ] }
Tags como variáveis de política
Em alguns serviços da AWS que você pode anexar os próprios atributos personalizados a recursos criados por esses serviços. Por exemplo, você pode aplicar etiquetas a buckets do Amazon S3 ou a usuários do IAM. Essas tags são pares de chave-valor. Você define o nome da chave de tag e o valor associado ao nome dessa chave. Por exemplo, convém criar uma tag com uma chave department e um valor Human Resources. Para obter mais informações sobre como etiquetar entidades do IAM, consulte Recursos de etiquetas do IAM. Para obter informações sobre como marcar recursos criados por outros serviços da AWS, consulte a documentação desse serviço. Para obter informações sobre como usar o Tag Editor, consulte Trabalhar com o Tag Editor no AWS Management Console Guia do usuário.
Você pode etiquetar recursos do IAM para simplificar a descoberta, a organização e o monitoramento de seus recursos do IAM. Você também pode etiquetar as identidades do IAM para controlar o acesso a recursos ou etiquetar a si mesmo. Para saber mais sobre como usar tags para controlar o acesso, consulte Controle de acesso para usuários e funções do IAM usando etiquetas.
Onde você pode usar variáveis de política
Você pode usar variáveis de política no elemento Resource e em comparações de string no elemento Condition.
Elemento de recurso
É possível usar uma variável de política no elemento Resource, mas somente na parte de recurso do ARN. Essa parte do ARN aparece após o quinto sinal de dois pontos (:). Não é possível usar uma variável para substituir partes do ARN antes do quinto sinal de dois pontos, como o serviço ou a conta. Para obter mais informações sobre o formato do ARN, consulte ARNs do IAM.
Para substituir parte de um ARN com um valor de tag, coloque o prefixo e o nome da chave com ${ }. Por exemplo, o elemento de Recurso a seguir se refere apenas a um bucket com o mesmo nome do valor na tag do usuário de solicitação.
"Resource":
["arn:aws::s3:::bucket/${aws:PrincipalTag/department}"]
Muitos recursos da AWS usam ARNs que contêm um nome criado pelo usuário. A política do IAM a seguir garante que somente os usuários pretendidos com valores de tag access-project, access-application e access-environment correspondentes possam modificar seus recursos. Além disso, usando correspondências curingas *, eles podem permitir sufixos de nomes de recursos personalizados.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowAccessBasedOnArnMatching", "Effect": "Allow", "Action": [ "sns:CreateTopic", "sns:DeleteTopic"], "Resource": ["arn:aws:sns:*:*:${aws:PrincipalTag/access-project}-${aws:PrincipalTag/access-application}-${aws:PrincipalTag/access-environment}-*" ] } ] }
Elemento de condição
É possível usar uma variável de política para valores Condition em qualquer condição que envolva os operadores de string ou os operadores de ARN. Os operadores de string incluem StringEquals, StringLike e StringNotLike. Os operadores de ARN incluem ArnEquals e ArnLike. Não é possível usar uma variável de política com outros operadores, como os operadores Numeric, Date, Boolean, Binary, IP Address ou Null. Para obter mais informações sobre operadores de condição, consulte Elementos de política JSON do IAM: operadores de condição.
Ao fazer referência a uma tag em uma expressão do elemento Condition, use o prefixo relevante e o nome da chave de condição. Em seguida, use o valor que você deseja testar no valor da condição.
Por exemplo, o exemplo de política a seguir permite acesso total aos usuários, mas apenas se a tag costCenter estiver anexada ao usuário. A tag também deve ter um valor de 12345 ou 67890. Se a tag não tiver valor, ou qualquer outro valor, a solicitação falhará.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iam:*user*" ], "Resource": "*", "Condition": { "StringLike": { "iam:ResourceTag/costCenter": [ "12345", "67890" ] } } } ] }
Variáveis de política sem valor
Quando as variáveis de política fazem referência a uma chave de contexto de condição que não tem valor ou não está presente em um contexto de autorização para uma solicitação, o valor é efetivamente nulo. Não há valor igual ou semelhante. As chaves de contexto de condição podem não estar presentes no contexto de autorização quando:
-
Você está usando chaves de contexto de condição específicas do serviço em solicitações a recursos que não oferecem suporte a essa chave de condição.
-
As etiquetas em entidades principais, sessões, recursos ou solicitações do IAM não estão presentes.
-
Outras circunstâncias, conforme listadas para cada chave de contexto de condição global em Chaves de contexto de condição globais da AWS.
Quando você usa uma variável sem valor no elemento de condição de uma política do IAM, Elementos de política JSON do IAM: operadores de condição como StringEquals ou StringLike não tem correspondência, e a instrução de política não entra em vigor.
Operadores de condição invertida como StringNotEquals ou StringNotLike correspondem a um valor nulo, pois o valor da chave de condição que serve de base para o teste não é igual ou semelhante ao valor efetivamente nulo.
Neste exemplo, aws:principaltag/Team deve ser igual a s3:ExistingObjectTag/Team para permitir o acesso. O acesso é explicitamente negado quando não aws:principaltag/Team está definido. Se uma variável sem valor no contexto de autorização for usada como parte do elemento Resource ou NotResource de uma política, o recurso que inclui uma variável de política sem valor não corresponderá a nenhum recurso.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Deny", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::/example-bucket/*", "Condition": { "StringNotEquals": { "s3:ExistingObjectTag/Team": "${aws:PrincipalTag/Team}" } } } ] }
Solicitar informações que você pode usar para variáveis de política
É possível usar o elemento Condition de uma política JSON para comparar chaves no contexto da solicitação com os valores de chave especificados na política. Quando você usa uma variável de política, a AWS substitui um valor da chave de contexto de solicitação no lugar da variável na política.
Valores de chave de principal
Os valores de aws:username, aws:userid e aws:PrincipalType dependem do tipo de principal que iniciou a solicitação. Por exemplo, a solicitação pode ser feita usando as credenciais de um usuário do IAM, um perfil do IAM ou o Usuário raiz da conta da AWS. A seguinte lista mostra valores para essas chaves de diferentes tipos de entidades principais.
| Entidade principal | aws:username |
aws:userid |
aws:PrincipalType |
|---|---|---|---|
| Usuário raiz da conta da AWS | (não está presente) | ID da Conta da AWS | Account |
| IAM user (Usuário do IAM) | IAM-user-name |
ID exclusivo | User |
| Usuário federado | (não está presente) | conta:caller-specified-name |
FederatedUser |
| Usuário federado OIDC Para obter informações sobre as chaves de política que estão disponíveis ao usar federação de identidades da web, consulte Chaves disponíveis para federação OIDC da AWS. |
(não está presente) |
em que |
AssumedRole |
| Usuário federado SAML Para obter informações sobre as chaves de política que estão disponíveis ao usar a federação SAML, consulte Identificar exclusivamente os usuários na federação baseada em SAML. |
(não está presente) |
em que |
AssumedRole |
| Função assumida | (não está presente) |
em que |
AssumedRole |
| Função atribuída a uma instância do Amazon EC2 | (não está presente) |
em que |
AssumedRole |
| Autor da chamada anônimo (somente Amazon SQS, Amazon SNS e Amazon S3) | (não está presente) | anonymous |
Anonymous |
Para os itens nesta tabela, observe o seguinte:
-
not present (não está presente) significa que o valor não está nas informações da solicitação atual, e que qualquer tentativa de correspondê-lo falhará e fará com que a instrução seja invalidada.
-
role-idé um identificador exclusivo atribuído a cada função na criação. É possível exibir o ID da função com o comando da AWS CLI:aws iam get-role --role-namerolename -
caller-specified-nameecaller-specified-role-namesão nomes que são passados pelo processo de chamada (como um aplicativo ou serviço) ao fazer uma chamada para obter credenciais temporárias. -
ec2-instance-idé um valor atribuído à instância quando ela é iniciada e aparece na página Instances (Instâncias) do console do Amazon EC2. Também é possível exibir o ID da instância executando o comando da AWS CLI:aws ec2 describe-instances
Informações disponíveis em solicitações para usuários federados
Usuários federados são usuários que são autenticados usando um sistema que não seja o IAM. Por exemplo, uma empresa pode ter uma aplicação para uso interno que faz chamadas para a AWS. Pode ser impraticável fornecer uma identidade do IAM para cada usuário corporativo que use o aplicativo. Em vez disso, a empresa pode usar um aplicativo proxy (camada intermediária) que tem uma única identidade do IAM ou a empresa pode usar um provedor de identidade (IdP) SAML. O aplicativo proxy ou IdP SAML autentica usuários individuais usando a rede corporativa. Um aplicativo proxy pode usar sua identidade do IAM para obter credenciais de segurança temporárias para usuários individuais. Um IdP SAML pode, efetivamente, trocar informações de identidade por credenciais de segurança temporárias da AWS. As credenciais de segurança temporárias podem ser usadas para acessar os recursos da AWS.
Da mesma forma, você pode criar uma aplicação para um dispositivo móvel no qual ela precise acessar os recursos da AWS. Nesse caso, você pode usar a federação OIDC, em que a aplicação autentica o usuário usando um provedor de identidades conhecido, como Login with Amazon, Amazon Cognito, Facebook ou Google. A aplicação pode então usar as informações de autenticação do usuário desses provedores para obter credenciais de segurança temporárias para acessar recursos da AWS.
A maneira recomendada de usar a federação OIDC é aproveitando as vantagens oferecidas pelo Amazon Cognito e os SDKs móveis da AWS. Para mais informações, consulte:
Caracteres especiais
Há algumas variáveis de políticas predefinidas especiais com valores fixos que permitem representar caracteres que, de outra forma, têm um significado especial. Se esses caracteres especiais fizerem parte da string, você estiver tentando estabelecer uma correspondência e os inseriu literalmente, eles seriam mal-interpretados. Por exemplo, inserir um asterisco * na string seria interpretado como curinga, fazendo correspondência com qualquer caractere, em vez de como um * literal. Nesses casos, você pode usar as seguintes variáveis de política predefinidas:
-
${*} - use quando precisar um asterisco (*).
-
${?} - use quando precisar de um ponto de interrogação (?).
-
${$} - use quando precisar de um caractere de cifrão ($).
Essas variáveis de política predefinidas podem ser usadas em qualquer string onde é possível usar variáveis de política normais.
Especificação de valores padrão
Para adicionar um valor padrão a uma variável, coloque o valor padrão entre aspas simples (' ') e separe o texto da variável e o valor padrão com uma vírgula e espaço (, ).
Por exemplo, se uma entidade principal estiver marcada com um team=yellow, é possível acessar o bucket do Amazon S3 da ExampleCorp's nomeado como DOC-EXAMPLE-BUCKET-yellow. Uma política com esse recurso permite que os membros da equipe acessem o bucket da própria equipe, mas não os de outras equipes. Para usuários sem etiquetas de equipe, ele define um valor padrão de company-wide para o nome do bucket. Esses usuários podem acessar somente o bucket DOC-EXAMPLE-BUCKET-company-wide, onde podem visualizar informações gerais, como instruções para ingressar em uma equipe.
"Resource":"arn:aws:s3:::DOC-EXAMPLE-BUCKET-${aws:PrincipalTag/team, 'company-wide'}"
Para obter mais informações
Para obter mais informações sobre políticas, consulte o seguinte:
