Soluciona problemas de autenticación de identidad del agente

En este documento, se describe cómo resolver errores comunes cuando se autentican agentes con Agent Identity y el administrador de autenticación de Agent Identity.

Para obtener instrucciones sobre cómo configurar proveedores de autenticación, consulta Administra proveedores de autenticación de Agent Identity. Para obtener instrucciones sobre cómo verificar los tokens de ID de Agent Identity en servicios externos, consulta Autenticación en servicios externos con la identidad propia de un agente.

Los URI de redireccionamiento no coinciden

Si recibes un error redirect URI mismatch de la aplicación de terceros durante el flujo de OAuth, asegúrate de que el URI de redireccionamiento registrado en el portal para desarrolladores de terceros coincida exactamente con el URI generado por el administrador de autorización.

Para resolver este problema, busca el URI de redireccionamiento generado. Para ello, consulta los detalles del proveedor de autenticación en la consola de Google Cloud o ejecuta el siguiente comando de gcloud:

gcloud alpha agent-identity authProviders describe AUTH_PROVIDER_NAME \
    --location="LOCATION"

Falta el rol del usuario

Si tu agente no puede usar el proveedor de autenticación, verifica que la identidad del agente tenga el rol roles/agentidentity.user en el recurso del proveedor de autenticación.

Para resolver este problema, otorga el rol con la consola de Google Cloud o ejecuta el comando add-iam-policy-binding.

Problemas con el extremo de la entidad emisora

En el caso de los proveedores de OIDC, verifica que se pueda acceder públicamente al extremo del emisor y que admita el documento de descubrimiento .well-known/openid-configuration.

Si Google Cloud no puede recuperar los metadatos de OIDC o el JWKS, asegúrate de que el extremo no esté detrás de un firewall o una red restringida.

Error 401 UNAUTHENTICATED

Si tu agente no puede autenticarse, es posible que se produzca el siguiente error. Por lo general, este error se debe a una política de Acceso adaptado al contexto administrada por Google que aplica la vinculación de mTLS y las pruebas criptográficas de DPoP:

{
  "error": {
    "code": 401,
    "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
    "status": "UNAUTHENTICATED"
  }
}

Para resolver este error, puedes inhabilitar la política predeterminada de Acceso adaptado al contexto cuando tengas requisitos específicos para compartir tokens o debas insertar el token directamente en el encabezado. Para inhabilitar esta opción, configura la siguiente variable de entorno cuando implementes tu agente:

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

Servicio de clave de API bloqueado (API_KEY_SERVICE_BLOCKED)

Si validas tu clave de API, es posible que se produzca el siguiente error. Este error indica que el servicio está bloqueado:

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_SERVICE_BLOCKED",
    "domain": "googleapis.com",
    "metadata": {
      "methodName": "google.cloud.translate.v2.TranslateService.TranslateText",
      "service": "translate.googleapis.com",
      "consumer": "projects/PROJECT_NUMBER",
      "apiName": "translate"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "Requests to this API translate method google.cloud.translate.v2.TranslateService.TranslateText are blocked."
  }
]

Este error se produce porque el servicio de la API de destino (por ejemplo, la API de Cloud Translation) no se habilitó en tu proyecto de Google Cloud o porque las restricciones de la clave de API no permiten el acceso a este servicio.

Para resolver este error, sigue estos pasos:

  1. En la consola de Google Cloud , ve a la página APIs y servicios >Biblioteca y asegúrate de que la API de destino esté habilitada.

    Ve a APIs y servicios >Biblioteca.

  2. En la consola de Google Cloud , ve a la página APIs y servicios >Credenciales, edita tu clave de API y verifica que sus restricciones de API permitan el acceso al servicio.

    Ir a APIs y servicios >Credenciales

La clave de API no es válida (API_KEY_INVALID)

Cuando envías solicitudes a un servicio de terceros, es posible que se produzca el siguiente error. Este error indica que la clave de API no es válida:

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_INVALID",
    "domain": "googleapis.com",
    "metadata": {
      "service": "translate.googleapis.com"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "API key not valid. Please pass a valid API key."
  }
]

Este error se produce porque la cadena de la clave de API que se pasó en el encabezado de la solicitud es incorrecta, está mal formada o no existe en las credenciales de tu proyecto.

Para resolver este error, verifica que hayas copiado la cadena de clave de API correcta de la página Credenciales en la consola de Google Cloud y que no hayas incluido espacios en blanco iniciales o finales.

Se denegó el permiso para recuperar credenciales (agentidentity.authProviders.retrieveCredentials)

Cuando ejecutas adk web de forma local o interactúas con tu agente implementado, es posible que se produzca el siguiente error de 403 Forbidden:

google.api_core.exceptions.Forbidden: 403 POST https://agentidentitycredentials.mtls.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME/credentials:retrieve?%24alt=json%3Benum-encoding%3Dint: Permission 'agentidentity.authProviders.retrieveCredentials' denied on resource '//agentidentity.googleapis.com/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME' (or it may not exist).

Este error se produce porque el principal que intenta invocar al proveedor de autenticación no tiene los permisos de IAM necesarios para recuperar credenciales.

Para resolver este error, otorga el rol de Usuario de identidad del agente (roles/agentidentity.user) a la entidad principal:

  • Si este error se produce durante el desarrollo local (uv run adk web o uvicorn), asegúrate de haber otorgado el rol a tu cuenta de usuario personal (user:USER_EMAIL).
  • Si este error se produce cuando interactúas con un agente implementado, asegúrate de haber otorgado el rol a la principal del ID de SPIFFE de tu agente (principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID).

Error genérico de implementación

Cuando implementes tu agente con uv run adk deploy, es posible que el comando falle con un mensaje de error genérico.

Este error se produce debido a dependencias de Python faltantes, errores de sintaxis en agent.py o variables de entorno mal configuradas.

Para resolver este error, haz lo siguiente:

  1. Abre la consola de Google Cloud y ve a la página Explorador de registros.
  2. Busca los registros del contenedor de implementación temporal (por ejemplo, maps_mcp_agent_tmp... o bigquery_mcp_agent_tmp...).
  3. Revisa el registro de seguimiento de Python para identificar errores de sintaxis o rastrear paquetes faltantes.
  4. Asegúrate de que todos los paquetes obligatorios aparezcan en tu archivo requirements.txt.

Bucle de autenticación de ServiceNow o permisos inesperados

Cuando un agente se autentica en ServiceNow con OAuth de 3 segmentos, es posible que falle el flujo de autenticación o que el agente entre en un bucle de solicitudes.

Este problema se produce porque ServiceNow determina los permisos otorgados a nivel de la aplicación en lugar de los permisos solicitados por el agente. Si un administrador configura permisos específicos en la aplicación de ServiceNow (por ejemplo, useraccount), ServiceNow devuelve tokens que contienen solo esos permisos configurados, incluso si el agente solicitó permisos diferentes (como mcp_server). Si el agente espera o valida estrictamente los permisos solicitados, rechaza el token recibido y podría volver a solicitar credenciales en un bucle.

Para solucionar este problema, haz lo siguiente:

  1. Accede a tu instancia de ServiceNow como administrador.
  2. Ve a la configuración de la aplicación de OAuth de ServiceNow.
  3. Asegúrate de que todos los alcances que requiere tu agente se agreguen de forma explícita a la lista de alcances permitidos para la aplicación.
  4. Configura tu agente para que solicite solo los permisos habilitados en ServiceNow.

Para obtener más información, consulta Servicios de terceros compatibles.

Error de varios permisos de GitHub o Microsoft

Cuando configuras un proveedor de autenticación para GitHub o Microsoft, la autenticación falla si solicitas varios permisos de OAuth.

El administrador de autorización admite integraciones de un solo alcance para GitHub y Microsoft. El administrador de autorización no admite la solicitud de varios permisos de acceso de forma simultánea.

Para resolver este problema, configura tu agente o proveedor de autenticación para que solicite solo un alcance necesario para la integración.

Para obtener más información, consulta Servicios de terceros compatibles.

Errores de detección de OpenID Connect y del extremo JWKS

Un servicio externo o una entidad que confía puede consultar los extremos del Google CloudServicio de tokens de seguridad de OpenID Connect Discovery (/.well-known/openid-configuration) o del conjunto de claves web JSON (/openid/jwks) para verificar un token de ID de Agent Identity. Cuando consultes estos extremos, es posible que la solicitud falle con un error HTTP 400, 404, 429 o 500.

En la siguiente tabla, se describen las causas y las soluciones para estos errores:

Estado de HTTP Causa Solución
400 Bad Request Este error se produce porque el nombre del recurso del grupo de identidades para cargas de trabajo en la URL de la solicitud no es válido o porque la solicitud incluye un encabezado HTTP Authorization. Para resolver este error, haz lo siguiente:
  • Verifica que el nombre del recurso del grupo de identidades para cargas de trabajo use un formato de dominio de confianza del agente admitido (agents.global.org-ORGANIZATION_ID.system.id.goog o agents.global.proj-PROJECT_NUMBER.system.id.goog).
  • Quita los encabezados Authorization o de OAuth de la solicitud. Los extremos /.well-known/openid-configuration y /openid/jwks son públicos y no están autenticados. Si se pasan encabezados de autenticación, la solicitud falla con un error HTTP 400.
404 Not Found Este error se produce porque no existe el ID de organización, el número de proyecto o el grupo de identidades para cargas de trabajo especificados, o bien la ruta de URL es incorrecta. Para resolver este error, confirma que el ID de organización, el número de proyecto y el dominio de confianza (ID del grupo de identidades para cargas de trabajo) en la URL sean correctos. Verifica también que la ruta de URL termine con /.well-known/openid-configuration o /openid/jwks.
429 Too Many Requests Este error se produce porque tu verificador superó el límite de frecuencia de solicitudes al consultar los extremos de detección o JWKS sin almacenar en caché la respuesta. Para resolver este error, configura tu verificador para que almacene en caché el documento de descubrimiento y el JWKS durante un máximo de 24 horas según el encabezado de respuesta Cache-Control: public, max-age=86400, must-revalidate.
500 Internal Server Error Este error se produce porque el servidor encontró un problema interno temporal mientras recuperaba las claves de firma públicas. Para resolver este error, usa tu JWKS almacenado en caché si está disponible o vuelve a intentar la solicitud con una retirada exponencial.

Falla la verificación de la firma del token después de la rotación de claves

Cuando un servicio externo verifica un token de ID de identidad del agente, es posible que falle la verificación de la firma para los tokens emitidos recientemente, aunque los tokens anteriores del mismo agente se hayan verificado correctamente.

Este problema se produce porque Google Cloud rota periódicamente las claves de firma privadas y públicas para los grupos de identidades de cargas de trabajo. Como resultado, es posible que el kid (ID de clave) del token entrante no se encuentre en la caché de claves local de tu verificador.

Para resolver este problema, configura tu verificador de modo que, cuando reciba un token con un kid no reconocido, recupere un JWKS nuevo del extremo /openid/jwks antes de rechazar el token.

¿Qué sigue?