Lorsqu'une application cliente inclut un jeton Web JSON (JWT) dans une requête adressée à une API, le proxy Extensible Service Proxy (ESP) valide le jeton avant d'envoyer la requête au backend de l'API. Cette page fournit des informations de dépannage en cas d'échec de validation JWT et si ESP affiche une erreur dans la réponse au client. Pour en savoir plus sur les jetons JWT, consultez la norme RFC 7519.
Erreur : 401: Jwt issuer is not configured
Cela peut se produire lors du déploiement d'ESPv2 dans Cloud Run. L'option --allow-unauthenticated n'est pas utilisée dans la commande gcloud run deploy.
Si l'option n'est pas utilisée, le jeton JWT est intercepté et vérifié par le serveur IAM de contrôle des accès Cloud Run <a=" docs="" managing-access"="" run="" securing="">et non par ESPv2. IAM peut utiliser un émetteur différent de ESPv2.
</a=">
Erreur : BAD_FORMAT
Vérifiez les éléments suivants :
Assurez-vous que le jeton JWT contient un JSON valide.
Vérifiez que le champ "alg" est présent dans l'en-tête du jeton JWT et que sa valeur est "RS256", "HS256", "RS384", "HS384", "RS512" ou "HS512".
Vérifiez le type de données des champs suivants, s'ils sont présents, dans la charge utile JWT :
Les déclarations "iat" (date/heure d'émission), "exp" (date/heure d'expiration) et "nbf" (pas avant le) sont des nombres supérieurs à 0 et non des chaînes.
Les champs "sub" (objet), "iss" (émetteur) et "jti" (ID JWT) sont des chaînes.
La déclaration "aud" (audience) est une chaîne ou un tableau de chaînes.
Assurez-vous que les déclarations suivantes sont présentes dans la charge utile du jeton JWT : "sub" (objet), "iss" (émetteur) et "aud" (audience).
Utilisez jwt.io pour décoder le jeton JWT et assurez-vous que :
la déclaration "exp" (date/heure d'expiration) est présente ;
la valeur de la déclaration "exp" (date/heure d'expiration) correspond à une date et une heure dans le futur ; la date et l'heure actuelles doivent être antérieures à la date et heure d'expiration indiquées dans la déclaration "exp" ;
la déclaration "nbf" (pas avant), si elle est présente, correspond à une date et une heure dans le passé . La date et l'heure actuelles doivent être postérieures ou identiques à la date et heure indiquées dans la déclaration "nbf".
Erreur : UNKNOWN
Utilisez jwt.io pour décoder le jeton JWT et vérifiez ce qui suit :
Si la déclaration "iss" (émetteur) est une adresse e-mail, les déclarations "sub" (objet) et "iss" doivent être identiques.
Cela permet de garantir que le jeton JWT est auto-émis pour les émetteurs via e-mail.
Error: KEY_RETRIEVAL_ERROR
Vérifiez que l'URI de clé publique spécifié dans le champ x-google-jwks_uri du document OpenAPI est correct et valide.
Error: Issuer not allowed
Vérifiez que la revendication "iss" (émetteur) de votre jeton JWT correspond au champ x-google-issuer dans la section securityDefinitions de l'objet de sécurité de votre document OpenAPI.
Dans le document OpenAPI, vérifiez que l'objet "security" est activé pour la méthode d'API appelée.
Consultez l'exemple dans le fichier openapi.yaml pour savoir comment décrire la sécurité au niveau de la méthode en utilisant les objets securityDefinition et security.
Error: Audience not allowed
Comparez la revendication "aud" (audience) dans un jeton JWT pour vérifier si elle correspond au nom du service Endpoints, qui correspond au champ host du document OpenAPI.
Si la revendication "aud" et le nom du service Endpoints sont différents :
vérifiez que la revendication "aud" du jeton JWT correspond à l'une des valeurs x-google-audiences spécifiées dans votre document OpenAPI ;
assurez-vous que x-google-audiences et x-google-issuer se trouvent dans le même objet securityDefinitions de votre document OpenAPI.
Si la revendication "aud" et le nom du service Endpoints sont identiques, ESP valide l'audience et ignore les valeurs x-google-audiences dans votre document OpenAPI. Par exemple, si votre nom de service est "myservice.endpoints.example-project-12345.cloud.goog", un jeton JWT avec "aud" défini sur "myservice.endpoints.example-project-12345.cloud.goog" ou "https://myservice.endpoints.example-project-12345.cloud.goog" est une audience valide.
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/09/04 (UTC).
[[["Facile à comprendre","easyToUnderstand","thumb-up"],["J'ai pu résoudre mon problème","solvedMyProblem","thumb-up"],["Autre","otherUp","thumb-up"]],[["Difficile à comprendre","hardToUnderstand","thumb-down"],["Informations ou exemple de code incorrects","incorrectInformationOrSampleCode","thumb-down"],["Il n'y a pas l'information/les exemples dont j'ai besoin","missingTheInformationSamplesINeed","thumb-down"],["Problème de traduction","translationIssue","thumb-down"],["Autre","otherDown","thumb-down"]],["Dernière mise à jour le 2025/09/04 (UTC)."],[[["\u003cp\u003eThis document provides troubleshooting steps for JSON Web Token (JWT) validation failures encountered when using the Extensible Service Proxy (ESP) with an API.\u003c/p\u003e\n"],["\u003cp\u003eCommon JWT validation errors include \u003ccode\u003eBAD_FORMAT\u003c/code\u003e, \u003ccode\u003eTIME_CONSTRAINT_FAILURE\u003c/code\u003e, \u003ccode\u003eUNKNOWN\u003c/code\u003e, \u003ccode\u003eKEY_RETRIEVAL_ERROR\u003c/code\u003e, \u003ccode\u003eIssuer not allowed\u003c/code\u003e, and \u003ccode\u003eAudience not allowed\u003c/code\u003e, each with specific diagnostic instructions.\u003c/p\u003e\n"],["\u003cp\u003eWhen using Cloud Run, make sure the \u003ccode\u003e--allow-unauthenticated\u003c/code\u003e flag is used to prevent Cloud Run from intercepting and verifying the JWT token.\u003c/p\u003e\n"],["\u003cp\u003eThe document emphasizes checking the JWT's structure, ensuring the presence of required fields like \u003ccode\u003e"iss"\u003c/code\u003e, \u003ccode\u003e"sub"\u003c/code\u003e, and \u003ccode\u003e"aud"\u003c/code\u003e, and using \u003ca href=\"https://jwt.io/\"\u003ejwt.io\u003c/a\u003e to decode and examine the JWT's content.\u003c/p\u003e\n"],["\u003cp\u003eCorrect configuration of the \u003ccode\u003ex-google-jwks_uri\u003c/code\u003e, \u003ccode\u003ex-google-issuer\u003c/code\u003e, and \u003ccode\u003ex-google-audiences\u003c/code\u003e fields in the OpenAPI document is critical for successful JWT validation.\u003c/p\u003e\n"]]],[],null,["# Troubleshooting JWT validation\n\nOpenAPI \\| [gRPC](/endpoints/docs/grpc/troubleshoot-jwt \"View this page for the Cloud Endpoints gRPC docs\")\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 [`x-google-jwks_uri`](/endpoints/docs/openapi/openapi-extensions#x-google-jwks_uri) field in your OpenAPI document is correct and valid.\n\n**Error: `Issuer not allowed`**\n\n- Check that the `\"iss\"` (issuer) claim in your JWT token matches the\n [`x-google-issuer`](/endpoints/docs/openapi/openapi-extensions#x-google-issuer)\n field in the `securityDefinitions` section of the security object in your\n OpenAPI document.\n\n- In your OpenAPI document, check that the security object is\n enabled for the API method invoked.\n\nSee the\n[sample openapi.yaml](https://github.com/GoogleCloudPlatform/python-docs-samples/blob/master/endpoints/getting-started/openapi.yaml)\nfile for an example of how to describe security at the method level by using\n`securityDefinition` and `security` objects.\n\n**Error: `Audience not allowed`**\n\nCompare the `\"aud\"` (audience) claim in a JWT token to see if it matches the\nEndpoints service name, which corresponds to the `host` field in\nthe OpenAPI document.\n\nIf the `\"aud\"` claim and the Endpoints service name are\ndifferent:\n\n- Check that the `\"aud\"` claim in the JWT matches one of the\n `x-google-audiences` values specified in your OpenAPI document.\n\n- Make sure that the `x-google-audiences` and `x-google-issuer` are in the same\n `securityDefinitions` object in your OpenAPI document.\n\nIf the `\"aud\"` claim and the Endpoints service name are the same,\nthe ESP validates the audience and\nignores the\n[`x-google-audiences`](/endpoints/docs/openapi/openapi-extensions#x-google-audiences)\nvalues in your OpenAPI document. For example, if your service name\nis `\"myservice.endpoints.example-project-12345.cloud.goog\"`, then a JWT with\n`\"aud\"` set to `\"myservice.endpoints.example-project-12345.cloud.goog\"` or\n`\"https://myservice.endpoints.example-project-12345.cloud.goog\"` is a valid\naudience."]]