Visão geral das condições do IAM

Nesta página, descrevemos o recurso de condições do gerenciamento de identidade e acesso (IAM, na sigla em inglês). Este recurso permite que você defina e aplique o controle de acesso condicional e baseado em atributos para recursos do Google Cloud.

Com as Condições do IAM, é possível optar por conceder acesso aos recursos a identidades (membros) somente se as condições configuradas forem atendidas. Por exemplo, isso pode ser feito para configurar o acesso temporário para usuários no caso de um problema de produção ou para limitar o acesso a recursos somente para funcionários que fazem solicitações no escritório corporativo.

As condições são especificadas nas vinculações de papéis da política do IAM de um recurso. Quando uma condição existir, a solicitação de acesso só será concedida se a expressão condicional for avaliada como true. Cada expressão condicional é um conjunto de instruções lógicas, permitindo que você especifique um ou mais atributos a serem verificados.

Políticas do IAM com condições

As políticas do IAM consistem em uma ou mais vinculações de papéis, que têm a estrutura a seguir:

"bindings": [
  {
    "role": ...
    "members": ...
    "condition": ...
  },
  ...
]

O objeto condition é opcional, e cada vinculação de papel pode conter zero ou uma condição. Se uma vinculação de papel não tiver um objeto condition, os membros nessa vinculação de papel sempre terão o papel especificado no recurso.

O objeto condition tem a seguinte estrutura:

"condition": {
    "title": ...
    "description": ...
    "expression": ...
}

O title da condição é obrigatório, mas o description é opcional. Tanto o título quanto a descrição são campos puramente informativos para ajudá-lo a identificar e descrever a condição.

O campo expression é obrigatório. Ele define uma expressão lógica baseada em atributo usando um subconjunto da Common Expression Language (CEL). A CEL é explicada em mais detalhes na seção abaixo. A condição expression pode conter várias instruções, cada uma usando um atributo, e as instruções são combinadas usando operadores lógicos, seguindo a especificação da linguagem CEL.

Para saber como adicionar, modificar e remover vinculações de papéis condicionais, veja Como gerenciar vinculações de papéis condicionais.

CEL para condições

Common Expression Language, ou CEL, é a linguagem de expressão usada para especificar uma expressão na condição do IAM. Ela é personalizada para expressar expressões lógicas baseadas em atributos. Para saber mais, veja a especificação da CEL e a respectiva definição de linguagem.

Nas condições do IAM, um subconjunto da CEL é usado com a finalidade de conseguir decisões de autorização booleana com base nos dados do atributo. Em geral, uma expressão condicional consiste em uma ou mais instruções unidas por operadores lógicos (&&, || ou !). Cada instrução expressa uma regra de controle baseada em atributo que se aplica à vinculação de papéis e, por fim, determina se a autorização é permitida.

Veja abaixo os recursos de CEL mais importantes relacionados às condições:

  • Variáveis: as condições usam variáveis para expressar um determinado atributo, como request.time (do tipo carimbo de data/hora) ou resource.name (do tipo string). Essas variáveis são preenchidas com valor com base no contexto no ambiente de execução.
  • Operadores: cada tipo de dados, como carimbo de data/hora ou string, é compatível com um conjunto de operadores que podem ser usados para criar uma expressão lógica. Geralmente, os operadores são usados para comparar o valor contido em uma variável com um valor literal, como resource.service == "compute.googleapis.com". Neste exemplo, se o valor de entrada de resource.service for compute.googleapis.com, a expressão será avaliada como true.
  • Funções: uma função é um operador "composto" para tipos de dados compatíveis com operações mais complexas. Em expressões condicionais, existem funções predefinidas que podem ser usadas em conjunto com um determinado tipo de dados. Por exemplo, request.path.startsWith("/finance") usa uma função de correspondência de prefixo de string e avalia como true se o valor de request.path contém um prefixo correspondente, como "/finance".
  • Operadores lógicos: as condições são compatíveis com três operadores lógicos que podem ser usados para criar expressões lógicas complexas a partir de instruções de expressões simples: &&, || e !. Esses operadores lógicos possibilitam o uso de muitas variáveis de entrada em uma expressão condicional. Por exemplo: request.time.getFullYear() < 2020 && resource.service == "compute.googleapis.com" une duas instruções simples e exige que ambas sejam atendidas para produzir um resultado geral de avaliação true.

Saiba mais sobre variáveis, operadores e funções compatíveis na referência do atributo.

Atributos de condição

Os atributos de condição são baseados no recurso solicitado (por exemplo, seu tipo ou nome) ou em detalhes sobre a solicitação (por exemplo, carimbo de data/hora, endereço IP de origem ou de destino da instância de máquina virtual de destino do Compute Engine). Veja abaixo exemplos de expressões que usam esses atributos.

Atributos de recurso

Os atributos de recurso permitem criar condições que avaliam o recurso na solicitação de acesso, incluindo o tipo de recurso, o nome dele e o serviço do Google Cloud que está sendo usado.

Veja uma lista completa de atributos de recursos na Referência de atributos de recursos.

Saiba como usar atributos de recursos para configurar o acesso baseado em recursos em Como configurar o acesso baseado em recursos.

Exemplos de expressões

Permitir acesso a instâncias de VMs do Compute Engine, mas nenhum outro tipo de recurso:

resource.type == "compute.googleapis.com/Instance"

Permite acesso a recursos do Cloud Storage, mas não a outros recursos do serviço:

resource.service == "storage.googleapis.com"

Permitir acesso apenas a recursos com nomes que iniciam com uma string de prefixo especificada:

resource.name.startsWith("projects/_/buckets/exampleco-site-assets-")

Atributos de solicitação

Os atributos de solicitação permitem criar condições que avaliam detalhes sobre a solicitação, como data/hora, host/caminho de URL esperado (para IAP), endereço IP de destino e porta (para o tunelamento de TCP do IAP) ou nível de acesso.

Exemplo de expressões de data/hora

Permitir acesso temporariamente até uma data/hora de validade especificada:

request.time < timestamp("2021-01-01T00:00:00Z")

Permitir acesso apenas durante o horário de trabalho especificado, com base no fuso horário de Berlim, na Alemanha:

request.time.getHours("Europe/Berlin") >= 9 &&
request.time.getHours("Europe/Berlin") <= 17 &&
// Days of the week range from 0 to 6, where 0 == Sunday and 6 == Saturday.
request.time.getDayOfWeek("Europe/Berlin") >= 1 &&
request.time.getDayOfWeek("Europe/Berlin") <= 5

Permitir acesso apenas para um mês e um ano específicos, com base no fuso horário de Berlim, na Alemanha:

request.time.getFullYear("Europe/Berlin") == 2020
request.time.getMonth("Europe/Berlin") < 6

Para especificar um carimbo de data/hora, use o formato RFC 3339. Para especificar um fuso horário, use os identificadores do banco de dados de fuso horário da IANA.

Saiba mais sobre expressões de data e hora na especificação da CEL.

Saiba como usar expressões de data/hora para configurar o acesso temporário em Como configurar o acesso temporário.

Exemplos de expressões de host/caminho de URL (para o IAP)

Permite acesso apenas a determinados subdomínios ou caminhos de URL na solicitação:

request.host == "hr.example.com"
request.host.endsWith(".example.com")
request.path == "/admin/payroll.js"
request.path.startsWith("/admin")

Exemplo de expressões de IP/porta de destino (para o tunelamento de TCP do IAP)

Permitir acesso a determinado IP ou porta de destino na solicitação:

destination.ip == "14.0.0.1"
destination.ip != "127.0.0.1"
destination.port == 22
destination.port > 21 && destination.port <= 23

Exemplo de expressão de nível de acesso (somente para IAP)

Permitir acesso somente se a solicitação atingir um nível de acesso definido pela organização. No exemplo a seguir, a organização definiu um nível de acesso, CorpNet, que limita o acesso ao intervalo de endereços IP em que o tráfego entra e sai de uma rede corporativa:

"accessPolicies/199923665455/accessLevels/CorpNet" in
request.auth.access_levels

Os níveis de acesso são definidos pela sua organização. Eles são atribuídos com base nos atributos da solicitação, como o endereço IP de origem, os atributos do dispositivo, a hora do dia e muito mais. Saiba mais sobre os níveis de acesso na documentação do Access Context Manager.

Exemplo de expressões de regra de encaminhamento

Permitir o acesso de um membro se a solicitação não estiver criando uma regra de encaminhamento ou se a solicitação estiver criando uma regra de encaminhamento para um balanceador de carga interno do Google Cloud:

!compute.isForwardingRuleCreationOperation() || (
  compute.isForwardingRuleCreationOperation() &&
  compute.matchLoadBalancingSchemes([
    'INTERNAL', 'INTERNAL_MANAGED', 'INTERNAL_SELF_MANAGED'
  ]))
)

Para mais detalhes sobre esquemas de balanceamento de carga, consulte Como usar condições do IAM em balanceadores de carga do Google Cloud.

Exemplo de expressão com diferentes tipos de atributos

Permitir acesso quando a solicitação é feita durante um horário específico, correspondendo a um prefixo de nome de recurso, com o nível de acesso pretendido e para um tipo de recurso específico:

request.time > timestamp("2018-08-03T16:00:00-07:00") &&
request.time < timestamp("2018-08-03T16:05:00-07:00") &&
((resource.name.startsWith("projects/project-123/zones/us-east1-b/instances/dev") ||
 (resource.name.startsWith("projects/project-123/zones/us-east1-b/instances/prod") &&
  "accessPolicies/34569256/accessLevels/CorpNet" in request.auth.access_levels)) ||
 resource.type != "compute.googleapis.com/Instance")

Recursos que aceitam vinculações de papéis condicionais

É possível adicionar condições às políticas do IAM para os seguintes tipos de recursos do Google Cloud:

Serviço do Google Cloud Tipos de recurso
Cloud Storage Buckets1
Compute Engine
  • Serviços de back-end globais
  • Serviços de back-end regionais
  • Firewalls
  • Imagens
  • Modelos de instância
  • Instâncias
  • Discos permanentes regionais
  • Discos permanentes por zona
  • Snapshots
Identity-Aware Proxy (IAP)
  • Túneis
  • Instâncias de túnel
  • Zonas de túnel
  • Todos os serviços da Web
  • Serviços da Web individuais
  • Tipos de serviços da Web
  • Versões dos serviços da Web
Cloud Key Management Service (Cloud KMS)
  • Chaves de criptografia
  • Versões de chaves de criptografia
  • Keyrings
Resource Manager
  • Organizações
  • Projetos
Secret Manager
  • Secrets
  • Versões de secret
1. É possível usar o resource.name atributo em uma condição para referir-se a objetos em buckets do Cloud Storage. No entanto, é preciso adicionar a condição à política do IAM para um recurso de nível superior, como o bucket ou o projeto.

Outros tipos de recursos não permitem condições nas políticas do IAM. No entanto, é possível adicionar vinculações de papéis condicionais no nível da organização ou do projeto, e outros recursos herdarão essas vinculações por meio da hierarquia de recursos.

Para saber quais atributos afetam quais tipos de recursos, veja a referência do atributo.

Limitações conhecidas

As seguintes limitações se aplicam às condições do IAM:

  • Conforme descrito nos detalhes sobre os serviços compatíveis nesta página, você só pode adicionar condições a vinculações de papéis em alguns serviços do Google Cloud. Além disso, a maioria dos atributos de condição é compatível com um número limitado de serviços.
  • Os papéis primários (roles/owner, roles/editor, roles/viewer) não são compatíveis. Se você tentar definir uma condição em uma vinculação de papel que use um papel primário, a operação setIamPolicy falhará.
  • Os valores de allUsers e allAuthenticatedUsers são tipos de membros incompatíveis em uma vinculação de papéis condicional. Se você especificar um desses tipos de membros, a operação setIamPolicy falhará.
  • Recomendamos que cada política não contenha mais de 100 vinculações de papéis condicionais. Há um limite de tamanho de armazenamento subjacente para uma política. As políticas que envolvem muitas vinculações de papéis condicionais podem exceder o limite de tamanho e ser rejeitadas.
  • Recomendamos que você defina apenas algumas vinculações de papéis condicionais diferentes para o mesmo membro para o mesmo papel (condições diferentes). No entanto, você pode incluir no máximo 20 vinculações de papéis para o mesmo papel e o mesmo membro. Se você exceder esse número, a operação setIamPolicy falhará.
  • É possível usar no máximo 12 operadores lógicos em uma expressão de condição. Se você exceder esse número, a operação setIamPolicy falhará.

A seguir