Controle o acesso ao banco de memória com as condições do IAM

Por predefinição, as autorizações da gestão de identidade e de acesso da memória estão ao nível do projeto. Este documento descreve como usar as condições da IAM para controlar o acesso mais detalhado aos recursos do banco de memória do Vertex AI Agent Engine.

Vista geral

As condições de IAM permitem-lhe conceder acesso a recursos de memória e revisão de memória apenas se forem cumpridas as condições especificadas. Pode controlar o acesso às memórias com base no campo scope num recurso de memória através do atributo da API "aiplatform.googleapis.com/memoryScope" com uma expressão escrita em Common Expression Language. O âmbito é um dicionário arbitrário fornecido quando cria ou gera memórias, como {'user_id': '123'}, que lhe permite organizar as memórias que pertencem a que grupo.

Estas políticas de gestão de identidade e de acesso condicionais são criadas ao nível do projeto e aplicam-se a todas as memórias num projeto. Pode aplicar condições da IAM a todos os tipos de principais, incluindo utilizadores do seu projeto e contas de serviço.

As condições da IAM são úteis para conceder autorizações da Identity and Access Management (IAM) a muitos recursos relacionados do Memory Bank em simultâneo, incluindo os que ainda não existem. Pode restringir o acesso às suas memórias e revisões para que um utilizador só possa aceder às suas próprias informações ou para que os programadores só possam ver determinados recursos do banco de memórias sem concessões de autorizações especiais.

Antes de começar

Para configurar políticas de IAM condicionais para memórias e revisões de memórias, faça o seguinte:

Reveja as condições do IAM: familiarize-se com a vista geral das condições do IAM.
Determine as funções necessárias: identifique as funções de IAM do Memory Bank especializadas adequadas para o seu exemplo de utilização para garantir o princípio do menor privilégio.
Identifique os responsáveis afetados: identifique quem na sua organização deve receber que autorizações. Por exemplo, considere o seguinte:
- Se os programadores devem poder ver todas as memórias.
- Se os administradores do projeto devem poder ver todas as memórias.
- Se determinadas identidades de agentes só podem aceder a determinadas memórias.
Conceda funções de IAM: certifique-se de que tem as funções necessárias que contêm as autorizações necessárias para realizar as tarefas descritas neste documento.
Para receber as autorizações de que precisa para aplicar condições de IAM aos recursos do banco de memória do Vertex AI Agent Engine, peça ao seu administrador para lhe conceder as seguintes funções de IAM:
- Para projetos: Administrador de IAM do projeto (roles/resourcemanager.projectIamAdmin)
Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Estas funções predefinidas contêm as autorizações necessárias para aplicar condições de IAM a recursos do banco de memória do Vertex AI Agent Engine. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:
Autorizações necessárias

São necessárias as seguintes autorizações para aplicar condições de IAM aos recursos do Memory Bank do Vertex AI Agent Engine:
- Defina o acesso IAM condicional ao nível do projeto: resourcemanager.projects.setIamPolicy
Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.
Se planeia usar as condições do IAM na sua organização, também precisa de autorizações para gerir políticas da organização.

Criar acesso condicional para memórias

O acesso condicional às memórias é concedido adicionando uma condição a uma associação de políticas de IAM ao nível do projeto. A condição usa a função api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) para inspecionar o mapa de âmbito de um recurso de memória. Define o âmbito quando cria ou gera uma memória.

Para um guia detalhado sobre a criação de políticas de IAM com condições, consulte o artigo Condições nas políticas de autorização.

Para conceder uma única função a um principal, faça o seguinte:

Consola

Na Google Cloud consola, aceda à página IAM.

Aceda ao IAM
Selecione o seu projeto.
Selecione um principal ao qual conceder uma função:
- Para conceder uma função a um principal que já tenha outras funções no recurso, encontre uma linha que contenha o principal, clique em Editar principal nessa linha e clique em Adicionar outra função.
  
  Para conceder uma função a um agente de serviço, selecione a caixa de verificação Incluir concessões de funções fornecidas pela Google para ver o respetivo endereço de email.
  
  Nota: não pode editar funções herdadas quando gere o acesso a um recurso. Para editar funções herdadas, aceda ao recurso onde a função foi concedida.
- Para conceder uma função a um principal que não tenha funções existentes no recurso, clique em Conceder acesso e, de seguida, introduza um identificador principal, por exemplo, my-user@example.com ou //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com.
Selecione uma função a conceder na lista pendente. Para as melhores práticas de segurança, escolha uma função que inclua apenas as autorizações de que o seu principal precisa. Pode escolher uma das funções de IAM do banco de memória especializado.
Adicione uma condição à função, usando aiplatform.googleapis.com/memoryScope como o atributo da API. Consulte os exemplos abaixo para ver algumas possíveis declarações de condições.
Clique em Guardar. O principal recebe a função 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-lhe conceder rapidamente uma função a um principal.

Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:
- PROJECT_ID: o ID do seu Google Cloud projeto. Os IDs dos projetos são alfanuméricos, como my-project.
- PRINCIPAL: um identificador do principal ou membro, que normalmente 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 ver uma lista completa dos valores que PRINCIPAL pode ter, consulte Identificadores principais.
  
  Para o tipo principal user, o nome do domínio no identificador tem de ser um domínio do Google Workspace ou um domínio do Cloud ID. Para saber como configurar um domínio do Cloud Identity, consulte a vista geral do Cloud Identity.
- ROLE_NAME: o nome da função que quer revogar. Use um dos seguintes formatos:
  - Funções predefinidas: roles/aiplatform.IDENTIFIER
  - Funções personalizadas ao nível do projeto: projects/PROJECT_ID/roles/IDENTIFIER
  Selecione uma função a conceder na lista pendente. Para as melhores práticas de segurança, escolha uma função que inclua apenas as autorizações de que o seu principal precisa. Pode escolher uma das funções de IAM do Memory Bank especializadas.
- CONDITION: adicione uma condição à função, usando aiplatform.googleapis.com/memoryScope como atributo da API. Consulte os exemplos abaixo para ver algumas possíveis declarações de condições.
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 de IAM atualizada.

Terraform

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

Se estiver a usar o Terraform para definir as suas políticas de IAM, pode incluir uma condição no recurso google_project_iam_member para restringir o acesso de um membro às memórias.

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 seu Google Cloud projeto. Os IDs dos projetos são alfanuméricos, como my-project.
ROLE: a função de IAM a conceder, por exemplo, roles/aiplatform.memoryEditor.
MEMBER: o principal ao qual conceder a função, por exemplo, user:developerA@corp.com. Para ver uma lista completa dos valores que MEMBER pode ter, consulte Identificadores principais.
CONDITION: a sua declaração de condição do IAM que usa aiplatform.googleapis.com/memoryScope como atributo da API. Consulte os exemplos abaixo para ver algumas possíveis declarações de condições.

Práticas recomendadas para autorizações ao nível do âmbito

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

Use funções especializadas do Memory Bank: as condições da IAM do Memory Bank só devem ser usadas para funções que se aplicam a memórias e revisões de memórias. Pode usar funções especializadas, como aiplatform.googleapis.com/memoryViewer, aiplatform.googleapis.com/memoryEditor e aiplatform.googleapis.com/memoryUser, para evitar o acesso excessivamente permissivo. Consulte as funções de IAM do banco de memória especializado para mais detalhes.
Use condições positivas: recomendamos que use condições positivas (como verificações de igualdade ou a presença de pares de chave-valor) em aiplatform.googleapis.com/memoryScope para uma maior precisão. Uma vez que os tipos e os serviços não suportados são representados por um âmbito vazio, as condições negativas (como as verificações de desigualdade) podem corresponder inadvertidamente a uma vasta gama de recursos, o que pode ser excessivamente permissivo e permitir a concessão de autorizações inesperada.
Reduza as condições, se possível: recomendamos que use a lógica mais curta e simples nas suas expressões de condições de IAM, especialmente se planear 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 que se depare com estas limitações do IAM. Consulte a secção Limitações para ver mais detalhes. Por exemplo, pode 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', uma vez que é avaliada com o mesmo resultado que a declaração mais curta api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA'.

Funções IAM do banco de memória especializado

É fundamental evitar políticas de IAM excessivamente permissivas quando usar condições de IAM. A tabela seguinte apresenta as funções especializadas que pode usar quando concede funções de IAM condicionais para as APIs Memory Bank:

Nome da Função	Descrição	Autorizações incluídas
`roles/aiplatform.memoryViewer`	Concede acesso só de leitura a memórias e revisões de memórias.	`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 escrita e geração a memórias, bem como acesso de reversão a revisões de memórias.	`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 memórias e revisões, incluindo todas as autorizações de leitor e editor.	Inclui todas as autorizações de `memoryEditor` e `memoryViewer`.

Usar condições do IAM com o Memory Bank

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

Conceda acesso de leitura a memórias com correspondência de âmbito exata.
Conceda acesso de escrita a memórias com âmbito que contenha um par de chave-valor específico.
Conceda acesso total às memórias com um âmbito que contenha chaves específicas.
Conceda acesso total a memórias com um âmbito que contenha um prefixo específico.
Conceda acesso total às memórias com o âmbito da chave com um conjunto de valores permitidos.

Conceda acesso de leitura a memórias com correspondência exata do âmbito

A condição seguinte concede ao indivíduo userA@gmail.com acesso de visualização apenas a memórias que tenham o âmbito exato {"userId": "userA"}.

Isto significa que o membro tem a capacidade de obter e recuperar memórias, juntamente com a listagem e a obtenção das revisões dessas memórias, desde que o âmbito seja exatamente {"userId": "userA"}. O utilizador não tem acesso a memórias com âmbito, 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'}"
  }
}

Conceda acesso de escrita a memórias com âmbito que contenha um par de chave-valor específico

A condição seguinte concede ao indivíduo developerA@corp.com acesso de edição a todas as memórias que contenham o par de chave-valor 'userId': 'userA'.

Isto significa que o utilizador tem a capacidade de criar, atualizar, eliminar e gerar memórias, bem como criar e reverter as revisões dessas memórias, com âmbitos 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'"
  }
}

Conceda acesso total às memórias com um âmbito que contenha chaves específicas

A condição seguinte concede ao grupo group:engineering@corp.com acesso de utilizador (leitor e editor) às memórias que têm a chave 'admin_override' ou 'public_access_flag'.

Isto significa que os membros do grupo têm acesso total de leitura e escrita a memórias com âmbitos 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', {}))"
  }
}

Conceda acesso total às memórias com um âmbito que contenha um prefixo específico

A condição seguinte concede ao grupo group:engineering@corp.com acesso de utilizador (leitor e editor) a memórias que tenham a chave 'userId' com o valor a começar por 'user'.Pode usar 'startsWith' para verificar o prefixo e 'endsWith' para verificar o sufixo.

Isto significa que os membros do grupo têm acesso total de leitura e escrita a memórias com âmbitos 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')"
  }
}

Conceda acesso total às memórias com o âmbito da chave com um conjunto de valores permitidos

A seguinte condição concede ao grupo group:engineering@corp.com acesso de utilizador (leitor e editor) a memórias que tenham a chave 'userId' com valores de 'userA' ou 'userB'.