Controlar o acesso ao Memory Bank com as condições do IAM

Com o Memory Bank, é possível controlar o acesso a memórias e recursos de revisão de memória com base nos atributos de escopo. É possível usar as condições do IAM para definir controles de acesso detalhados, como restringir o acesso a usuários ou grupos específicos com base em critérios definidos na Common Expression Language.

Este documento descreve como criar e aplicar políticas de acesso condicional para memórias e revisões no seu projeto.

Para informações gerais sobre permissões, consulte Analisar os papéis necessários.

Visão geral

Com as condições do IAM, é possível conceder acesso a recursos de memória e revisão de memória somente se as condições especificadas forem atendidas. É possível controlar o acesso às recordações com base no campo scope em um recurso de recordação usando o atributo de API "aiplatform.googleapis.com/memoryScope" com uma expressão escrita em Common Expression Language. O escopo é um dicionário arbitrário fornecido ao criar ou gerar memórias, como {'user_id': '123'}, que permite organizar quais memórias pertencem a qual grupo.

Essas políticas condicionais do Identity and Access Management são criadas no nível do projeto e se aplicam a todas as memórias dentro de 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 relacionados do Memory Bank simultaneamente, incluindo aqueles que ainda não existem. É possível restringir o acesso às suas memórias e revisões para que um usuário só possa acessar as próprias informações ou para que desenvolvedores só possam acessar determinados recursos do Memory Bank sem concessões de permissão especiais.

Antes de começar

Para configurar políticas condicionais do IAM para memórias e revisões de memória, 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 do Memory Bank são adequados para seu caso de uso e garanta o princípio de privilégio mínimo.

• Identifique os principais afetados: identifique quem na sua organização deve receber quais permissões. Por exemplo, considere o seguinte:

  • Se os desenvolvedores podem ver todas as recordações.
  • Se os administradores do projeto podem ver todas as recordações.
  • Se determinadas identidades de agente só podem acessar determinadas memórias.
• 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 do banco de memória da plataforma do agente, 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 do Memory Bank do Agent Platform. 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 condições do IAM aos recursos do Memory Bank da Plataforma de Agentes:

  • 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 recordações

O acesso condicional às recordações é concedido adicionando uma condição a uma vinculação de política do IAM no nível do projeto. A condição usa a função api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) para inspecionar o mapa de escopo de um recurso de memória. Você define o escopo ao criar ou gerar uma memória.

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       = "Memory Access Condition"
    description = "IAM condition for Memory Bank"
    expression  = "CONDITION"
  }
}

Práticas recomendadas para permissões no nível do escopo

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

1. Use papéis especializados do Memory Bank: as condições do IAM do Memory Bank só devem ser usadas para papéis que se aplicam a memórias e revisões de memória. É possível usar papéis especializados como aiplatform.googleapis.com/memoryViewer, aiplatform.googleapis.com/memoryEditor e aiplatform.googleapis.com/memoryUser para evitar acesso excessivamente permissivo. Consulte os papéis do IAM do Memory Bank especializado para mais detalhes.

2. Use condições positivas: recomendamos usar condições positivas (como verificações de igualdade ou a presença de pares de chave-valor) em aiplatform.googleapis.com/memoryScope para maior precisão. Como tipos e serviços não compatíveis são representados por um escopo vazio, 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 esses problemas. Consulte Limitações para mais detalhes. Por exemplo, é possível omitir a verificação da presença de uma chave na expressão 'user_id' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) && api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA' e usar a instrução mais curta api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA'. Se a chave user_id estiver faltando, a expressão mais longa será avaliada como false, enquanto a mais curta vai resultar em um erro. Como erros em expressões de condição do IAM causam a negação do acesso, ambas as expressões produzem o mesmo resultado.

Papéis especializados do IAM do Memory Bank

É 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 do Memory Bank:

Como usar condições do IAM com o Memory Bank

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

1. Conceder acesso de leitura a recordações com correspondência exata de escopo.

2. Conceda acesso de gravação a recordações com escopo que contenha um par de chave-valor específico.

3. Conceder acesso total às recordações com escopo que contenha chaves específicas.

4. Conceder acesso total às recordações com escopo que contenha um prefixo específico.

5. Conceda acesso total às memórias com escopo de chave e um conjunto de valores permitidos.

Conceder acesso de leitura a recordações com correspondência exata de escopo

A condição a seguir concede ao indivíduo acesso de visualização userA@gmail.com apenas às recordações que têm o escopo exato {"userId": "userA"}.

Isso significa que o membro pode receber e recuperar recordações, além de listar e receber as revisões delas, desde que o escopo seja exatamente {"userId": "userA"}. O usuário não tem acesso a recordações com escopo como {'userId': 'userA', 'source': 'ADK'}.

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

Conceder acesso de gravação a memórias com escopo que contenha um par de chave-valor específico

A condição a seguir concede ao indivíduo developerA@corp.com acesso de edição a todas as recordações que contêm o par de chave-valor 'userId': 'userA'.

Isso significa que o usuário pode criar, atualizar, excluir e gerar memórias, além de criar e reverter as revisões dessas memórias, com escopos como {'userId': 'userA'} e {'userId': 'userA', 'source': 'ADK'}.

{
  "members": ["user:developerA@corp.com"],
  "role": "roles/aiplatform.memoryEditor",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'] == 'userA'"
  }
}

Conceder acesso total às recordações com escopo que contenha chaves específicas

A condição a seguir concede ao grupo group:engineering@corp.com acesso de usuário (leitor e editor) a recordações que têm a chave 'admin_override' ou 'public_access_flag'.

Isso significa que os membros do grupo têm acesso total de leitura e gravação às recordações com escopos como {'admin_override': 'true'}, {'admin_override': 'true', 'public_access_flag': 'false'} e {'userId': 'userA', 'public_access_flag': 'false'}.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "('admin_override' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {})) || ('public_access_flag' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {}))"
  }
}

Conceder acesso total a recordações com escopo que contenha um prefixo específico

A condição a seguir concede ao grupo group:engineering@corp.com acesso de usuário (leitor e editor) a recordações que têm a chave 'userId' com valor iniciando com 'user'.Você pode usar 'startsWith' para verificação de prefixo e 'endsWith' para verificação de sufixo.

Isso significa que os membros do grupo têm acesso total de leitura e gravação às recordações com escopos como {'userId': 'userA'} e {'userId': 'userB', 'public_access_flag': 'false'}.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'].startsWith('user')"
  }
}

Conceder acesso total às recordações com escopo de chave e um conjunto de valores permitidos

A condição a seguir concede ao grupo group:engineering@corp.com acesso de usuário (leitor e editor) a recordações que têm a chave 'userId' com valores de 'userA' ou 'userB'.

Isso significa que os membros do grupo têm acesso total de leitura e gravação às recordações com escopos como {'userId': 'userA'} e {'userId': 'userB', 'public_access_flag': 'false'}.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'] in ['userA', 'userB']"
  }
}

Limitações

• 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.

• Suporte à API: as condições do IAM não são compatíveis com métodos que operam em vários escopos, como ListMemories e PurgeMemories. Para conceder essas permissões, atribua ao principal um papel incondicional, como aiplatform.googleapis.com/memoryViewer, aiplatform.googleapis.com/memoryUser ou um papel incondicional relevante da plataforma de agente do Gemini Enterprise.