Résoudre des problèmes de validation de jetons JWT

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

Error: BAD_FORMAT

Vérifiez les éléments suivants :

  • Assurez-vous que le jeton JWT contient un JSON valide.
  • Vérifiez que l'en-tête JWT contient le champ "alg" et est défini sur l'un des éléments suivants : "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 revendications "iat" (émises à), "exp" (délai d'expiration) et "nbf"(non antérieures) 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 revendication "aud" (audience) est une chaîne ou un tableau de chaînes.
  • Assurez-vous que les revendications suivantes sont présentes dans la charge utile JWT : "sub" (objet), "iss" (émetteur) et "aud" (audience).

Voici un exemple de jeton JWT décodé valide :

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "42ba1e234ac91ffca687a5b5b3d0ca2d7ce0fc0a"
    }

    Payload:
    {
      "iss": "myservice@myproject.iam.gserviceaccount.com",
      "iat": 1493833746,
      "aud": "myservice.appspot.com",
      "exp": 1493837346,
      "sub": "myservice@myproject.iam.gserviceaccount.com"
    }
    
Error: TIME_CONSTRAINT_FAILURE

Utilisez jwt.io pour décoder le jeton JWT et assurez-vous que :

  • La revendication "exp" (délai d'expiration) existe.
  • La valeur de la revendication "exp" (délai d'expiration) est une date et une heure situées dans le futur. La date et l'heure actuelles doivent être antérieures à la date et à l'heure d'expiration indiquées dans la revendication "exp".
  • La revendication "nbf" (non antérieures) (si elle est présente) est une date et une heure passées. La date et l'heure actuelles doivent être postérieures ou égales à la date et l'heure indiquées dans la revendication "nbf".
Error: UNKNOWN

Utilisez jwt.io pour décoder le jeton JWT et vérifiez ce qui suit :

  • Si la revendication "iss" (émetteur) est une adresse e-mail, les revendications "sub" (objet) et "iss" doivent alors ê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 de votre 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 voir 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, l'ESP valide l'audience et ignore les valeurs x-google-audiences dans votre document OpenAPI. Par exemple, si le nom de votre 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.