# 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.](reference_policies_elements_condition_operators.md#Conditions_IfExists) **Topics** + [Introdução](#policy-vars-intro) + [Usar variáveis em políticas](#policy-vars-using-variables) + [Tags como variáveis de política](#policy-vars-tags) + [Onde você pode usar variáveis de política](#policy-vars-wheretouse) + [Variáveis de política sem valor](#policy-vars-no-value) + [Solicitar informações que você pode usar para variáveis de política](#policy-vars-infotouse) + [Especificação de valores padrão](#policy-vars-default-values) + [Para obter mais informações](#policy-vars-formoreinfo) ## 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 `amzn-s3-demo-bucket` para projetos de `marketing`. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": ["arn:aws:s3:::amzn-s3-demo-bucket"], "Condition": {"StringLike": {"s3:prefix": ["marketing/*"]}} }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject" ], "Resource": ["arn:aws:s3:::amzn-s3-demo-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](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) e [políticas de endpoint da VPC](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html). 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 [https://docs.aws.amazon.com/service-authorization/latest/reference/reference.html](https://docs.aws.amazon.com/service-authorization/latest/reference/reference.html). 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html). **Importante** Os nomes das chaves não diferenciam maiúsculas de minúsculas. Por exemplo, `aws:CurrentTime` equivale a `AWS: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. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": ["arn:aws:s3:::amzn-s3-demo-bucket"], "Condition": {"StringLike": {"s3:prefix": ["${aws:PrincipalTag/team}/*"]}} }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject" ], "Resource": ["arn:aws:s3:::amzn-s3-demo-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*](reference_policies_condition-keys.md#condition-keys-principaltag) 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](reference_policies_elements_version.md). Para saber mais sobre as versões de política, consulte [Versionamento de políticas do IAM](access_policies_managed-versioning.md). Uma política que permite que uma entidade principal obtenha objetos do caminho /David de um bucket do S3 tem a seguinte aparência: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-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. ------ #### [ JSON ] **** ``` { "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. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowOnlyDeptS3Prefix", "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-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 [Tags para recursos do AWS Identity and Access Management](id_tags.md). 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](https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/tag-editor.html) no *Console de gerenciamento da AWS 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](access_iam-tags.md). ## Onde você pode usar variáveis de política É possível usar variáveis de política no elemento `Resource` e em comparações de string no elemento `Condition`. ### Elemento de recursos É 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](reference_identifiers.md#identifiers-arns). 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:::amzn-s3-demo-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 \$1](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_resource.html), eles podem permitir sufixos de nomes de recursos personalizados. ------ #### [ JSON ] **** ``` { "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](reference_policies_elements_condition_operators.md). 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á. ------ #### [ JSON ] **** ``` { "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 [AWSChaves de contexto de condições globais da](reference_policies_condition-keys.md). 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](reference_policies_elements_condition_operators.md) 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. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Deny", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::amzn-s3-demo-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](reference_policies_evaluation-logic_policy-eval-reqcontext.md) 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](reference_identifiers.md#identifiers-unique-ids) | User | | Entidade principal de usuário federado do AWS STS | (não está presente) | conta:caller-specified-name | FederatedUser | | Entidade principal federada 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](reference_policies_iam-condition-keys.md#condition-keys-wif). | (não está presente) | *role-id*:*caller-specified-role-name* em que `role-id` é o [id exclusivo da função](reference_identifiers.md#identifiers-unique-ids) e caller-specified-role-name é especificado pelo [parâmetro RoleSessionName](https://docs.aws.amazon.com/IAM/latest/APIReference/API_AssumeRole.html#API_AssumeRoleWithWebIdentity_RequestParameters) passado para a solicitação AssumeRoleWithWebIdentity. | AssumedRole | | Entidade principal federada 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](id_roles_providers_saml.md#CreatingSAML-userid). | (não está presente) | *role-id*:*caller-specified-role-name* em que `role-id` corrresponde ao [id exclusivo da função](reference_identifiers.md#identifiers-unique-ids) e o nome da função especificado pelo autor da chamada é especificado pelo elemento de atributo com o [atributo Name](id_roles_providers_create_saml_assertions.md) definido como https://aws.amazon.com/SAML/attributes/RoleSessionName. | AssumedRole | | Função assumida | (não está presente) | *role-id*:*caller-specified-role-name* em que `role-id` é o [id exclusivo da função](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-unique-ids) e caller-specified-role-name é especificado pelo [parâmetro RoleSessionName](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html#API_AssumeRole_RequestParameters) passado para a solicitação AssumeRole. | AssumedRole | | Função atribuída a uma instância do Amazon EC2 | (não está presente) | *role-id*:*ec2-instance-id* em que `role-id` é o [id exclusivo da função](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-unique-ids) e o ec2-instance-id é o [identificador exclusivo da instância do EC2](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstances.html). | 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-name rolename` + *caller-specified-name* e *caller-specified-role-name* sã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 entidades principais federadas Entidades principais federadas são usuários que são autenticados usando um sistema diferente do 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 saber mais, consulte: + [Guia do usuário do Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) + [Cenários comuns para credenciais temporárias](id_credentials_temp.md#sts-introduction) ### 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 \$1 na string seria interpretado como curinga, fazendo correspondência com qualquer caractere, em vez de como um \$1 literal. Nesses casos, você pode usar as seguintes variáveis de política predefinidas: + **\$1\$1\$1\$1** - use quando precisar um asterisco (\$1). + **\$1\$1?\$1** - use quando precisar de um ponto de interrogação (?). + **\$1\$1\$1\$1** - use quando precisar de um caractere de cifrão (\$1). 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 `amzn-s3-demo-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 `amzn-s3-demo-bucket-company-wide`, onde podem visualizar informações gerais, como instruções para ingressar em uma equipe. ``` "Resource":"arn:aws:s3:::amzn-s3-demo-bucket-${aws:PrincipalTag/team, 'company-wide'}" ``` ## Para obter mais informações Para obter mais informações sobre políticas, consulte o seguinte: + [Políticas e permissões no AWS Identity and Access Management](access_policies.md) + [Exemplos de políticas baseadas em identidade do IAM](access_policies_examples.md) + [Referência de elemento de política JSON do IAM](reference_policies_elements.md) + [Lógica da avaliação de política](reference_policies_evaluation-logic.md) + [Federação OIDC](id_roles_providers_oidc.md)