Controlar o acesso a sessões com as condições do IAM

Por padrão, as permissões do Identity and Access Management das sessões são para envolvidos no projeto. Neste documento, descrevemos como usar as Condições do IAM para controlar o acesso mais granular aos recursos de sessões da plataforma de agentes.

Visão geral

As condições do IAM permitem conceder acesso aos recursos de sessão e de evento de sessão somente se as condições especificadas forem atendidas. É possível controlar o acesso a sessões com base na string userId no recurso de sessão usando o atributo de API aiplatform.googleapis.com/sessionUserId com uma expressão escrita em Common Expression Language. O ID do usuário é uma string arbitrária fornecida ao criar sessões, como userId = "userA".

Essas políticas condicionais do Identity and Access Management são criadas no nível do projeto e se aplicam a todas as sessões e eventos de sessão em um projeto. É possível aplicar condições do IAM a todos os tipos de principais, incluindo usuários do projeto e contas de serviço.

As condições do IAM são úteis para conceder permissões do Identity and Access Management (IAM) a muitos recursos de sessão relacionados ao mesmo tempo, incluindo aqueles que ainda não existem. É possível restringir o acesso às sessões e aos eventos para que um usuário só possa acessar as próprias informações ou para que os desenvolvedores só possam visualizar determinados recursos de sessão sem concessões de permissão especiais.

Antes de começar

Para configurar políticas condicionais do Identity and Access Management para sessões e eventos de sessão, faça o seguinte:

  • Revise as condições do IAM: familiarize-se com a visão geral das condições do IAM.
  • Determine os papéis necessários: identifique quais papéis especializados do IAM de sessão são adequados para seu caso de uso para garantir o princípio de privilégio mínimo.
  • Identificar os principais afetados: identifique quem na sua organização deve receber quais permissões. Por exemplo, considere o seguinte:
    • Os usuários devem poder ver as sessões de outros usuários?
    • Os desenvolvedores devem poder ver todas as sessões?
    • Os administradores do projeto devem poder ver todas as sessões?
    • Algumas identidades de agente devem ter acesso a determinadas sessões?
  • Conceder papéis do IAM: verifique se você tem os papéis necessários que contêm as permissões necessárias para realizar as tarefas neste documento.

    Para receber as permissões necessárias para aplicar as condições do IAM aos recursos de sessões da plataforma de agentes, peça ao administrador para conceder a você os seguintes papéis do IAM:

    • Para projetos: Administrador do IAM do projeto (`roles/resourcemanager.projectIamAdmin`)

    Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

    Esses papéis predefinidos contêm as permissões necessárias para aplicar condições do IAM aos recursos de sessões da plataforma de agentes. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

    Permissões necessárias

    As seguintes permissões são necessárias para aplicar as condições do IAM aos recursos de sessões da plataforma de agente :

    • Definir o acesso condicional do IAM no nível do projeto: `resourcemanager.projects.setIamPolicy`

    Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

    Se você planeja usar condições do IAM em toda a organização, também precisará de permissões para gerenciar as políticas da organização.

Como criar acesso condicional para sessões

Conceda acesso condicional às sessões adicionando uma condição a uma vinculação de política do Identity and Access Management no nível do projeto. A condição usa a função api.getAttribute('aiplatform.googleapis.com/sessionUserId', "") para inspecionar o ID do usuário do recurso de sessão. Você define um ID do usuário ao criar uma sessão.

Para um guia detalhado sobre como criar políticas do IAM com condições, consulte Condições em políticas de permissão.

Para conceder um único papel a um principal, faça o seguinte:

Console

  1. No console do Google Cloud , acesse a página IAM.

    Acessar IAM

  2. Selecione o projeto.

  3. Selecione um principal para conceder um papel:

    • Para conceder um papel a um principal que já tenha outros papéis no recurso, encontre uma linha contendo o principal e clique em Editar principal nessa linha, e clique em Adicionar outro papel.

      Para conceder um papel a um agente de serviço, marque a caixa de seleção Incluir concessões de papel fornecidas pelo Google para ver o endereço de e-mail dele.

    • Para conceder um papel a um principal que ainda não tem papéis no recurso, clique em Conceder acesso e insira um identificador de principal. Por exemplo, my-user@example.com ou //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com.

  4. Na lista suspensa, selecione um papel a ser concedido. Como prática recomendada de segurança, escolha um papel que inclua apenas as permissões necessárias ao principal. É possível escolher um dos papéis especializados do IAM de sessão.

  5. Adicione uma condição ao papel usando aiplatform.googleapis.com/sessionUserId como o atributo da API. Confira os exemplos abaixo para ver algumas possíveis declarações de condição.

  6. Clique em Salvar. O principal recebe o papel no recurso.

gcloud

  1. No console do Google Cloud , ative o Cloud Shell.

    Ativar o Cloud Shell

    Na parte inferior do console do Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

  2. O comando add-iam-policy-binding permite que você conceda rapidamente um papel a um principal.

    Antes de usar os dados do comando abaixo, faça estas substituições:

    • PROJECT_ID: o ID do projeto do Google Cloud . Os IDs de projeto são alfanuméricos, como my-project.

    • PRINCIPAL: um identificador do principal ou membro, que geralmente tem o seguinte formato: PRINCIPAL_TYPE:ID. Por exemplo, user:my-user@example.com ou principalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com. Para uma lista completa dos valores que PRINCIPAL pode ter, consulte Identificadores de principais.

      Para o tipo de principal user, o nome de domínio no identificador precisa ser do Google Workspace ou do Cloud Identity. Para saber como configurar um domínio do Cloud Identity, consulte a Visão geral do Cloud Identity.

    • ROLE_NAME: o nome do papel que você quer revogar. Use um dos seguintes formatos:

      • Papéis predefinidos: roles/aiplatform.IDENTIFIER
      • Papéis personalizados para envolvidos no projeto: projects/PROJECT_ID/roles/IDENTIFIER

      Na lista suspensa, selecione um papel a ser concedido. Como prática recomendada de segurança, escolha um papel que inclua apenas as permissões necessárias ao principal. É possível escolher um dos papéis especializados do IAM para sessões.

    • CONDITION: adicione uma condição ao papel, usando aiplatform.googleapis.com/sessionUserId como o atributo da API. Confira os exemplos abaixo para ver algumas possíveis instruções de condição.

    Execute o seguinte comando:

    Linux, macOS ou Cloud Shell

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=PRINCIPAL --role=ROLE_NAME \
        --condition=CONDITION

    Windows (PowerShell)

    gcloud projects add-iam-policy-binding PROJECT_ID `
        --member=PRINCIPAL --role=ROLE_NAME `
        --condition=CONDITION

    Windows (cmd.exe)

    gcloud projects add-iam-policy-binding PROJECT_ID ^
        --member=PRINCIPAL --role=ROLE_NAME ^
        --condition=CONDITION

    A resposta contém a política da IAM atualizada:

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform. Para mais informações, consulte a documentação de referência do provedor Terraform.

Se você estiver usando o Terraform para definir as políticas do IAM, inclua uma condição no recurso google_project_iam_member para restringir o acesso de um membro às sessões.

resource "google_project_iam_member" "example" {
  project    = "PROJECT_ID"
  role       = "ROLE"
  member     = "MEMBER"
  condition {
    title       = "Session Access Condition"
    description = "IAM condition for Session"
    expression  = "CONDITION"
  }
}

Substitua as seguintes variáveis:

  • PROJECT_ID: o ID do projeto do Google Cloud . Os IDs de projeto são alfanuméricos, como my-project.
  • ROLE: o papel do IAM a ser concedido, por exemplo, roles/aiplatform.sessionEditor.
  • MEMBER: o principal ao qual o papel será concedido, por exemplo, user:developerA@corp.com. Para uma lista completa dos valores que MEMBER pode ter, consulte Identificadores principais.
  • CONDITION: sua instrução de condição do IAM usando aiplatform.googleapis.com/sessionUserId como o atributo da API. Confira os exemplos abaixo para ver algumas possíveis instruções de condição.

Práticas recomendadas para permissões no nível do ID do usuário

Ao criar condições para sessões, use as seguintes práticas recomendadas:

  1. Use papéis especializados do IAM de sessão: as condições do IAM de sessão só devem ser usadas para papéis que se aplicam a sessões e eventos de sessão. É possível usar papéis especializados, como aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionEditor e aiplatform.googleapis.com/sessionUser, para evitar o acesso excessivamente permissivo. Consulte a seção Papéis do IAM de sessão especializada para mais detalhes.

  2. Use condições positivas: recomendamos o uso de condições positivas (como verificações de igualdade ou a presença de prefixos) em aiplatform.googleapis.com/sessionUserId para maior precisão. Como os tipos e serviços não compatíveis são representados por um ID do usuário vazio, as condições negativas (como verificações de desigualdade) podem corresponder inadvertidamente a uma ampla gama de recursos, o que pode ser excessivamente permissivo e permitir a concessão inesperada de permissões.

  3. Encurte as condições, se possível: recomendamos usar a lógica mais curta e simples nas expressões de condição do IAM, especialmente se você planeja ter um grande número de condições. As políticas de permissão do IAM têm uma limitação de tamanho, e a simplificação das condições evita que as limitações do IAM sejam atingidas. Consulte Limitações para saber mais detalhes. Por exemplo, é possível simplificar a verificação de dois IDs do usuário diferentes combinando a instrução composta: api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'sessionA' || api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == sessionB', já que ela é avaliada com o mesmo resultado da instrução mais curta api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['sessionA', 'sessionB'].

Papéis especializados do IAM para sessões

É fundamental evitar políticas do IAM excessivamente permissivas ao usar as condições do IAM. A tabela a seguir lista os papéis especializados que podem ser usados ao conceder papéis condicionais do IAM para APIs de sessão:

Nome do papel Descrição Permissões incluídas
roles/aiplatform.sessionViewer Concede acesso somente leitura a sessões e eventos de listagem.
  • aiplatform.googleapis.com/sessions.get
  • aiplatform.googleapis.com/sessions.list
  • aiplatform.googleapis.com/sessionEvents.list
roles/aiplatform.sessionEditor Concede acesso de gravação a sessões e eventos de anexação.
  • aiplatform.googleapis.com/sessions.create
  • aiplatform.googleapis.com/sessions.update
  • aiplatform.googleapis.com/sessions.delete
  • aiplatform.googleapis.com/sessionEvents.append
roles/aiplatform.sessionUser Concede acesso total a sessões e eventos, incluindo todas as permissões de leitor e editor. Inclui todas as permissões de sessionEditor e sessionViewer.

Como usar as condições do IAM com sessões

Nesta seção, mostramos os seguintes exemplos de uso das condições do IAM com sessões:

  1. Conceder acesso de leitura a sessões com correspondência exata do ID do usuário.

  2. Conceder acesso de gravação a sessões que contêm um prefixo específico no ID do usuário.

  3. Conceder acesso total a sessões que contêm um dos dois IDs de usuário.

Conceder acesso de leitura a sessões com correspondência exata do ID do usuário

A condição a seguir concede ao indivíduo userA@gmail.com acesso de visualização apenas às sessões que têm o ID do usuário exato userA.

Isso significa que o indivíduo pode receber sessões e listar os eventos de sessão, desde que o ID do usuário seja exatamente userA. O usuário não tem acesso a sessões com ID do usuário, como userB.

{
  "members": ["user:userA@gmail.com"],
  "role": "roles/aiplatform.sessionViewer",
  "condition": {
    "title": "Session Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'userA'"
  }
}

Conceder acesso de gravação a sessões que contêm um prefixo específico no ID do usuário

A condição a seguir concede ao indivíduo developerA@corp.com acesso de edição a todas as sessões que contêm o ID do usuário que começa com user. Use startsWith para verificar o prefixo e endsWith para verificar o sufixo.

Isso significa que o desenvolvedor pode criar, atualizar e excluir sessões, além de anexar eventos, com IDs do usuário como userA ou user1234.

{
  "members": ["user:developerA@corp.com"],
  "role": "roles/aiplatform.sessionEditor",
  "condition": {
    "title": "Session Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '').startsWith('user')"
  }
}

Conceder acesso total a sessões que contêm um dos dois IDs do usuário

A condição a seguir concede ao usuário do grupo group:engineering@corp.com (leitor e editor) acesso a sessões que têm apenas os IDs de usuário userA ou user123.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.sessionUser",
  "condition": {
    "title": "Session Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['userA', 'user123']"
  }
}

Limitações

  1. Limite de principais: as políticas do IAM são limitadas a 1.500 principais únicos. Esse limite pode ser gerenciado usando os Grupos do Google. Saiba mais em Limites para todos os principais.

  2. Suporte à API ListSessions: a API ListSessions não é compatível com as condições do IAM. Para conceder permissões ListSessions, é preciso conceder ao principal um papel incondicional, como aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionUser ou um papel incondicional relevante da Gemini Enterprise Agent Platform.