Autenticación en servicios externos con la identidad propia de un agente

Los agentes alojados en Google Cloud pueden usar su propia identidad para autenticarse en herramientas y servicios alojados en Google Cloud runtimes, como Cloud Run o Google Kubernetes Engine (GKE), solicitando un token de ID de OpenID Connect (OIDC) de Agent Identity. Los agentes también pueden usar estos tokens de ID para autenticarse en plataformas de nube de terceros, como Amazon Web Services (AWS) y Microsoft Azure, APIs personalizadas, API Gateways y backends locales.

Cuando un agente actúa por su propia autoridad para acceder a un servicio externo, Agent Identity emite un token de ID de OpenID Connect (OIDC). Este token web JSON (JWT) afirma la identidad SPIFFE del agente y está firmado por las claves de la entidad emisora para el dominio de confianza del agente (grupo de identidades para cargas de trabajo administrado). Los sistemas externos pueden verificar estos tokens sin Google Cloud credenciales ni SDKs a través de extremos públicos alojados por el Google Cloud servicio de tokens de seguridad:

  • Un extremo de OpenID Connect Discovery 1.0 (/.well-known/openid-configuration) que publica los metadatos del proveedor de OpenID y el extremo de clave pública (jwks_uri).
  • Un extremo de conjunto de claves web JSON (JWKS) (/openid/jwks) que entrega las claves públicas activas que se usan para verificar las firmas en los tokens de ID del agente.

Antes de comenzar

  1. Verifica que hayas elegido el método de autenticación correcto. Revisa cómo funcionan las identidades SPIFFE, los dominios de confianza, y las credenciales de agente en la descripción general de Agent Identity.
  2. Crea e implementa un agente con Agent Identity habilitado.
  3. Asegúrate de que tu servicio externo o proveedor de identidad cumpla con los siguientes requisitos:
  4. Identifica los siguientes valores de configuración para tu agente y el servicio externo de destino:
    • URL de la entidad emisora (iss reclamación): La URL de la entidad emisora del grupo de identidades para cargas de trabajo para tu organización (https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN) o proyecto (https://sts.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/TRUST_DOMAIN).
    • Público permitido (reclamación aud): El URI del público que espera el servicio externo o el proveedor de identidad cuando valida los tokens de ID.
  5. Verifica que tengas los roles necesarios para completar esta tarea.

Roles obligatorios

Para obtener los permisos que necesitas para implementar un agente con Agent Identity, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para implementar un agente con Agent Identity. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para implementar un agente con Agent Identity:

  • Implementa un agente en Agent Runtime en Gemini Enterprise Agent Platform:
    • aiplatform.reasoningEngines.create
    • aiplatform.reasoningEngines.update
  • Implementa un servicio de agente en Cloud Run:
    • run.services.create
    • run.services.update

También puedes obtener estos permisos con roles personalizados o otros roles predefinidos.

Obtén un token de ID de OIDC para un agente

Para configurar tu agente para obtener y enviar un token de ID de OIDC a un servicio externo, completa las siguientes tareas:

  1. Configura tu agente con Agent Identity
  2. Solicita un token de ID de OIDC en el código de la aplicación

Configura tu agente con Agent Identity

Habilita Agent Identity cuando implementes tu agente:

  • Si implementas tu agente en Agent Runtime en Gemini Enterprise Agent Platform , establece identity_type en AGENT_IDENTITY:

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

  • Si implementas un servicio de agente en contenedores en Cloud Run, pasa la marca --identity-type=agent-identity:

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

    Reemplaza lo siguiente:

    • SERVICE_NAME: El nombre de tu servicio de Cloud Run.
    • IMAGE_URL: La URL de la imagen de contenedor de tu agente.

Solicita un token de ID de OIDC en el código de la aplicación

En el código de la aplicación de tu agente, usa la biblioteca cliente de Google Auth para solicitar un token de ID de OIDC para tu público externo de destino. La biblioteca cliente controla la generación de tokens, el almacenamiento en caché local y la renovación automática desde el servidor de metadatos.

De forma predeterminada, las bibliotecas cliente de Google Auth compatibles vinculan criptográficamente los tokens de ID de OIDC al certificado X.509 único del agente, ya que incluyen la huella digital del certificado en la reclamación cnf (x5t#S256) del token. Los servicios receptores pueden validar de forma opcional esta reclamación con el certificado de cliente presentado durante un protocolo de enlace TLS mutuo (mTLS) o ignorar la reclamación si no aplican la vinculación de certificados.

Cloud Run aplica automáticamente la vinculación de certificados cuando la reclamación cnf está presente en un token de ID. Si tu agente llama a un servicio de Cloud Run con un token de ID vinculado, debes llamar a su extremo mTLS (*.mtls.run.app) a través de una conexión mTLS. Para seguir llamando a una URL *.run.app estándar, inhabilita la vinculación de certificados por solicitud (por ejemplo, configurando bind_id_token=False en Python) o en todo el entorno de ejecución con GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false. Para obtener ejemplos y versiones de bibliotecas compatibles, consulta Inhabilitar tokens vinculados a certificados.

En el siguiente ejemplo, se usa la biblioteca google-auth para solicitar un token de ID de OIDC y adjuntarlo como un token Bearer en una solicitud saliente:

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"},
)

Reemplaza lo siguiente:

  • EXTERNAL_SERVICE_AUDIENCE: El URI del público que espera tu servicio receptor (por ejemplo, bedrock.us-east-1.amazonaws.com o api.example.com).
  • EXTERNAL_SERVICE_ENDPOINT: La URL de la API externa o el extremo de backend al que llama tu agente.

Para obtener instrucciones y ejemplos de biblioteca cliente en otros lenguajes, como Go, Node.js y Java, consulta Obtén un token de ID. Las bibliotecas cliente para estos lenguajes admiten --identity-type=agent-identity. Las bibliotecas que admiten tokens de ID vinculados a certificados vinculan tokens de forma predeterminada y te permiten inhabilitarlos para solicitudes individuales.

Verifica los tokens de ID de Agent Identity

Cuando un servicio externo recibe un token de ID de OIDC de tu agente, verifica el token con cualquiera de los siguientes enfoques según el servicio de destino:

Usa la federación de Workload Identity integrada

Si tu servicio receptor se ejecuta en una plataforma de nube que admite la autenticación de IAM integrada o la federación de Workload Identity de OIDC, no necesitas escribir código de verificación de tokens personalizado:

  • Cloud Run: Si tu servicio receptor se ejecuta en Cloud Run con entrada autenticada (--no-allow-unauthenticated), Cloud Run valida los tokens de Agent Identity entrantes en la capa de entrada. Otorga al agente que llama el rol de Invocador de Cloud Run (roles/run.invoker) en el servicio receptor. Para obtener más información, consulta Autentícate en servidores de MCP en Cloud Run.

    Si tu servicio permite la entrada no autenticada y verifica los tokens en el código de la aplicación, consulta Verifica los tokens de manera programática.

  • Amazon Bedrock: Configura la autenticación de JWT entrante especificando la Google Cloud URL de descubrimiento del servicio de tokens de seguridad o la URL de la entidad emisora y tu público esperado. Para obtener instrucciones, consulta Configura el autorizador de JWT entrante en la documentación de AWS.

  • Microsoft Entra ID: Configura una credencial de identidad federada con la situación Otra entidad emisora. Especifica la Google Cloud URL de la entidad emisora del servicio de tokens de seguridad , el público esperado y el identificador del sujeto (reclamación sub). Para obtener instrucciones, consulta Crea una relación de confianza entre una app y un proveedor de identidad externo en la documentación de Microsoft Learn.

Verifica los tokens de manera programática

Si tu agente envía solicitudes a una API personalizada, un microservicio, una API Gateway o una carga de trabajo local, tu servicio receptor debe verificar el token de ID de OIDC entrante antes de otorgar acceso. Por lo general, tu agente pasa este token en el Authorization: Bearer TOKEN encabezado HTTP.

Para verificar los tokens de ID entrantes de manera programática, completa las siguientes tareas:

  1. Extrae y valida la URL de la entidad emisora del token
  2. Descubre y almacena en caché las claves de firma públicas
  3. Verifica la firma y las reclamaciones del token
  4. Autoriza la identidad SPIFFE del agente

Extrae y valida la URL de la entidad emisora del token

Cuando llega una solicitud entrante, lee la carga útil de JWT no verificada para extraer la reclamación iss (entidad emisora). Esta reclamación contiene la URL del grupo de identidades para cargas de trabajo del dominio de confianza del agente. Esta URL sirve como URL base para el documento de descubrimiento y las claves de firma públicas.

Antes de realizar cualquier solicitud de red saliente, verifica que la reclamación iss coincida con la URL del grupo de identidades para cargas de trabajo del servicio de tokens de seguridad Google Cloud esperada para tu organización o proyecto:

  • Dominios de confianza a nivel de la organización:

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

    Por ejemplo, para una organización con el ID 123456789012, TRUST_DOMAIN es agents.global.org-123456789012.system.id.goog.

  • Dominios de confianza a nivel del proyecto (para proyectos sin una organización):

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

    Por ejemplo, para un proyecto con el número 9876543210, TRUST_DOMAIN es agents.global.proj-9876543210.system.id.goog.

Descubre y almacena en caché las claves de firma públicas

Después de validar la URL de la entidad emisora, recupera y almacena en caché las claves de firma públicas del Google Cloud servicio de tokens de seguridad:

  1. Consulta el extremo de OpenID Connect Discovery: Agrega /.well-known/openid-configuration a la URL base de la entidad emisora y envía una solicitud HTTP GET no autenticada:

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • ORGANIZATION_ID: Es el ID de tu Google Cloud organización. Para un proyecto sin una organización, reemplaza organizations/ORGANIZATION_ID con projects/PROJECT_NUMBER.
    • TRUST_DOMAIN: El ID del grupo de identidades para cargas de trabajo del dominio de confianza de tu agente (por ejemplo, agents.global.org-123456789012.system.id.goog).

    Método HTTP y URL: 

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

    Para enviar tu solicitud, expande una de estas opciones:

    Si la solicitud se realiza correctamente, se muestra un estado HTTP 200 OK y un objeto JSON que contiene los metadatos del proveedor de OpenID, incluido el 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. Consulta el extremo del conjunto de claves web JSON (JWKS): Envía una solicitud HTTP GET no autenticada a la jwks_uri URL que se muestra en los metadatos del proveedor de OpenID:

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • ORGANIZATION_ID: Es el ID de tu Google Cloud organización. Para un proyecto sin una organización, reemplaza organizations/ORGANIZATION_ID con projects/PROJECT_NUMBER.
    • TRUST_DOMAIN: El ID del grupo de identidades para cargas de trabajo del dominio de confianza de tu agente (por ejemplo, agents.global.org-123456789012.system.id.goog).

    Método HTTP y URL: 

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

    Para enviar tu solicitud, expande una de estas opciones:

    Si la solicitud se realiza correctamente, se muestra un estado HTTP 200 OK y un objeto JSON que contiene un array de claves públicas con el formato según RFC 7517:

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

  3. Almacena en caché el documento de descubrimiento y las claves: Las respuestas de ambos extremos, el de OpenID Connect Discovery y el de JWKS, incluyen el siguiente encabezado de caché HTTP:

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

    Almacena en caché el documento de descubrimiento y JWKS por hasta 24 horas ( 86400 segundos) para mejorar el rendimiento de la verificación y evitar la límite de frecuencia.

    Google Cloud rota periódicamente las claves de firma privadas y públicas para los grupos de identidades para cargas de trabajo. Si tu verificador recibe un token entrante con un kid (ID de clave) que no está en su caché de claves local, recupera un JWKS nuevo del extremo /openid/jwks antes de rechazar el token.

    Si encuentras errores de HTTP cuando consultas los extremos de descubrimiento o JWKS, consulta Soluciona problemas de autenticación de Agent Identity.

Verifica la firma y las reclamaciones del token

Para verificar criptográficamente la firma del token y validar las reclamaciones de JWT, usa una biblioteca de verificación de OIDC o JWT estándar (como Google Tink) y haz lo siguiente:

  1. Firma: Busca la clave pública en el JWKS almacenado en caché que coincida con el kid (ID de clave) en el encabezado JWT. Valida la firma con el algoritmo especificado en el campo alg (RS256). Para la compatibilidad con versiones anteriores, inspecciona los campos alg y kty en el JWKS de forma dinámica en lugar de codificar de forma rígida los tipos de algoritmos.
  2. Entidad emisora (iss): Confirma que la reclamación iss coincida con la URL de la entidad emisora del grupo de identidades para cargas de trabajo de confianza Google Cloud para tu dominio de confianza.
  3. Público (aud): Confirma que la reclamación aud coincida con el identificador de público configurado de tu servicio.
  4. Hora de emisión (iat) y hora de vencimiento (exp): Verifica que la reclamación iat esté en el pasado y que la hora actual sea anterior a la reclamación exp (lo que permite una pequeña tolerancia de desviación del reloj, como de 1 a 2 minutos).

En el siguiente ejemplo, se usa Google Tink (tink.jwt) para verificar un token de ID de Agent Identity con una carga útil de JSON de 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)

Autoriza la identidad SPIFFE del agente

Después de verificar la firma del token y las reclamaciones estándar, inspecciona la reclamación sub (sujeto) verificada para autorizar la solicitud y registrar el agente que llama en tus registros de auditoría.

La reclamación sub contiene el ID SPIFFE único del agente , por ejemplo:

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

En la lógica de autorización de tu servicio, compara la reclamación sub verificada con una lista de entidades permitidas de IDs SPIFFE de agentes de confianza (o prefijos de dominio de confianza) antes de otorgar acceso a los recursos protegidos.

¿Qué sigue?