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

Por padrão, as permissões do Identity and Access Management das sessões 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 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 na Common Expression Language. O User-ID é 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. Você pode 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 ver 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 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:
- Os usuários podem ver as sessões de outros usuários?
- Os desenvolvedores podem ver 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?
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 de sessão do Vertex AI Agent Engine, peça ao administrador para conceder a você os seguintes papéis do IAM:
- Para projetos: Administrador 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:
- 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 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:

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. É possível escolher um dos papéis especializados do IAM para sessões.
Adicione uma condição à função usando aiplatform.googleapis.com/sessionUserId 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 de sessão.
- CONDITION: adicione uma condição à função usando aiplatform.googleapis.com/sessionUserId 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 as políticas do IAM, inclua 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 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.sessionEditor.
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/sessionUserId 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 User-ID

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

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.
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 tipos e serviços não compatíveis são representados por um ID de usuário 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.
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 User IDs 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 especializados do IAM para sessões

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

Nome do papel	Descrição	Permissões incluídas
`roles/aiplatform.sessionViewer`	Concede acesso somente leitura a sessões e eventos de listagem.	`aiplatform.googleapis.com/sessions.get` `aiplatform.googleapis.com/sessions.list` `aiplatform.googleapis.com/sessionEvents.list`
`roles/aiplatform.sessionEditor`	Concede acesso de gravação 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 permissões de leitor e editor.	Inclui todas as permissões de `sessionEditor` e `sessionViewer`.

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:

Conceder acesso de leitura a sessões com correspondência exata de ID do usuário.
Conceder acesso de gravação a sessões que contêm um prefixo específico no ID do usuário.
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 User-ID

A condição a seguir concede ao indivíduo userA@gmail.com acesso à visualização apenas para sessões que têm o User ID exato userA.

Isso significa que a pessoa pode receber sessões e listar os eventos de sessão, desde que o User ID seja exatamente userA. O usuário não tem acesso a sessões com ID de 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 os 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

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 ListSessions: a API ListSessions não é compatível com condições do IAM. Para conceder permissões "ListSessions", atribua ao principal um papel incondicional, como aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionUser ou um papel incondicional relevante da Vertex AI.