Autenticar serviços externos usando a própria identidade de um agente

Os agentes hospedados em Google Cloud podem usar a própria identidade para autenticar ferramentas e serviços hospedados em tempos de execução Google Cloud , como o Cloud Run ou o Google Kubernetes Engine (GKE), solicitando um token de ID do OpenID Connect (OIDC) da identidade do agente. Os agentes também podem usar esses tokens de ID para autenticar plataformas de nuvem de terceiros (como Amazon Web Services [AWS] e Microsoft Azure), APIs personalizadas, gateways de API e back-ends locais.

Quando um agente age por conta própria para acessar um serviço externo, a identidade do agente emite um token de ID do OpenID Connect (OIDC). Esse JSON Web Token (JWT) declara a identidade SPIFFE do agente e é assinado pelas chaves do emissor para o domínio de confiança do agente (pool de identidades de carga de trabalho gerenciado). Sistemas externos podem verificar esses tokens sem Google Cloud credenciais ou SDKs usando endpoints públicos hospedados pelo Google Cloud Security Token Service:

  • Um endpoint do OpenID Connect Discovery 1.0 (/.well-known/openid-configuration) que publica os metadados do provedor OpenID e o endpoint de chave pública (jwks_uri).
  • Um endpoint do conjunto de chaves da Web JSON (JWKS) (/openid/jwks) que veicula as chaves públicas ativas usadas para verificar assinaturas em tokens de ID do agente.

Antes de começar

  1. Verifique se você escolheu o método de autenticação correto. Confira como as identidades SPIFFE, os domínios de confiança e as credenciais do agente funcionam na visão geral da identidade do agente.
  2. Crie e implante um agente com a Identidade do agente ativada.
  3. Verifique se o serviço ou provedor de identidade externo atende aos seguintes requisitos:
  4. Identifique os seguintes valores de configuração para seu agente e serviço externo de destino:
    • URL do emissor (declaração iss): o URL do emissor do pool de identidades da carga de trabalho da sua organização (https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN) ou projeto (https://sts.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/TRUST_DOMAIN).
    • Público-alvo permitido (declaração aud): o URI de público-alvo que o serviço externo ou o provedor de identidade espera ao validar tokens de ID.
  5. Verifique se você tem os papéis necessários para concluir esta tarefa.

Funções exigidas

Para receber as permissões necessárias para implantar um agente com a identidade do agente, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

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 implantar um agente com a identidade do agente. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para implantar um agente com a identidade do agente:

  • Implante um agente no Agent Runtime na Gemini Enterprise Agent Platform:
    • aiplatform.reasoningEngines.create
    • aiplatform.reasoningEngines.update
  • Implante um serviço de agente no Cloud Run:
    • run.services.create
    • run.services.update

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Receber um token de ID do OIDC para um agente

Para configurar o agente para receber e enviar um token de ID do OIDC a um serviço externo, conclua as seguintes tarefas:

  1. Configurar seu agente com a identidade do agente
  2. Solicitar um token de ID do OIDC no código do aplicativo

Configurar seu agente com a identidade do agente

Ative a identidade do agente ao implantar o agente:

  • Se você implantar seu agente no Agent Runtime na Gemini Enterprise Agent Platform , defina identity_type como AGENT_IDENTITY:

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

  • Se você implantar um serviço de agente em contêiner no Cloud Run, transmita a flag --identity-type=agent-identity:

    gcloud run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --identity-type=agent-identity \
    --no-allow-unauthenticated

    Substitua:

    • SERVICE_NAME: o nome do seu serviço do Cloud Run.
    • IMAGE_URL: o URL da imagem do contêiner do seu agente.

Solicitar um token de ID do OIDC no código do aplicativo

No código do aplicativo do seu agente, use a biblioteca de cliente de autenticação do Google para solicitar um token de ID do OIDC para seu público-alvo externo. A biblioteca de cliente processa a geração de tokens, o armazenamento em cache local e a renovação automática do servidor de metadados.

Por padrão, os tokens de ID do OIDC emitidos para públicos-alvo externos não são vinculados ao certificado de tempo de execução.

O exemplo a seguir usa a biblioteca google-auth para solicitar um token de ID do OIDC e anexá-lo como um token Bearer em uma solicitação de saída:

Python

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

# 1. Specify the audience expected by the external receiver
# (for example, AWS Bedrock AgentCore or your external service URL).
target_audience = "https://EXTERNAL_SERVICE_AUDIENCE"

# 2. Create ID token credentials and an AuthorizedSession, which handles
# local token caching, automatic renewal before expiry, and the Bearer header.
credentials = id_token.fetch_id_token_credentials(audience=target_audience)
authed_session = AuthorizedSession(credentials)

# 3. Send the authenticated request to the external service.
response = authed_session.post(
    "https://EXTERNAL_SERVICE_ENDPOINT",
    json={"prompt": "Hello from Agent"},
)

Substitua:

  • EXTERNAL_SERVICE_AUDIENCE: o URI do público-alvo esperado pelo serviço de recebimento (por exemplo, bedrock.us-east-1.amazonaws.com ou api.example.com).
  • EXTERNAL_SERVICE_ENDPOINT: o URL da API externa ou do endpoint de back-end que seu agente chama.

Para instruções e exemplos de biblioteca de cliente em outras linguagens de programação (incluindo Go, Node.js e Java), consulte Receber um token de ID. As versões atuais das biblioteca de cliente para essas linguagens oferecem suporte a --identity-type=agent-identity, mas não usam tokens vinculados por padrão.

Verificar tokens de ID de identidade do agente

Quando um serviço externo recebe um token de ID do OIDC do seu agente, verifique o token usando uma das seguintes abordagens com base no serviço de destino:

Usar a federação de identidade da carga de trabalho integrada

Se o serviço de recebimento for executado em uma plataforma de nuvem que ofereça suporte à autenticação integrada do IAM ou à federação de identidade da carga de trabalho do OIDC, não será necessário escrever um código personalizado de verificação de token:

  • Cloud Run: se o serviço de recebimento for executado no Cloud Run com entrada autenticada (--no-allow-unauthenticated), o Cloud Run vai validar os tokens de identidade do agente na camada de entrada. Conceda ao agente de chamada o papel de Invocador do Cloud Run (roles/run.invoker) no serviço de recebimento. Para mais informações, consulte Autenticar servidores MCP no Cloud Run.

    Se o serviço permitir entrada não autenticada e verificar tokens no código do aplicativo, consulte Verificar tokens de maneira programática.

  • Amazon Bedrock: configure a autenticação JWT de entrada especificando o URL de descoberta ou de emissor doGoogle Cloud Security Token Service e seu público-alvo esperado. Para instruções, consulte Configurar um autorizador JWT de entrada na documentação da AWS.

  • Microsoft Entra ID: configure uma credencial de identidade federada com o cenário Outro emissor. Especifique o URL do emissor do serviço de token de segurança Google Cloud , o público-alvo esperado e o identificador do assunto (declaração sub). Para instruções, consulte Criar uma relação de confiança entre um app e um provedor de identidade externo na documentação do Microsoft Learn.

Verificar tokens de maneira programática

Se o agente enviar solicitações para uma API personalizada, um microsserviço, um gateway de API ou uma carga de trabalho local, o serviço de recebimento precisará verificar o token de ID do OIDC recebido antes de conceder acesso. Normalmente, o agente transmite esse token no cabeçalho HTTP Authorization: Bearer TOKEN.

Para verificar os tokens de ID recebidos de forma programática, conclua as seguintes tarefas:

  1. Extrair e validar o URL do emissor do token
  2. Descobrir e armazenar em cache as chaves de assinatura públicas
  3. Verificar a assinatura e as declarações do token
  4. Autorizar a identidade SPIFFE do agente

Extrair e validar o URL do emissor do token

Quando uma solicitação chega, leia o payload do JWT não verificado para extrair a declaração iss (emissor). Essa declaração contém o URL do pool de identidade da carga de trabalho para o domínio de confiança do agente. Esse URL serve como o URL base para o documento de descoberta e as chaves de assinatura públicas.

Antes de fazer qualquer solicitação de rede de saída, verifique se a declaração iss corresponde ao URL esperado do pool de identidades da carga de trabalho do Serviço de token de segurança Google Cloud para sua organização ou projeto:

  • Domínios de confiança no nível da organização:

    https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN

    Por exemplo, para uma organização com ID 123456789012, TRUST_DOMAIN é agents.global.org-123456789012.system.id.goog.

  • Domínios de confiança no nível do projeto (para projetos sem uma organização):

    https://sts.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/TRUST_DOMAIN

    Por exemplo, para um projeto com o número 9876543210, TRUST_DOMAIN é agents.global.proj-9876543210.system.id.goog.

Descobrir e armazenar em cache as chaves de assinatura públicas

Depois de validar o URL do emissor, recupere e armazene em cache as chaves públicas de assinatura do Serviço de token de segurança Google Cloud :

  1. Consulte o endpoint de descoberta do OpenID Connect: adicione /.well-known/openid-configuration ao URL base do emissor e envie uma solicitação HTTP GET não autenticada:

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • ORGANIZATION_ID: o ID da organização Google Cloud. Para um projeto sem uma organização, substitua organizations/ORGANIZATION_ID por projects/PROJECT_NUMBER.
    • TRUST_DOMAIN: o ID do pool de identidades da carga de trabalho para o domínio de confiança do seu agente (por exemplo, agents.global.org-123456789012.system.id.goog).

    Método HTTP e URL: 

    GET https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/.well-known/openid-configuration

    Para enviar a solicitação, expanda uma destas opções:

    Uma solicitação bem-sucedida retorna um status HTTP 200 OK e um objeto JSON que contém os metadados do provedor OpenID, incluindo o campo jwks_uri:

    {
  "issuer": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog",
  "jwks_uri": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog/openid/jwks",
  "authorization_endpoint": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog/authorize",
  "token_endpoint": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog/token",
  "response_types_supported": [
    "id_token"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ]
}

  2. Consultar o endpoint do conjunto de chaves da Web JSON (JWKS): envie uma solicitação HTTP GET não autenticada para o URL jwks_uri retornado nos metadados do provedor OpenID:

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • ORGANIZATION_ID: o ID da organização Google Cloud. Para um projeto sem uma organização, substitua organizations/ORGANIZATION_ID por projects/PROJECT_NUMBER.
    • TRUST_DOMAIN: o ID do pool de identidades da carga de trabalho para o domínio de confiança do seu agente (por exemplo, agents.global.org-123456789012.system.id.goog).

    Método HTTP e URL: 

    GET https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/openid/jwks

    Para enviar a solicitação, expanda uma destas opções:

    Uma solicitação bem-sucedida retorna um status HTTP 200 OK e um objeto JSON que contém uma matriz de chaves públicas formatadas de acordo com a RFC 7517:

    {
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "4d1933f8e6c4e0b512c140989f6655c68997...",
      "n": "uQn4zN_1mQ0VpGv82-Wp3w...",
      "e": "AQAB"
    }
  ]
}

  3. Armazenar em cache o documento de descoberta e as chaves: as respostas do endpoint de descoberta do OpenID Connect e do endpoint JWKS incluem o seguinte cabeçalho de cache HTTP:

    Cache-Control: public, max-age=86400, must-revalidate

    Faça o cache do documento de descoberta e do JWKS por até 24 horas (86400 segundos) para melhorar o desempenho da verificação e evitar a limitação de taxa.

    OGoogle Cloud alterna periodicamente as chaves de assinatura privada e pública para pools de identidades de carga de trabalho. Se o verificador receber um token com um kid (ID da chave) que não está no cache de chaves local, busque um JWKS atualizado no endpoint /openid/jwks antes de rejeitar o token.

    Se você encontrar erros HTTP ao consultar os endpoints de descoberta ou JWKS, consulte Solução de problemas de autenticação de identidade do agente.

Verificar a assinatura e as declarações do token

Para verificar criptograficamente a assinatura do token e validar as declarações do JWT, use uma biblioteca padrão de verificação do OIDC ou JWT (como Google Tink) e faça o seguinte:

  1. Assinatura: encontre a chave pública no JWKS em cache que corresponda ao kid (ID da chave) no cabeçalho do JWT. Valide a assinatura usando o algoritmo especificado no campo alg (RS256). Para compatibilidade futura, inspecione os campos alg e kty no JWKS dinamicamente em vez de codificar tipos de algoritmos.
  2. Emissor (iss): confirme se a declaração iss corresponde ao URL do emissor do pool de identidades da carga de trabalhoGoogle Cloud confiável para seu domínio de confiança.
  3. Público-alvo (aud): confirme se a declaração aud corresponde ao identificador de público-alvo configurado do seu serviço.
  4. Horário de emissão (iat) e horário de expiração (exp): verifique se a declaração iat está no passado e se o horário atual é anterior à declaração exp (permitindo uma pequena tolerância de diferença de relógio, como de 1 a 2 minutos).

O exemplo a seguir usa o Google Tink (tink.jwt) para verificar um token de ID de identidade do agente em relação a um payload JSON JWKS:

Python

import tink
from tink import jwt

# Initialize Tink JWT signature primitives (call once at application startup).
jwt.register_jwt_signature()


def verify_agent_identity_token(
    token: str,
    jwks_json: str,
    expected_issuer: str,
    expected_audience: str,
) -> jwt.VerifiedJwt:
    """Verifies an Agent Identity JWT against a JWKS JSON string using Tink.

    Args:
        token: The compact serialized JWT string.
        jwks_json: The JWKS JSON string fetched from the STS pool endpoint.
        expected_issuer: The expected token issuer ('iss' claim).
        expected_audience: The expected token audience ('aud' claim).

    Returns:
        jwt.VerifiedJwt: The verified JWT claims object.

    Raises:
        tink.TinkError: If the JWKS cannot be parsed, the key is not found,
            or token validation (signature, issuer, audience, expiration) fails.
    """
    # 1. Convert the JWKS JSON into a Tink public KeysetHandle.
    keyset_handle = jwt.jwk_set_to_public_keyset_handle(jwks_json)

    # 2. Instantiate the Tink JwtPublicKeyVerify primitive.
    jwt_verifier = keyset_handle.primitive(jwt.JwtPublicKeyVerify)

    # 3. Configure expected validation rules (issuer, audience, expiration).
    # Google Cloud STS sets 'typ': 'JWT' in the header, so
    # expected_type_header="JWT" is required.
    validator = jwt.new_validator(
        expected_issuer=expected_issuer,
        expected_audience=expected_audience,
        expected_type_header="JWT",
        allow_missing_expiration=False,
    )

    # 4. Cryptographically verify the signature and standard OIDC claims.
    return jwt_verifier.verify_and_decode(token, validator)

Autorizar a identidade SPIFFE do agente

Depois de verificar a assinatura e as declarações padrão do token, inspecione a declaração sub (assunto) verificada para autorizar a solicitação e registrar o agente de chamada nos registros de auditoria.

A declaração sub contém o ID SPIFFE exclusivo do agente, por exemplo:

  spiffe://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-test-agent

Na lógica de autorização do seu serviço, compare a declaração sub verificada com uma lista de permissões de IDs SPIFFE de agentes confiáveis (ou prefixos de domínio de confiança) antes de conceder acesso a recursos protegidos.

A seguir