Limitar as permissões do agente com credenciais com escopo

Quando o agente orquestrador chama um agente remoto Agent2Agent (A2A), o escopo das credenciais ajuda a garantir que o agente remoto receba apenas as permissões necessárias para essa solicitação. Depois de descobrir um agente no Registro de Agentes, inclua as credenciais do usuário ou gere tokens com escopo usando o gerenciador de autenticação de Identidade do Agente com escopos OAuth restritos ou limites de acesso a credenciais para o Cloud Storage.

Antes de começar

Antes de limitar as permissões do agente com credenciais com escopo para chamadas de app para app, siga estas etapas:

  1. Configure o Agent Registry.
  2. Para uma configuração de projeto único, use o ID do projeto da governança em que o Agent Registry está ativado. Se você configurou um limite de gerenciamento para vários projetos, use o ID do projeto de gerenciamento para descoberta e registro em todo o limite ou especifique um ID de projeto de membro para operações em um único projeto.

  3. Se você quiser restringir os tokens do Cloud Storage, ative a API Security Token Service (sts.googleapis.com) no seu projeto.

  4. Instale as bibliotecas Python google-auth e requests:

    pip install --upgrade google-auth requests
    
  5. Configure o Application Default Credentials (ADC) para desenvolvimento local. Caso contrário, anexe uma conta de serviço ou uma configuração de credencial da federação de identidade da carga de trabalho:

    gcloud auth application-default login
    

Funções exigidas

É possível usar sua conta de usuário para desenvolvimento local ou uma conta de serviço ou principal do agente para que o agente orquestrador descubra agentes registrados e chame agentes A2A de destino. A conta de usuário, a conta de serviço ou o principal do agente precisa ter os papéis apropriados para concluir essas tarefas.

Para garantir que sua conta de usuário, conta de serviço ou principal do agente tenha as permissões necessárias para descobrir agentes A2A no Agent Registry e chamar agentes A2A de destino, peça ao administrador para conceder os seguintes papéis do IAM à sua conta de usuário, conta de serviço ou principal do agente:

  • Para descobrir agentes no Agent Registry: Leitor da API Agent Registry (roles/agentregistry.viewer) no projeto de governança em que o Agent Registry está ativado.
  • Para chamar um agente A2A de destino no ambiente de execução: O papel de ambiente de execução ou gateway do serviço que hospeda o agente de destino, necessário para chamar esse agente. Por exemplo, se o agente de destino for executado no Cloud Run, a conta ou o principal precisará ter o papel de invocador do Cloud Run (roles/run.invoker).

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

O administrador também pode conceder à sua conta de usuário, conta de serviço ou principal do agente as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

Como as credenciais são transmitidas entre agentes

Quando um cliente A2A ou agente orquestrador envia uma mensagem para um agente remoto, os serviços downstream verificam as permissões com base em como a solicitação é autenticada:

  • Em nome de um usuário: um usuário faz login no seu agente orquestrador, que transmite um token OAuth 2.0 autorizado pelo usuário ou um token gerenciado pelo gerenciador de autenticação para o agente A2A remoto. As APIs do Google Cloud verificam o token e as permissões do Identity and Access Management (IAM) do usuário para que o agente remoto não possa acessar recursos que o usuário não tem permissão para acessar.
  • Usando a própria identidade do agente: quando um agente orquestrador é executado sem um usuário conectado, ele se autentica com a própria identidade de agente ou conta de serviço. Os serviços downstream verificam os papéis concedidos ao principal desse agente (principal://), a um conjunto de principais correspondente (principalSet://) ou à conta de serviço dele.
  • De cargas de trabalho externas ou entre nuvens: os agentes em execução fora doGoogle Cloud trocam tokens de um provedor de identidade externo pela federação de identidade da carga de trabalho para receber tokens de acesso federados do Google Cloud antes de chamar os endpoints do agente A2A de destino.

Para limitar as permissões que um token concede a um agente remoto, é possível limitar o escopo dos tokens OAuth com vinculações para agentes A2A de terceiros ou SaaS.

Também é possível restringir tokens do Cloud Storage usando um limite de acesso a credenciais para limitar um Google Cloud token de acesso a buckets do Cloud Storage ou objetos específicos do Cloud Storage. Os limites de acesso a credenciais são compatíveis apenas com as permissões do Cloud Storage (storage.googleapis.com). Para outras APIs do Google Cloud e chamadas de agente A2A, limite o acesso usando vinculações do gerenciador de autenticação, identidades de agente com privilégio mínimo com políticas de permissão e negação do IAM ou o Gateway de Agente.

Se essas opções não se adequarem ao seu caso de uso e o agente do orquestrador for autenticado com uma conta de serviço, também será possível usar a identidade temporária de conta de serviço para solicitar um token de curta duração para uma conta de serviço dedicada que tenha apenas os papéis necessários para uma tarefa específica.

Escopo de tokens OAuth com vinculações

Ao chamar um agente A2A de terceiros ou SaaS que usa o OAuth 2.0 de duas ou três etapas, crie um provedor de autenticação no gerenciador de autenticação e anexe um recurso Binding no registro de agentes que liste apenas o scopes do OAuth que o agente remoto precisa. Quando o Kit de Desenvolvimento de Agente (ADK) recupera o agente remoto usando get_remote_a2a_agent(), ele solicita tokens limitados aos escopos dessa vinculação. Para conferir as etapas de configuração, consulte Autenticar em ferramentas e recursos e Gerenciar vinculações.

Restringir tokens do Cloud Storage

Se o agente orquestrador transmitir um token de acesso OAuth 2.0 para um agente ou ferramenta que lê ou grava dados do Cloud Storage, é possível reduzir as permissões do token para permitir o acesso apenas a buckets ou prefixos de objeto específicos. Use o Security Token Service para aplicar um limite de acesso a credenciais antes de enviar a solicitação:

import google.auth
from google.auth import downscoped
from google.auth.transport.requests import Request

source_creds, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)

access_boundary_rule = downscoped.AccessBoundaryRule(
    available_resource=(
        "//storage.googleapis.com/projects/_/buckets/BUCKET_NAME"
    ),
    available_permissions=["inRole:roles/storage.objectViewer"],
)
cab = downscoped.CredentialAccessBoundary(rules=[access_boundary_rule])

downscoped_creds = downscoped.Credentials(
    source_credentials=source_creds,
    credential_access_boundary=cab,
)
downscoped_creds.refresh(Request())

Substitua BUCKET_NAME pelo nome do bucket do Cloud Storage que o agente remoto pode ler.

Controles de segurança adicionais

É possível combinar o escopo de credenciais com políticas de rede e inspeção de comandos:

A seguir