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

A Identidade do agente permite que seus agentes Google Cloud usem a própria identidade para autenticar serviços externos e cargas de trabalho hospedadas no Cloud Run ou no Google Kubernetes Engine (GKE). Ao usar tokens de ID do OpenID Connect (OIDC), é possível conectar agentes a 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, a Identidade do agente emite um token de ID do OIDC, que é um JSON Web Token (JWT) que declara a identidade SPIFFE do agente e é assinado pelas chaves do emissor para o domínio de confiança do agente (pool de identidade da carga de trabalho gerenciada). Sistemas externos podem verificar esses tokens de ID sem Google Cloud credenciais ou SDKs por 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.

Para autenticar seu agente em Google Cloud APIs e recursos usando a própria identidade, consulte Autenticar em Google Cloud usando a própria identidade de um agente. Para acessar serviços em nome de um usuário final, consulte Autenticar usando o OAuth de três etapas com o gerenciador de autenticação.

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 externo ou o provedor de identidade atende aos seguintes requisitos:

  4. Identifique os seguintes valores de configuração para o agente e o serviço externo de destino:

    • URL do emissor (iss declaração): o URL do emissor do pool de identidade da carga de trabalho para 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 do 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 essa 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 que são 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:

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

Essas permissões também podem ser concedidas com papéis personalizados 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 o agente com a Identidade do agente
  2. Solicitar um token de ID do OIDC no código do aplicativo

Configurar o agente com a Identidade do agente

Ative a Identidade do agente ao implantar o agente:

  • Se você implantar o 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 serviço do Cloud Run.
    • IMAGE_URL: o URL da imagem de contêiner do agente.

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

No código do aplicativo do agente, use a biblioteca de cliente do Google Auth para solicitar um token de ID do OIDC para o público-alvo externo de destino. 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, as bibliotecas de cliente do Google Auth com suporte vinculam criptograficamente 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. Os serviços de recebimento podem validar essa declaração opcionalmente em relação ao certificado do cliente apresentado durante um handshake de TLS mútuo (mTLS) ou ignorar a declaração se não aplicarem a vinculação de certificados.

O Cloud Run aplica automaticamente a vinculação de certificados quando a declaração cnf está presente em um token de ID. Se o agente chamar um serviço do Cloud Run usando um token de ID vinculado, será necessário chamar o endpoint mTLS (*.mtls.run.app) em uma conexão mTLS. Para continuar chamando um URL *.run.app padrão, desative a vinculação de certificados por solicitação (por exemplo, definindo bind_id_token=False no Python) ou em todo o ambiente de execução com GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false. Para versões e exemplos de bibliotecas com suporte, consulte Desativar tokens vinculados a certificados.

Ao chamar um endpoint que aplica a vinculação de certificados no mTLS, configure a sessão do cliente para apresentar o certificado X.509 do agente durante o handshake mTLS (por exemplo, chamando authed_session.configure_mtls_channel() no Python).

Os exemplos a seguir usam a biblioteca google-auth para solicitar um token de ID do OIDC vinculado a um certificado, configurar opcionalmente o canal mTLS e anexar o token 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 o agente chama.

Python (mTLS)

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

# 1. Specify the audience expected by the receiving service
# (for example, a regional Cloud Run mTLS URL or an on-premises mTLS endpoint).
target_audience = "https://EXTERNAL_SERVICE_AUDIENCE"

# 2. Create certificate-bound ID token credentials and configure the mTLS
# channel to present the agent's X.509 certificate.
credentials = id_token.fetch_id_token_credentials(audience=target_audience)
authed_session = AuthorizedSession(credentials)
authed_session.configure_mtls_channel()

# 3. Send the authenticated request over mTLS.
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, um URL mTLS regional do Cloud Run ou api.example.com).
  • EXTERNAL_SERVICE_ENDPOINT: o URL da API mTLS ou do endpoint de back-end que o agente chama.

Para instruções e exemplos de biblioteca de cliente em outras linguagens, como Go, Node.js e Java, consulte Receber um token de ID. As bibliotecas de cliente para essas linguagens oferecem suporte a --identity-type=agent-identity. As bibliotecas que oferecem suporte a tokens de ID vinculados a certificados vinculam tokens por padrão e permitem que você desative para solicitações individuais.

Verificar tokens de ID da Identidade do agente

Quando um serviço externo recebe um token de ID do OIDC do 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 oferece suporte à autenticação do IAM integrada ou à federação de identidade da carga de trabalho do OIDC, não será necessário gravar um código de verificação de token personalizado:

  • 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 recebidos na camada de entrada. Quando o token inclui a declaração cnf, configure o agente de chamada para direcionar o URL mTLS regional do serviço de recebimento (https://SERVICE_NAME-PROJECT_NUMBER.REGION.mtls.run.app) para que o Cloud Run possa validar o certificado do cliente durante o handshake mTLS. 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 em servidores MCP no Cloud Run.

    Se o serviço permitir a 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 Google Cloud URL de descoberta ou o URL do emissor do Security Token Service e o público-alvo esperado. Para instruções, consulte Configurar o 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 Google Cloud Security Token Service URL do emissor, o público-alvo esperado e o identificador do assunto (sub declaração). 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 Authorization: Bearer TOKEN cabeçalho HTTP.

Para verificar tokens de ID recebidos de maneira 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. Opcional: validar a vinculação de certificados (declaração cnf)
  5. Autorizar a identidade SPIFFE do agente

Extrair e validar o URL do emissor do token

Quando uma solicitação recebida chega, leia o payload 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 de 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 Google Cloud do pool de identidade da carga de trabalho do Security Token Service 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 o 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 de assinatura públicas do Google Cloud Security Token Service:

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

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

    • ORGANIZATION_ID: o Google Cloud ID da organização. Para um projeto sem uma organização, substitua organizations/ORGANIZATION_ID por projects/PROJECT_NUMBER.
    • TRUST_DOMAIN: o ID do pool de identidade da carga de trabalho para o domínio de confiança do 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 contendo 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 estas substituições:

    • ORGANIZATION_ID: o Google Cloud ID da organização. Para um projeto sem uma organização, substitua organizations/ORGANIZATION_ID por projects/PROJECT_NUMBER.
    • TRUST_DOMAIN: o ID do pool de identidade da carga de trabalho para o domínio de confiança do 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 contendo 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 de ambos os endpoints do OpenID Connect Discovery e do JWKS incluem o seguinte cabeçalho de cache HTTP:

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

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

    Google Cloud periodicamente gira as chaves de assinatura privadas e públicas para pools de identidade da carga de trabalho. Se o verificador receber um token de entrada com um kid (ID da chave) que não está no cache de chaves local, busque um JWKS novo no endpoint /openid/jwks antes de rejeitar o token.

    Se você encontrar erros de HTTP ao consultar os endpoints de descoberta ou JWKS, consulte Resolver problemas de autenticação da Identidade do Agente.

Verificar a assinatura e as declarações do token

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

  1. Assinatura: encontre a chave pública no JWKS armazenado em cache que corresponde ao kid (ID da chave) no cabeçalho JWT. Valide a assinatura usando o algoritmo especificado no campo alg (RS256). Para compatibilidade com versões anteriores, inspecione os campos alg e kty no JWKS de maneira dinâmica em vez de codificar tipos de algoritmo.
  2. Emissor (iss): confirme se a declaração iss corresponde ao URL do emissor do pool de identidade da carga de trabalho confiável Google Cloud para o 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 serviço.
  4. Hora de emissão (iat) e hora de expiração (exp): verifique se a declaração iat está no passado e se a hora atual é anterior à declaração exp (permitindo uma pequena tolerância de distorção de relógio, como 1 a 2 minutos).

O exemplo a seguir usa o Google Tink (tink.jwt) para verificar um token de ID da Identidade do agente em relação a um payload JSON do 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)

Opcional: validar a vinculação de certificados (declaração cnf)

Se o serviço de recebimento aplicar a vinculação de certificados no mTLS, valide a declaração cnf (x5t#S256) em relação ao certificado do cliente apresentado durante o handshake mTLS:

  1. Encerrar o TLS mútuo (mTLS): configure o servidor ou proxy de entrada para solicitar e validar o certificado X.509 do agente durante o handshake de TLS de acordo com o TLS 1.3 (RFC 9846).
  2. Calcular a impressão digital do certificado (x5t#S256): extraia o certificado do cliente X.509 da conexão mTLS. Calcule o hash SHA-256 nos bytes codificados por DER e codifique o resumo em base64url sem preenchimento =.
  3. Validar a declaração cnf (x5t#S256): inspecione o payload JWT verificado para o objeto cnf ({"cnf": {"x5t#S256": "FINGERPRINT"}}) e verifique se o valor x5t#S256 corresponde à impressão digital do certificado do cliente de acordo com a seção 6.1 da RFC 8705. Se o autor da chamada não apresentar um certificado do cliente no mTLS ou se as impressões digitais não corresponderem, rejeite a solicitação com uma resposta HTTP 401 Unauthorized.

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 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