Controle o acesso às sessões com as condições do IAM

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

Vista geral

As condições da IAM permitem-lhe conceder acesso a recursos de sessões e eventos de sessões apenas se forem cumpridas as condições especificadas. Pode controlar o acesso às sessões com base na string userId no recurso Session através do atributo da API aiplatform.googleapis.com/sessionUserId com uma expressão escrita na linguagem de expressão comum. O ID do utilizador é uma string arbitrária fornecida quando cria sessões, como userId = "userA".

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 sessões e eventos de sessão 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 de sessão relacionados em simultâneo, incluindo os que ainda não existem. Pode restringir o acesso às suas sessões e eventos para que um utilizador só possa aceder às suas próprias informações ou para que os programadores só possam ver determinados recursos de sessão sem concessões de autorização especiais.

Antes de começar

Para configurar políticas de gestão de identidade e de acesso condicionais para sessões e eventos de sessão, 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 que funções IAM de sessão especializadas são 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:
- Os utilizadores devem poder ver as sessões de outros utilizadores?
- Os programadores devem poder ver todas as sessões?
- Os administradores do projeto devem poder ver todas as sessões?
- Determinadas identidades de agentes devem poder aceder a determinadas sessões?
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 de sessão do Vertex AI Agent Engine, peça ao seu administrador para lhe conceder as seguintes funções de IAM:
- Para projetos: Administrador de IAM de projetos (`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 aos recursos de sessão 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 a recursos de sessão 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 sessões

Conceda acesso condicional a sessões adicionando uma condição a uma associação de políticas de gestão de identidade e de acesso ao nível do projeto. A condição usa a função api.getAttribute('aiplatform.googleapis.com/sessionUserId', "") para inspecionar o ID do utilizador do recurso de sessão. Define um ID do utilizador quando cria uma sessão.

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 de sessão especializadas.
Adicione uma condição à função, usando aiplatform.googleapis.com/sessionUserId 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 de sessão especializadas.
- CONDITION: adicione uma condição à função, usando aiplatform.googleapis.com/sessionUserId 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 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 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.sessionEditor.
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/sessionUserId 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 ID do utilizador

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

Use funções IAM de sessão especializadas: as condições IAM de sessão só devem ser usadas para funções que se aplicam a sessões e eventos de sessão. Pode usar funções especializadas, como aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionEditor e aiplatform.googleapis.com/sessionUser, para evitar o acesso excessivamente permissivo. Consulte a secção Funções de IAM de sessão especializada para mais detalhes.
Use condições positivas: recomendamos que use condições positivas (como verificações de igualdade ou a presença de prefixos) em aiplatform.googleapis.com/sessionUserId para uma maior precisão. Uma vez que os tipos e os serviços não suportados são representados por um ID do utilizador vazio, as condições negativas (como 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 autorização do IAM têm uma limitação de tamanho e a simplificação das condições evita problemas com as limitações do IAM. Consulte a secção Limitações para ver mais detalhes. Por exemplo, pode simplificar a verificação de dois IDs de utilizadores diferentes combinando a declaração composta: api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'sessionA' || api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == sessionB', uma vez que é avaliada com o mesmo resultado que a declaração mais curta api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['sessionA', 'sessionB'].

Funções de IAM de sessão especializadas

É 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 APIs de sessão:

Nome da Função	Descrição	Autorizações incluídas
`roles/aiplatform.sessionViewer`	Concede acesso só de leitura a sessões e eventos de fichas.	`aiplatform.googleapis.com/sessions.get` `aiplatform.googleapis.com/sessions.list` `aiplatform.googleapis.com/sessionEvents.list`
`roles/aiplatform.sessionEditor`	Concede acesso de escrita 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 autorizações de visualizador e editor.	Inclui todas as autorizações de `sessionEditor` e `sessionViewer`.

Usar condições da IAM com sessões

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

Conceder acesso de leitura a sessões com correspondência exata do ID do utilizador.
Conceda acesso de escrita a sessões que contenham um prefixo específico no ID do utilizador.
Conceder acesso total a sessões que contenham um de dois IDs de utilizadores.

Conceda acesso de leitura a sessões com correspondência exata do ID do utilizador

A seguinte condição concede ao indivíduo userA@gmail.com acesso de visualização apenas a sessões que tenham o User ID exato userA.

Isto significa que o indivíduo tem a capacidade de obter sessões e listar os eventos de sessão, desde que o ID do utilizador seja exatamente userA. O utilizador não tem acesso a sessões com um ID do utilizador, como userB.

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

Conceda acesso de escrita a sessões que contenham um prefixo específico no User ID

A condição seguinte concede ao indivíduo developerA@corp.com acesso de edição a quaisquer sessões que contenham o ID do utilizador que começa com user. Pode usar startsWith para verificar o prefixo e endsWith para verificar o sufixo.

Isto significa que o programador tem a capacidade de criar, atualizar e eliminar sessões, juntamente com a anexação de eventos, com IDs de utilizador, 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 contenham um de dois IDs de utilizadores

A seguinte condição concede ao grupo group:engineering@corp.com acesso de utilizador (leitor e editor) a sessões que tenham apenas IDs de utilizador 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

Limite de principal: as políticas de IAM estão limitadas a 1500 principais únicos. Este limite pode ser gerido através dos Grupos Google. Consulte mais informações em Limites em todos os responsáveis.
ListSessions Apoio técnico da API: a API ListSessions não suporta condições da IAM. Para conceder autorizações ListSessions, tem de conceder ao principal uma função incondicional, como aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionUser ou uma função incondicional relevante do Vertex AI.