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). Use as condições do IAM para definir e aplicar o controle de acesso condicional e baseado em atributos para recursos do Google Cloud.

Condições e tipos de política

Você pode usar condições nos seguintes lugares:

  • Permitir políticas
  • Políticas de negação
  • Vinculações de políticas para políticas de limite de acesso principal

As seções a seguir descrevem como usar condições em cada um desses lugares para aplicar o controle de acesso baseado em atributos.

Condições nas políticas de permissão

É possível usar condições nas políticas de permissão para conceder acesso aos principais somente se as condições especificadas forem atendidas. Por exemplo, é possível conceder acesso temporário aos usuários para que eles resolvam um problema de produção, ou conceder acesso somente a funcionários que fazem solicitações na rede corporativa.

As condições são especificadas nas vinculações de papéis da política de permissão de um recurso. Se uma vinculação de função tiver uma condição, os principais na função só receberão a função se a expressão condicional for avaliada como true.

Para adicionar uma condição a uma vinculação de função, defina o campo condition:

"bindings": [
  {
    "role": "ROLE",
    "members": [
      "MEMBER_1",
      "MEMBER_2"
    ],
    "condition": {
      "title": "TITLE",
      "description": "DESCRIPTION",
      "expression": "EXPRESSION"
    }
  }
]

Para saber mais sobre os campos em uma condição, consulte Estrutura de condição nesta página.

Apenas alguns tipos de recurso aceitam condições em vinculações de papéis. No entanto, é possível conceder acesso condicional a outros tipos de recursos concedendo papéis no nível da organização ou do projeto.

Como prática recomendada, não adicione mais de 100 vinculações de papéis condicionais a uma única política de permissão. Se você usar um número maior de vinculações de papéis condicionais, poderá exceder o limite de tamanho geral das políticas de permissão.

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

Condições nas políticas de negação

É possível usar condições em políticas de negação para aplicar uma regra de negação somente se uma determinada condição for atendida. Por exemplo, você pode negar uma permissão somente se o recurso que o principal está tentando acessar estiver marcado como parte do ambiente prod.

As condições são especificadas nas regras de negação nas políticas de negação de um recurso. Se a condição for avaliada como true ou não puder ser avaliada, a regra de negação será aplicada e os principais não poderão usar as permissões especificadas. Se a condição for avaliada como false, a regra de negação não se aplicará e os principais poderão usar as permissões especificadas, se houver.

Para adicionar uma condição a uma regra de proibição, defina o campo denialCondition:

"rules": [
  {
    "denyRule": {
      "deniedPrincipals": [
        "PRINCIPAL_1",
        "PRINCIPAL_2"
      ],
      "exceptionPrincipals": [
        "EXCEPTION_PRINCIPAL_1",
        "EXCEPTION_PRINCIPAL_2"
      ],
      "deniedPermissions": [
        "DENIED_PERMISSION_1",
        "DENIED_PERMISSION_2"
      ],
      "denialCondition": {
        "title": "TITLE",
        "description": "DESCRIPTION",
        "expression": "EXPRESSION"
      }
    }
  }
]

Para saber mais sobre os campos em uma condição, consulte Estrutura de condição nesta página.

Para saber como criar e gerenciar políticas de negação, consulte Negar acesso.

Condições nas vinculações de políticas de limite de acesso principal

É possível usar condições em vinculações de políticas para políticas de limite de acesso principal para refinar o conjunto de principais ao qual a política de limite de acesso é aplicável. Por exemplo, você só pode aplicar uma política para contas de serviço ou isentar super-admin@example.com de uma política.

As condições são especificadas em cada vinculação de política. Se uma vinculação de política tiver uma condição, ela só será aplicada se a condição for avaliada como true.

Para adicionar uma condição a uma vinculação de política, defina o campo condition na vinculação de política:

{
  "displayName": "DISPLAY_NAME",
  "target": {
    "principalSet": "PRINCIPAL_SET"
  },
  "policyKind": "PRINCIPAL_ACCESS_BOUNDARY",
  "policy": "PAB_POLICY",
  "condition": {
    "title": "TITLE",
    "description": "DESCRIPTION",
    "expression": "EXPRESSION"
  }
}

Para saber mais sobre os campos em uma condição, consulte Estrutura de condição nesta página.

Para saber como criar vinculações de políticas para políticas de limite de acesso principal, consulte Aplicar uma política de limite de acesso principal a um conjunto de principais.

Estrutura da condição

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 expressão de condição pode conter várias instruções. cada declaração avalia um atributo. As instruções são combinadas usando operadores lógicos, seguindo a especificação da linguagem CEL.

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 para tomar 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 e, por fim, determina se a vinculação de papéis, a regra de negação ou a vinculação de políticas é aplicável.

As condições do IAM usam os seguintes recursos de CEL:

  • 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 de tipos de dados compatíveis com operações mais complexas. Em expressões condicionais, existem funções predefinidas que podem ser usadas 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 báicas: &&, || 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 básicas 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, o tipo ou nome) ou em detalhes sobre a solicitação, por exemplo, carimbo de data/hora ou endereço IP de destino.

Os atributos de condição que podem ser usados em uma expressão de condição dependem do tipo de política em que você está escrevendo condições. Para uma lista completa de atributos de condição e mais informações sobre os atributos aceitos para cada tipo de política, consulte a referência de atributo.

As seções a seguir mostram exemplos de alguns dos atributos que podem ser usados em condições.

Atributos de recurso

É possível usar atributos de recurso para gravar condições que avaliam o recurso na solicitação de acesso. Os atributos que podem ser avaliados incluem os seguintes:

  • O tipo de recurso
  • O nome do recurso
  • O serviço do Google Cloud que está sendo usado
  • As tags anexadas ao recurso

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

Em uma vinculação de função, a expressão de condição a seguir permite acesso a instâncias de VM do Compute Engine, mas não a outros tipos de recursos:

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

Em uma vinculação de função, a expressão de condição a seguir permite acesso a recursos do Cloud Storage, mas não a outros recursos do serviço:

resource.service == 'storage.googleapis.com'

Em uma vinculação de função, a expressão de condição a seguir permite o acesso apenas a objetos do Cloud Storage em um bucket específico:

resource.type == 'storage.googleapis.com/Object' &&
resource.name.startsWith('projects/_/buckets/exampleco-site-assets/')

Em uma regra de negação, a expressão de condição a seguir nega o acesso a recursos do Google Cloud que têm a tag env: prod:

resource.matchTag('123456789012/env', 'prod')

Atributos principais

Os atributos principais permitem gravar condições com base no principal que escreveu a solicitação. Os atributos que podem ser avaliados incluem o seguinte:

  • O tipo de principal na solicitação
  • A identidade do principal na solicitação

Para saber mais, consulte a referência do atributo de condições.

Exemplos de expressões

Em uma vinculação de política de limite de acesso de principal, a expressão de condição a seguir garante que a política na vinculação seja aplicada apenas para contas de serviço:

principal.type == 'iam.googleapis.com/ServiceAccount'

Em uma vinculação de política de limite de acesso de principal, a expressão de condição a seguir garante que a política na vinculação não seja aplicada para super-admin@example.com:

principal.subject != 'super-admin@example.com'

Atributos de solicitação

Use atributos de solicitação para gravar condições que avaliem detalhes sobre a solicitação, como os seguintes:

  • O nível de acesso
  • A data e a hora
  • O endereço IP e a porta de destino (para o tunelamento de TCP do IAP)
  • O host ou caminho do URL esperado (para o IAP)

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

No exemplo a seguir, a organização define 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. Em seguida, adicione a seguinte expressão de condição a uma vinculação de papel para permitir o acesso somente se a solicitação atender ao nível de acesso CorpNet:

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

A organização define os níveis de acesso 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. Para mais detalhes, consulte a documentação do Access Context Manager.

Exemplo de expressão do atributo de API

Em uma vinculação de função para uma função com a permissão iam.projects.setIamPolicy, a expressão de condição a seguir permite que um usuário conceda e revogue apenas a função de administrador da conta de faturamento (roles/billing.admin) no projeto:

api.getAttribute('iam.googleapis.com/modifiedGrantsByRole', [])
                 .hasOnly(['roles/billing.admin'])

Para saber mais sobre o uso de atributos de API para limitar a concessão de papéis, consulte Como definir limites ao conceder papéis.

Exemplo de expressões de data/hora

Em uma vinculação de função, a expressão de condição a seguir permite o acesso até a meia-noite de 1º de janeiro de 2021:

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

Em uma vinculação de função, a expressão de condição a seguir permite 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') <= '

Em uma vinculação de função, a expressão de condição a seguir permite acesso apenas em junho de 2020, 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.

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

Em uma vinculação de função, a expressão de condição a seguir permite o acesso a um endereço IP de destino interno ou número de porta:

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

Exemplo de expressões de regra de encaminhamento

Em uma vinculação de função, a expressão de condição a seguir permite o acesso de um principal se a solicitação não estiver criando uma regra de encaminhamento ou se ela 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.

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

Em uma vinculação de função, a expressão de condição a seguir 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ão com diferentes tipos de atributos

Em uma vinculação de função, a expressão de condição a seguir permite acesso se a solicitação for feita durante um horário específico, correspondendo a um prefixo de nome de recurso, com o nível de acesso escolhido 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')

A seguir