Fazer a autenticação no Google Cloud usando a própria identidade de um agente

Os agentes podem acessar as APIs do Google Cloud e outros recursos usando a própria identidade. O Google recomenda esse método para que os agentes hospedados no Google Cloud interajam com outros serviços do Google Cloud .

Quando um agente age por conta própria, ele usa a identidade SPIFFE principal para solicitar tokens de acesso do Google Cloud .

Antes de começar

  1. Verifique se você escolheu o método de autenticação correto.
  2. Crie e implante um agente com a identidade de agente ativada.
  3. Verifique se você tem os papéis necessários para concluir esta tarefa.

Funções exigidas

Para receber as permissões necessárias para conceder a um agente acesso aos serviços do Google Cloud , peça ao administrador para conceder a você os seguintes papéis do IAM no recurso de destino:

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

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Conceder acesso aos agentes

Para permitir que o agente acesse um serviço do Google Cloud , é preciso conceder à identidade do agente os papéis necessários no recurso de destino.

Nas políticas de permissão do IAM, as identidades de agente usam identificadores de principal.

Para conceder a um agente acesso a um recurso, use o Google Cloud console ou a CLI gcloud.

Console

  1. No console do Google Cloud , acesse a página IAM do recurso a que você quer conceder acesso.
    • Para um projeto, acesse a página do IAM:

      Acessar a página do IAM

    • Para outros recursos, acesse a página do recurso e clique na guia Permissões ou IAM.
  2. Clique em Conceder acesso.
  3. No campo Novos principais, insira o identificador de principal que corresponde ao nível de acesso que você quer conceder:
    • Um único agente: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • Todos os agentes em um projeto: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • Todos os agentes em uma organização: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  4. No campo Selecionar um papel, pesquise e selecione o papel que você quer conceder.
  5. Clique em Salvar.

CLI do Google Cloud

Para conceder a um agente acesso a um recurso, execute o seguinte comando: 
gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

Substitua:

  • SERVICE: o serviço do Google Cloud (por exemplo, storage ou bigquery).
  • RESOURCE_NAME: o nome do recurso (por exemplo, o nome do bucket ou o ID do conjunto de dados).
  • PRINCIPAL_IDENTIFIER: o identificador principal que corresponde ao nível de acesso que você quer conceder:
    • Um único agente: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • Todos os agentes em um projeto: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • Todos os agentes em uma organização: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  • ORGANIZATION_ID: o ID da organização do Google Cloud .
  • PROJECT_NUMBER: o número do projeto do Google Cloud .
  • LOCATION: o local do agente (por exemplo, us-central1). Obrigatório apenas para acesso de agente único.
  • ENGINE_ID: o ID do mecanismo de raciocínio. (Obrigatório apenas para acesso de agente único.)
  • ROLE: o papel do IAM que você quer conceder.

Referenciar a identidade do agente no código

As bibliotecas de cliente do Google Cloud usam automaticamente a identidade do agente quando ele é implantado em um ambiente do Google Cloud compatível.

O snippet de Python a seguir mostra como usar manualmente as credenciais de identidade do agente para chamar a API Cloud Vision usando o Kit de Desenvolvimento de Agente (ADK).

from google.cloud import vision
from google.auth import default
from google.adk.tools import tool

@tool
def analyze_image_from_gcs(gcs_uri: str) -> dict:
    # Application default credentials automatically retrieve the
    # Agent Identity token from the metadata server.
    agent_identity_credentials, project_id = default()

    client = vision.ImageAnnotatorClient(
        credentials=agent_identity_credentials,
        project=project_id
    )

    # Prepare the image object with the Cloud Storage URI.
    image = vision.Image()
    image.source.image_uri = gcs_uri

    # Perform label detection on the image.
    response = client.label_detection(image=image)

    # Check for any errors returned by the API.
    if response.error.message:
        return {"status": "failure", "error_message": response.error.message}

    labels = response.label_annotations
    return {"status": "success", "labels": [label.description for label in labels]}

Opcional: desativar os tokens vinculados a certificados

Uma política de acesso baseado no contexto padrão gerenciada pelo Google ajuda a proteger as credenciais de identidade do agente. Além do Gateway de Agente, a política aplica a Demonstração de Prova de Posse (DPoP) autenticando o token de acesso do agente. A política também exige o TLS mútuo (mTLS) para acessar o Gateway de Agente. Esse requisito ajuda a garantir que apenas o ambiente de execução pretendido e confiável, como um contêiner do Cloud Run ou um pod do Google Kubernetes Engine (GKE), possa usar os tokens vinculados ao certificado. Essa referência de segurança impede que as credenciais roubadas sejam reutilizadas, ajudando a proteger contra roubo de credenciais e sequestro de conta (ATO, na sigla em inglês).

A vinculação de certificado ajuda a proteger dois tipos de credenciais de agente:

  • Tokens de acesso doGoogle Cloud : tokens de acesso do OAuth 2.0 de curta duração que autenticam solicitações para APIs do Google Cloud e outros recursos (*.googleapis.com).
  • Tokens de ID do OpenID Connect (OIDC): JSON Web Tokens (JWTs) que autenticam solicitações para serviços externos e para ferramentas e serviços hospedados em ambientes de execução do Google Cloud , como o Cloud Run (*.mtls.run.app) ou o GKE.

Desativar a vinculação para todos os tokens de acesso e de ID

Não é recomendável desativar a política padrão de acesso baseado no contexto e os tokens vinculados a certificados no ambiente de execução. Definir GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false remove a proteção de vinculação de token para tokens de acesso do Google Cloud e tokens de ID do OIDC, tornando esses tokens de curta duração vulneráveis a roubo ou ataques de repetição.

No entanto, é possível desativar o ambiente de execução nos seguintes casos raros:

  • Você tem requisitos específicos de compartilhamento de tokens entre agentes.
  • É preciso injetar o token diretamente no cabeçalho da solicitação.
  • Seu agente não consegue se autenticar e retorna um erro 401 UNAUTHENTICATED.

Para desativar o ambiente de execução, defina a seguinte variável de ambiente ao implantar o agente:

config={
  "env_vars": {
    "GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN": "false",
  }
}

Desativar solicitações de token de ID individuais

Por padrão, as bibliotecas de cliente do Google Auth compatíveis vinculam criptograficamente os tokens de ID do OIDC ao certificado X.509 exclusivo do agente, incluindo a impressão digital do certificado na declaração cnf (x5t#S256) do token.

Alguns serviços, como o Cloud Run, aplicam a vinculação de certificado quando a declaração cnf está presente. Se o agente chamar esses serviços por um endpoint que não seja mTLS, como um URL *.run.app padrão, ou se um endpoint de destino não exigir vinculação de certificado, será possível desativar as solicitações de token de ID individuais. Essa configuração afeta apenas essa solicitação e não desativa a vinculação de certificado para tokens de acesso do Google Cloud .

Python

Na biblioteca google-auth do Python (2.61.0 ou posterior no GKE e 2.62.0 ou posterior no Cloud Run), defina bind_id_token=False:

from google.auth.transport.requests import AuthorizedSession
from google.auth.transport.requests import Request
from google.oauth2 import id_token

target_audience = "https://TARGET_SERVICE_URL"

# Option 1: Use AuthorizedSession with IDTokenCredentials
credentials = id_token.fetch_id_token_credentials(
    audience=target_audience,
    bind_id_token=False,
)
authed_session = AuthorizedSession(credentials)
response = authed_session.get(target_audience)

# Option 2: Fetch a raw ID token directly
token = id_token.fetch_id_token(
    Request(),
    audience=target_audience,
    bind_id_token=False,
)

Substitua TARGET_SERVICE_URL pelo URI ou URL de público-alvo do serviço de recebimento que o agente chama.

Implantar o agente

Ao implantar o agente no Google Cloud, verifique se a identidade do agente está ativada. Se você estiver implantando no Agent Runtime na Gemini Enterprise Agent Platform, use a flag identity_type=AGENT_IDENTITY:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)

A seguir