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

Por padrão, as permissões do Identity and Access Management de memória são no nível do projeto. Neste documento, descrevemos como usar as condições do IAM para controlar o acesso mais granular aos recursos do banco de memória do Vertex AI Agent Engine.

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 da API "aiplatform.googleapis.com/memoryScope" com uma expressão escrita na Common Expression Language. O escopo é um dicionário arbitrário fornecido ao criar ou gerar recordações, como {'user_id': '123'}, que permite organizar quais recordações 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 dele. É 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 recordações e revisões para que um usuário só possa acessar as próprias informações ou para que os desenvolvedores só possam visualizar 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órias, 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 do 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 agentes só podem acessar determinadas recordações.
Conceda papéis do IAM: verifique se você tem os papéis necessários com 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 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 do banco de memória do mecanismo de agente da Vertex AI. 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 do banco de memória do Vertex AI Agent Engine:
- Defina 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 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:

Console

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

Acesse IAM
Selecione o projeto.
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 peloGoogle para ver o endereço de e-mail dele.
  
  Observação: não é possível editar papéis herdados ao gerenciar o acesso a um recurso. Para editar os papéis herdados, acesse o recurso em que o papel foi concedido.
- Para conceder um papel a um principal que ainda não tem papéis no recurso, clique em Conceder acesso e insira um identificador principal, por exemplo, my-user@example.com ou //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com.
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. Você pode escolher um dos papéis especializados do IAM do Memory Bank.
Adicione uma condição à função usando aiplatform.googleapis.com/memoryScope como o atributo da API. Confira os exemplos abaixo para ver algumas instruções de condição possíveis.
Clique em Salvar. O principal recebe o papel no recurso.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
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 do 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 conferir 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. Para práticas recomendadas de segurança, escolha um papel que inclua apenas as permissões necessárias ao principal. Você pode escolher um dos papéis especializados do IAM do Memory Bank.
- CONDITION: adicione uma condição à função usando aiplatform.googleapis.com/memoryScope como o atributo da API. Confira os exemplos abaixo para ver algumas instruções de condição possíveis.
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 suas políticas do IAM, inclua uma condição no recurso google_project_iam_member para restringir o acesso de um membro às recordações.

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

Substitua as seguintes variáveis:

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

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

Ao criar condições para o Banco de memória, use as seguintes práticas recomendadas:

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 recordações e revisões de recordações. É 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 Specialized Memory Bank IAM Roles para mais detalhes.
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 os tipos e serviços sem suporte são representados por um escopo 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.
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 os erros nas expressões de condição do IAM causam a negação do acesso, as duas expressões produzem o mesmo resultado.

Papéis especializados do IAM do Memory Bank

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

Nome do papel	Descrição	Permissões incluídas
`roles/aiplatform.memoryViewer`	Concede acesso somente leitura a memórias e revisões de memória.	`aiplatform.googleapis.com/memories.get` `aiplatform.googleapis.com/memories.list` `aiplatform.googleapis.com/memories.retrieve` `aiplatform.googleapis.com/memoryRevisions.list` `aiplatform.googleapis.com/memoryRevisions.get`
`roles/aiplatform.memoryEditor`	Concede acesso de gravação e geração a memórias e acesso de reversão a revisões de memória.	`aiplatform.googleapis.com/memories.create` `aiplatform.googleapis.com/memories.update` `aiplatform.googleapis.com/memories.delete` `aiplatform.googleapis.com/memories.generate` `aiplatform.googleapis.com/memoryRevisions.rollback`
`roles/aiplatform.memoryUser`	Concede acesso total a recordações e revisões, incluindo todas as permissões de leitor e editor.	Inclui todas as permissões de `memoryEditor` e `memoryViewer`.

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:

Conceder acesso de leitura a recordações com correspondência exata de escopo.
Conceder acesso de gravação a recordações com escopo que contenha um par de chave-valor específico.
Conceder acesso total às recordações com escopo que contenha chaves específicas.
Conceder acesso total às recordações com escopo que contenha um prefixo específico.
Conceder acesso total às recordações 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 userA@gmail.com acesso de visualização 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 recordações 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 recordações, além de criar e reverter as revisões delas, 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) às 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 usuário do grupo group:engineering@corp.com (leitor e editor) acesso a recordações que têm a chave 'userId' com valor começando com 'user'.Use 'startsWith' para verificar o prefixo e 'endsWith' para verificar o 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 'userA' ou 'userB'.