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

Por padrão, as permissões de 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 do Vertex AI Agent Engine.

Visão geral

Com as condições do IAM, é possível conceder acesso aos recursos de sessão e evento de sessão somente se as condições especificadas forem atendidas. É possível controlar o acesso às sessões com base na string userId no recurso Session usando o atributo da 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 simultaneamente, incluindo aqueles que ainda não existem. É possível restringir o acesso às suas sessões e 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 e garanta o princípio de menor privilégio.
• Identifique os principais afetados: identifique quem na sua organização deve receber quais permissões. Por exemplo, considere o seguinte:
  • Os usuários podem ver as sessões de outros usuários?
  • Os desenvolvedores precisam ter acesso a todas as sessões?
  • Os administradores de projetos podem ver todas as sessões?
  • Algumas identidades de agente precisam 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 condições do IAM a recursos de sessão do mecanismo de agente da Vertex AI , 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ão do Vertex AI Agent Engine . Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

  Permissões necessárias

  As permissões a seguir são necessárias para aplicar condições do IAM aos recursos de sessão do Vertex AI Agent Engine :

  • Definir 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 a 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 de 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:

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"
  }
}

Práticas recomendadas para permissões no nível do User-ID

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 acesso excessivamente permissivo. Consulte a seção Papéis do IAM de sessão especializada para mais detalhes.

2. Use condições positivas: recomendamos usar 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 de usuário vazio, as condições negativas (como verificações de desigualdade) podem corresponder inadvertidamente a uma ampla variedade 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, principalmente se você planeja ter uma grande quantidade 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 limitações do IAM. Consulte Limitações para mais detalhes. Por exemplo, é possível simplificar a verificação de dois IDs de 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 resulta no mesmo que a instrução mais curta api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['sessionA', 'sessionB'].

Papéis do IAM especializados para sessões

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

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

Esta seção aborda os seguintes exemplos de uso das condições do IAM com sessões:

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

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

3. Conceder acesso total às sessões que contêm um dos dois User-IDs.

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

A condição a seguir concede ao indivíduo userA@gmail.com acesso de visualização somente para sessões que têm o ID de 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 começando com user. Use startsWith para verificar prefixos e endsWith para verificar sufixos.

Isso significa que o desenvolvedor pode criar, atualizar e excluir sessões, além de anexar eventos, com IDs de 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 User-IDs

A condição a seguir concede ao grupo group:engineering@corp.com acesso de usuário (leitor e editor) a sessões que têm apenas 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 exclusivos. 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 condições do IAM. Para conceder permissões "ListSessions", é necessário atribuir ao principal um papel incondicional, como aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionUser ou um papel incondicional relevante da Gemini Enterprise Agent Platform.