Cuando una aplicación cliente incluye un token web JSON (JWT) en una solicitud a una API, el proxy de servicio extensible (ESP) valida el JWT antes de enviar la solicitud al backend de la API. En esta página, se proporciona información para la solución de problemas si falla la validación de JWT y el ESP muestra un error en la respuesta al cliente. Consulta RFC 7519 para obtener más información sobre los JWT.
Error: 401: Jwt issuer is not configured
Esto puede ocurrir cuando, durante la implementación del ESPv2 en Cloud Run, la marca --allow-unauthenticated no se usa en el comando gcloud run deploy.
Si no se usa la marca, el token JWT se intercepta y verifica mediante el servidor de IAM de <a=" docs="" managing-access"="" run="" securing="">control de acceso de Cloud Run, y no mediante el ESPv2. IAM puede un emisor diferente del ESPv2.
</a=">
Error: BAD_FORMAT
Verifica lo siguiente:
Asegúrate de que el JWT contenga un JSON válido.
Comprueba que el encabezado JWT tenga el campo "alg" y que se configure como una de las siguientes opciones: "RS256", "HS256", "RS384", "HS384", "RS512" o "HS512"
Comprueba el tipo de datos en los siguientes campos (si están presentes) de la carga útil del JWT:
Las reclamaciones "iat" (emitido en), "exp" (tiempo de vencimiento) y "nbf" (no antes) son números mayores que 0 y no son strings.
Los campos "sub" (sujeto), "iss" (emisor) y "jti" (ID de JWT) son strings.
La reclamación "aud" (público) es una string o un arreglo de strings.
Asegúrate de que las siguientes reclamaciones estén presentes en la carga útil del JWT: "sub" (asunto), "iss" (emisor) y "aud" (público).
El siguiente fragmento es un ejemplo de un token JWT decodificado que es válido:
Utiliza jwt.io para decodificar el JWT y asegurarte de que:
La reclamación "exp" (tiempo de vencimiento) existe.
El valor de la reclamación "exp" (tiempo de vencimiento) es una fecha y hora en el futuro. La fecha y la hora actuales deben ser anteriores a la fecha y hora de vencimiento indicadas en la reclamación "exp".
La reclamación "nbf" (no antes), si está presente, es una fecha y hora en el pasado. La fecha y hora actuales deben ser posteriores o iguales a la fecha y hora enumeradas en la reclamación "nbf".
Error: UNKNOWN
Utiliza jwt.io para decodificar el JWT y garantizar que:
Si la reclamación "iss" (emisor) es una dirección de correo electrónico, entonces las reclamaciones "sub" (asunto) y "iss" deben ser las mismas.
Esto es para garantizar que el JWT se emita de forma automática a los emisores con correo electrónico.
Error: KEY_RETRIEVAL_ERROR
Verifica que el URI de clave pública especificado en el campo jwks_uri de la sección authentication: providers del archivo de configuración .yaml de gRPC sea correcto y válido.
Error: Issuer not allowed
Verifica que la reclamación "iss" (emisor) en tu token de JWT coincida con el campo issuer en la sección authentication: providers del archivo de configuración .yaml de gRPC.
Error: Audience not allowed
Si la reclamación "aud" (audiencia) en un token de JWT coincide con el nombre del servicio de Endpoints, el ESP valida al público, no sin ignorar los valores audiences en el archivo de configuración .yaml de gRPC. Por ejemplo, si el nombre del servicio es "myservice.endpoints.example-project-12345.cloud.goog", un JWT con "aud" configurado como "myservice.endpoints.example-project-12345.cloud.goog" o "https://myservice.endpoints.example-project-12345.cloud.goog" es un público válido.
Si la reclamación "aud" no es la misma que el nombre del servicio de Endpoints, haz lo siguiente:
Verifica que la reclamación "aud" en el JWT coincida con uno de los valores audiences especificados en la sección authentication: providers del archivo de configuración .yaml de gRPC.
[[["Fácil de comprender","easyToUnderstand","thumb-up"],["Resolvió mi problema","solvedMyProblem","thumb-up"],["Otro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Información o código de muestra incorrectos","incorrectInformationOrSampleCode","thumb-down"],["Faltan la información o los ejemplos que necesito","missingTheInformationSamplesINeed","thumb-down"],["Problema de traducción","translationIssue","thumb-down"],["Otro","otherDown","thumb-down"]],["Última actualización: 2025-09-04 (UTC)"],[[["\u003cp\u003eThe Extensible Service Proxy (ESP) validates JSON Web Tokens (JWTs) before forwarding requests to the API backend, and this page offers troubleshooting for JWT validation failures.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eBAD_FORMAT\u003c/code\u003e error indicates potential issues with the JWT's structure, such as invalid JSON, incorrect \u003ccode\u003e"alg"\u003c/code\u003e field values, or incorrect data types for fields like \u003ccode\u003e"iat"\u003c/code\u003e, \u003ccode\u003e"exp"\u003c/code\u003e, \u003ccode\u003e"nbf"\u003c/code\u003e, \u003ccode\u003e"sub"\u003c/code\u003e, \u003ccode\u003e"iss"\u003c/code\u003e, \u003ccode\u003e"jti"\u003c/code\u003e, and \u003ccode\u003e"aud"\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eTIME_CONSTRAINT_FAILURE\u003c/code\u003e error means that either the \u003ccode\u003e"exp"\u003c/code\u003e (expiration time) claim is missing or invalid, or the \u003ccode\u003e"nbf"\u003c/code\u003e (not before) claim, if present, indicates that the token is not yet valid.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eKEY_RETRIEVAL_ERROR\u003c/code\u003e error suggests a problem with the \u003ccode\u003ejwks_uri\u003c/code\u003e specified in the gRPC configuration, which should be checked for accuracy.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eAudience not allowed\u003c/code\u003e error occurs when the \u003ccode\u003e"aud"\u003c/code\u003e claim in the JWT does not match either the Endpoints service name or the \u003ccode\u003eaudiences\u003c/code\u003e values specified in the gRPC configuration.\u003c/p\u003e\n"]]],[],null,["# Troubleshooting JWT validation\n\n[OpenAPI](/endpoints/docs/openapi/troubleshoot-jwt \"View this page for the Cloud Endpoints OpenAPI docs\") \\| gRPC\n\n\u003cbr /\u003e\n\nWhen a client application includes a JSON Web Token (JWT) in a request to an\nAPI, the [Extensible Service Proxy (ESP)](/endpoints/docs/openapi/glossary#extensible_service_proxy)\nvalidates the JWT before sending the request to the API\nbackend. This page provides troubleshooting information if the JWT validation\nfails and ESP returns an error in the response to the client. See\n[RFC 7519](https://tools.ietf.org/html/rfc7519) for more information\nabout JWTs.\n**Error: `401: Jwt issuer is not configured`**\n\nThis may happen when deploying ESPv2 in Cloud Run, the flag\n`--allow-unauthenticated` is not used in `gcloud run deploy` command.\nIf the flag is not used, the JWT token is intercepted\nand verified by Cloud Run access control IAM server and not by ESPv2. IAM may use a different issuer than ESPv2.\n**Error: `BAD_FORMAT`**\n\nCheck the\nfollowing:\n\n- Make sure the JWT contains valid JSON.\n- Check that the JWT header has the `\"alg\"` field and is set to one of the following: `\"RS256\"`, `\"HS256\"`, `\"RS384\"`, `\"HS384\"`, `\"RS512\"`, or `\"HS512\"`\n- Check the data type of the following fields (if they are present) in the JWT payload:\n - The `\"iat\"` (issued at), `\"exp\"` (expiration time), and `\"nbf\"`(not before) claims are numbers greater than 0 and not strings.\n - The `\"sub\"` (subject), `\"iss\"` (issuer), and `\"jti\"` (JWT ID) fields are strings.\n - The `\"aud\"` (audience) claim is either a string or an array of strings.\n- Ensure that the following claims are present in the JWT payload: `\"sub\"` (subject), `\"iss\"` (issuer), and `\"aud\"` (audience).\n\nThe following is an example of a decoded JWT token that is valid: \n\n```\n{\n \"alg\": \"RS256\",\n \"typ\": \"JWT\",\n \"kid\": \"42ba1e234ac91ffca687a5b5b3d0ca2d7ce0fc0a\"\n}\n\nPayload:\n{\n \"iss\": \"myservice@myproject.iam.gserviceaccount.com\",\n \"iat\": 1493833746,\n \"aud\": \"myservice.appspot.com\",\n \"exp\": 1493837346,\n \"sub\": \"myservice@myproject.iam.gserviceaccount.com\"\n}\n```\n**Error: `TIME_CONSTRAINT_FAILURE`**\n\nUse [jwt.io](https://jwt.io/) to decode the JWT and make sure that:\n\n- The `\"exp\"` (expiration time) claim exists.\n- The `\"exp\"` (expiration time) claim value is a date and time in the future. The current date and time must be before the expiration date and time listed in the `\"exp\"` claim.\n- The `\"nbf\"` (not before) claim (If present) is a date and time in the past. The current date and time must be after or equal to the date and time listed in the `\"nbf\"` claim.\n\n**Error: `UNKNOWN`**\n\nUse [jwt.io](https://jwt.io/) to decode the JWT and ensure that:\n\n- If the `\"iss\"` (issuer) claim is an email address, then the `\"sub\"` (subject) and `\"iss\"` claims should be the same. This is to ensure that for e-mail issuers, the JWT is self issued.\n\n**Error: `KEY_RETRIEVAL_ERROR`**\n\n- Check that the public key URI specified in the [`jwks_uri`](/endpoints/docs/grpc/service-account-authentication#set_up_authentication_in_the_grpc_api_configuration) field in the `authentication: providers` section of your gRPC `.yaml` configuration file is correct and valid.\n\n**Error: `Issuer not allowed`**\n\n- Check that the `\"iss\"` (issuer) claim in your JWT token matches the [`issuer`](/endpoints/docs/grpc/service-account-authentication#set_up_authentication_in_the_grpc_api_configuration) field in the `authentication: providers` section of your gRPC `.yaml` configuration file.\n\n**Error: `Audience not allowed`**\n\nIf the `\"aud\"` (audience) claim in a JWT token matches the Endpoints\nservice name, then the ESP validates the audience\nand ignores the `audiences` values in your gRPC `.yaml` configuration file. For\nexample, if your service name is\n`\"myservice.endpoints.example-project-12345.cloud.goog\"`,\nthen a JWT with `\"aud\"` set to\n`\"myservice.endpoints.example-project-12345.cloud.goog\"`\nor `\"https://myservice.endpoints.example-project-12345.cloud.goog\"` is a valid\naudience.\n\nIf the `\"aud\"` claim isn't the same as the Endpoints service\nname:\n\n- Check that the `\"aud\"` claim in the JWT matches one of the `audiences` values specified in the `authentication: providers` section of your gRPC `.yaml` configuration file."]]