Elementos de política JSON do IAM: operadores de condição

Use operadores de condição no elemento Condition para corresponder a chave de condição e o valor na política aos valores no contexto da solicitação. Para obter mais informações sobre o elemento Condition, consulte Elementos de política JSON do IAM: Condition.

O operador de condição que você pode usar em uma política depende da chave de condição escolhida. É possível escolher uma chave de condição global ou uma chave de condição específica do serviço. Para saber qual operador de condição pode ser usado para uma chave de condição global, consulte Chaves de contexto de condição globais da AWS. Para saber qual operador de condição você pode usar para uma chave de condição específica de serviço, consulte Ações, recursos e chaves de condição para produtos da AWS e escolha o serviço que deseja visualizar.

Os operadores de condição podem ser agrupados nas seguintes categorias:

Operadores de condição de strings

Operadores de condição de string permitem que você construa elementos Condition que restringem o acesso com base na comparação de uma chave a um valor de string.

Por exemplo, a declaração a seguir contém um elemento Condition que usa a chave aws:PrincipalTag para especificar que a entidade principal que está fazendo a solicitação deve ser marcada com a categoria de trabalho iamuser-admin.

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": "iam:*AccessKey*",
    "Resource": "arn:aws:iam::account-id:user/*",
    "Condition": {"StringEquals": {"aws:PrincipalTag/job-category": "iamuser-admin"}}
  }
}

Se a chave especificada em uma condição de política não estiver presente no contexto de solicitação, os valores não corresponderão. Nesse exemplo, a chave aws:PrincipalTag/job-category estará presente no contexto da solicitação se a entidade de segurança estiver usando um usuário do IAM com etiquetas anexadas. Ela também será incluída para um principal usando uma função do IAM com tags anexadas ou tags de sessão. Se um usuário sem a tag tentar visualizar ou editar uma chave de acesso, a condição retornará false e a solicitação será implicitamente negada por essa declaração.

Você pode usar uma variável de política com o operador de condição String.

O exemplo a seguir usa o operador de condição StringLike para realizar correspondência de string com uma variável de política para criar uma política que permite a um usuário do IAM usar o console do Amazon S3 para gerenciar seu próprio “diretório base” em um bucket do Amazon S3. A política permite as ações especificadas em um bucket do S3, desde que o s3:prefix corresponda a qualquer um dos padrões especificados.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListAllMyBuckets",
        "s3:GetBucketLocation"
      ],
      "Resource": "arn:aws:s3:::*"
    },
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::amzn-s3-demo-bucket",
      "Condition": {"StringLike": {"s3:prefix": [
        "",
        "home/",
        "home/${aws:username}/"
      ]}}
    },
    {
      "Effect": "Allow",
      "Action": "s3:*",
      "Resource": [
        "arn:aws:s3:::amzn-s3-demo-bucket/home/${aws:username}",
        "arn:aws:s3:::amzn-s3-demo-bucket/home/${aws:username}/*"
      ]
    }
  ]
}

Para obter um exemplo de uma política que mostra como usar o elemento Condition para restringir o acesso a recursos com base em um ID de aplicação e um ID de usuário para a federação de OIDC, consulte Amazon S3: permite que usuários do Amazon Cognito acessem objetos em seus buckets.

Correspondência de curinga

Os operadores de condição de string realizam uma correspondência sem padrões que não impõe um formato predefinido. Os operadores de condição ARN e Date são um subconjunto de operadores de string que impõem uma estrutura no valor da chave de condição. Quando você usa os operadores StringLike ou StringNotLike para correspondências parciais de string de um ARN ou data, a correspondência ignora qual parte da estrutura está marcada como curinga.

Por exemplo, as condições a seguir pesquisam uma correspondência parcial de um ARN usando operadores de condição diferentes.

Quando o ArnLike é usado, as partes partição, serviço, ID da conta, tipo de recurso e ID parcial do recurso do ARN devem ter a correspondência exata com o ARN no contexto da solicitação. Somente a região e o caminho do recurso permitem a correspondência parcial.

"Condition": {"ArnLike": {"aws:SourceArn": "arn:aws:cloudtrail:*:111122223333:trail/*"}}

Quando StringLike é usado em vez de ArnLike, a correspondência ignora a estrutura do ARN e permite a correspondência parcial, independentemente da parte que foi marcada como curinga.

"Condition": {"StringLike": {"aws:SourceArn": "arn:aws:cloudtrail:*:111122223333:trail/*"}}

Operadores de condição numéricos

Operadores de condição numéricos permitem que você construa elementos Condition que restringem o acesso com base na comparação de uma chave a um número inteiro ou valor decimal.

Por exemplo, a seguinte instrução contém um elemento Condition que usa o operador de condição NumericLessThanEquals com a chave s3:max-keys para especificar que o solicitante pode listar até 10 objetos no amzn-s3-demo-bucket por vez.

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": "s3:ListBucket",
    "Resource": "arn:aws:s3:::amzn-s3-demo-bucket",
    "Condition": {"NumericLessThanEquals": {"s3:max-keys": "10"}}
  }
}

Se a chave especificada em uma condição de política não estiver presente no contexto de solicitação, os valores não corresponderão. Neste exemplo, a chave s3:max-keys está sempre presente na solicitação ao realizar a operação ListBucket. Se essa política permitisse todas as operações do Amazon S3, somente as operações que incluíssem a chave de contexto max-keys com um valor inferior ou igual a 10 seriam permitidas.

Você não pode usar uma variável de política com o operador de condição Numeric.

Operadores de condição de data

Operadores de condição de data permitem que você construa elementos Condition que restringem o acesso com base na comparação de uma chave a um valor de data/hora. Você pode usar esses operadores de condição com a chave aws:CurrentTime ou a chave aws:EpochTime. Você deve especificar os valores de data e hora com uma das implementações W3C dos formatos de hora ISO 8601 ou em data e hora epoch (UNIX).

Por exemplo, a declaração a seguir contém um elemento Condition que usa o operador de condição DateGreaterThan com a chave aws:TokenIssueTime. Esta condição especifica que as credenciais de segurança temporárias usadas para fazer a solicitação foram emitidas em 2020. Esta política pode ser atualizada de forma programática todos os dias para garantir que os membros da conta usem credenciais novas.

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": "iam:*AccessKey*",
    "Resource": "arn:aws:iam::account-id:user/*",
    "Condition": {"DateGreaterThan": {"aws:TokenIssueTime": "2020-01-01T00:00:01Z"}}
  }
}

Se a chave especificada em uma condição de política não estiver presente no contexto de solicitação, os valores não corresponderão. A chave aws:TokenIssueTime está presente no contexto da solicitação somente quando o principal usar as credenciais temporárias para realizar a solicitação. A chave não está presente em solicitações da AWS CLI, da API da AWS ou do AWS SDK que são feitas usando chaves de acesso. Neste exemplo, se um usuário do IAM tentar visualizar ou editar uma chave de acesso, a solicitação será negada.

Você não pode usar uma variável de política com o operador de condição Date.

Operadores de condição booliana

Operadores de condição boolianos permitem que você construa elementos Condition que restringem o acesso com base na comparação de uma chave a um "verdadeiro" ou "falso".

Por exemplo, essa política baseada em identidade usará o operador de condição Bool com a chave aws:SecureTransport para negar a replicação de objetos e tags de objetos para o bucket de destino e seu conteúdo se a solicitação não for por SSL.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BooleanExample",
      "Action": "s3:ReplicateObject",
      "Effect": "Deny",
      "Resource": [
        "arn:aws:s3:::amzn-s3-demo-bucket",
        "arn:aws:s3:::amzn-s3-demo-bucket/*"
      ],
      "Condition": {
        "Bool": {
          "aws:SecureTransport": "false"
        }
      }
    }
  ]
}

Se a chave especificada em uma condição de política não estiver presente no contexto de solicitação, os valores não corresponderão. O contexto da solicitação aws:SecureTransport retorna true ou false.

Você pode usar uma variável de política com o operador de condição Boolean.

Operadores de condição binários

O operador de condição BinaryEquals permite que você construa elementos Condition que testam valores de chave em formato binário. Ele compara o valor da chave especificada byte por byte à uma representação base-64 codificada do valor binário na política.

"Condition" : {
  "BinaryEquals": {
    "key" : "QmluYXJ5VmFsdWVJbkJhc2U2NA=="
  }
}     

Se a chave especificada em uma condição de política não estiver presente no contexto de solicitação, os valores não corresponderão.

Você não pode usar uma variável de política com o operador de condição Binary.

Operadores de condição de endereço IP

Operadores de condição de endereço IP permitem que você construa elementos Condition que restringem o acesso com base na comparação de uma chave a um endereço IPv4 ou IPv6 ou a intervalo de endereços IP. Você pode usá-los com a chave aws:SourceIp. O valor deve ser no formato CIDR padrão (por exemplo, 203.0.113.0/24 ou 2001: DB8:1234:5678::/64). Se você especificar um endereço IP, sem o prefixo de roteamento associado, o IAM usará o valor do prefixo padrão /32.

Alguns serviços da AWS oferecem suporte a IPv6, usando :: para representar um intervalo de 0s. Para saber se um serviço oferece suporte a IPv6, consulte a documentação do serviço.

Por exemplo, a instrução a seguir usa o operador de condição IpAddress com a chave aws:SourceIp para especificar que a solicitação deve partir de um intervalo de IP 203.0.113.0 a 203.0.113.255.

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": "iam:*AccessKey*",
    "Resource": "arn:aws:iam::account-id:user/*",
    "Condition": {"IpAddress": {"aws:SourceIp": "203.0.113.0/24"}}
  }
}

A chave de condição aws:SourceIp resulta no endereço IP onde a solicitação foi gerada. Se as solicitações for proveniente de uma instância do Amazon EC2, o aws:SourceIp será avaliado para o endereço IP público da instância.

Se a chave especificada em uma condição de política não estiver presente no contexto de solicitação, os valores não corresponderão. A chave aws:SourceIp está sempre presente no contexto da solicitação, exceto quando o solicitante usar um VPC endpoint para fazer a solicitação. Nesse caso, a condição retornará false e a solicitação será negada implicitamente por essa declaração.

Você não pode usar uma variável de política com o operador de condição IpAddress.

O exemplo a seguir mostra como combinar endereços IPv4 e IPv6 para cobrir todos os endereços IP válidos da sua organização. Recomendamos atualizar seus intervalos de endereço IPv6, além dos intervalos IPv4 que você já possui, nas políticas de sua organização para garantir que as políticas continuarão a funcionar à medida que você fizer a transição para o IPv6.

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": "someservice:*",
    "Resource": "*",
    "Condition": {
      "IpAddress": {
        "aws:SourceIp": [
          "203.0.113.0/24",
          "2001:DB8:1234:5678::/64"
        ]
      }
    }
  }
}

A chave de condição aws:SourceIp só funcionará em uma política JSON se você estiver chamando a API testada diretamente como um usuário. Se você usar um serviço para chamar o serviço de destino em seu nome, o serviço de destino vê o endereço IP do serviço de chamada, em vez do endereço IP do usuário-fonte. Isso pode acontecer, por exemplo, se você usar o AWS CloudFormation para chamar o Amazon EC2 para criar instâncias para você. Atualmente, não há como passar o endereço IP de origem através de um serviço de chamada ao serviço de destino para avaliação em uma política JSON. Para esses tipos de chamadas de serviço de API, não use a chave de condição aws:SourceIp.

Operadores de condição de nome do recurso da Amazon (ARN)

Operadores de condição do nome de recurso da Amazon (ARN) permitem que você construa elementos Condition que restringem o acesso com base na comparação de uma chave a um ARN. O ARN é considerado uma string.

Você pode usar uma variável de política com o operador de condição ARN.

O exemplo de política baseada em recurso a seguir mostra uma política anexada a uma fila do Amazon SQS para a qual você deseja enviar mensagens do SNS. Ela fornece ao Amazon SNS permissão para enviar mensagens para a fila (ou as filas) de sua escolha, mas apenas se o serviço estiver enviando as mensagens em nome de um determinado tópico (ou tópicos) do Amazon SNS. Você especifica a fila no campo Resource e o tópico do Amazon SNS como o valor para a chave SourceArn.

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Principal": {"AWS": "123456789012"},
    "Action": "SQS:SendMessage",
    "Resource": "arn:aws:sqs:REGION:123456789012:QUEUE-ID",
    "Condition": {"ArnEquals": {"aws:SourceArn": "arn:aws:sns:REGION:123456789012:TOPIC-ID"}}
  }
}

Se a chave especificada em uma condição de política não estiver presente no contexto de solicitação, os valores não corresponderão. A chave aws:SourceArn estará presente no contexto da solicitação somente se um recurso acionar um serviço para chamar outro serviço em nome do proprietário do recurso. Se um usuário do IAM tentar realizar essa operação diretamente, a condição retornará false e a solicitação será negada implicitamente por esta instrução.

Operadores de condição ...IfExists

Você pode adicionar IfExists ao final de qualquer nome de operador de condição, exceto a condição Null, por exemplo, StringLikeIfExists. Isso é feito para dizer "Se a chave de condição estiver presente no contexto da solicitação, processar a chave conforme especificado na política. Se a chave não estiver presente, avalie o elemento da condição como verdadeiro." Outros elementos de condição na instrução ainda podem resultar em um nonmatch, mas não em uma chave ausente quando marcada com ...IfExists. Se você estiver usando um elemento "Effect": "Deny" com um operador de condição negada como StringNotEqualsIfExists, a solicitação ainda será negada mesmo se a chave de condição estiver ausente.

Exemplo do uso de IfExists

Muitas chaves de condição descrevem informações sobre determinado tipo de recurso e existem apenas ao acessar aquele tipo de recurso. Essas chaves de condição não estão presentes em outros tipos de recursos. Isso não causa problemas quando a declaração de política se aplica a apenas um tipo de recurso. No entanto, há casos em que uma única instrução pode se aplicar a vários tipos de recursos, tal como quando a declaração de política se refere a ações de múltiplos serviços ou quando dada ação de um serviço acessa diversos tipos de recursos dentro do mesmo serviço. Em tais casos, a inclusão de uma chave de condição que se aplica a apenas um dos recursos na declaração de política pode fazer com que o elemento Condition na declaração de política falhe de forma que o "Effect" da instrução não se aplica.

Por exemplo, considere o exemplo de política:

{
  "Version": "2012-10-17",
  "Statement": {
    "Sid": "THISPOLICYDOESNOTWORK",
    "Effect": "Allow",
    "Action": "ec2:RunInstances",
    "Resource": "*",
    "Condition": {"StringLike": {"ec2:InstanceType": [
      "t1.*",
      "t2.*",
      "m3.*"
    ]}}
  }
}

O objetivo da política anterior é permitir que o usuário execute qualquer instância do tipo t1, t2 ou m3. No entanto, iniciar uma instância na prática requer acesso a muitos recursos, além da própria instância; por exemplo, imagens, pares de chaves, grupos de segurança, entre outros. A instrução completa é avaliada em relação a cada recurso necessário para executar a instância. Esses recursos adicionais não têm a ec2:InstanceType chave de condição, de modo que a verificação StringLike falha e o usuário não é concedido a capacidade de executar qualquer tipo de instância.

Para resolver isso, use o operador de condição StringLikeIfExists. Dessa forma, o teste só acontece se a chave de condição existir. Você pode ler a política a seguir como: “Se o recurso que está sendo verificado tiver uma chave de condição ‘ec2:InstanceType‘, permita a ação apenas se o valor de chave começar com t1., t2. ou m3.. Se o recurso que está sendo verificado não tiver essa chave de condição, não se preocupe com isso." O asterisco (*) nos valores da chave de condição, quando usado com o operador de condição StringLikeIfExists, é interpretado como um curinga para obter correspondências parciais de strings. A instrução DescribeActions inclui as ações necessárias para visualizar a instância no console.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "RunInstance",
            "Effect": "Allow",
            "Action": "ec2:RunInstances",
            "Resource": "*",
            "Condition": {
                "StringLikeIfExists": {
                    "ec2:InstanceType": [
                        "t1.*",
                        "t2.*",
                        "m3.*"
             ]}}
        },
        {
            "Sid": "DescribeActions",
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeImages",
                "ec2:DescribeInstances",
                "ec2:DescribeVpcs",
                "ec2:DescribeKeyPairs",
                "ec2:DescribeSubnets",
                "ec2:DescribeSecurityGroups"
            ],
            "Resource": "*"
        }]
}

Operador de condição para verificar a existência de chaves de condição

Use um operador de condição Null para verificar se uma chave de condição não está presente no momento da autorização. Na instrução de política, use true (a chave não existe, é nulo) ou false (a chave existe e seu valor não é nulo).

Você não pode usar uma variável de política com o operador de condição Null.

Por exemplo, você pode usar esse operador de condição para determinar se um usuário está usando suas próprias credenciais para a operação ou credenciais temporárias. Se o usuário estiver usando credenciais temporárias, a chave aws:TokenIssueTime existe e tem um valor. O exemplo a seguir mostra uma condição que afirma que o usuário não deve usar credenciais temporárias (a chave não deve existir) para que o usuário use a API do Amazon EC2.

{
  "Version": "2012-10-17",
  "Statement":{
      "Action":"ec2:*",
      "Effect":"Allow",
      "Resource":"*",
      "Condition":{"Null":{"aws:TokenIssueTime":"true"}}
  }
}