Troubleshooting JWT validation

When a client application includes a JSON Web Token (JWT) in a request to an API, the Extensible Service Proxy (ESP) validates the JWT before sending the request to the API backend. This page provides troubleshooting information if the JWT validation fails and ESP returns an error in the response to the client. See RFC 7519 for more information about JWTs.

Error: 401: Jwt issuer is not configured

This may happen when deploying ESPv2 in Cloud Run, the flag --allow-unauthenticated is not used in gcloud run deploy command. If the flag is not used, the JWT token is intercepted and verified by Cloud Run access control IAM server and not by ESPv2. IAM may use a different issuer than ESPv2.

Error: BAD_FORMAT

Check the following:

  • Make sure the JWT contains valid JSON.
  • Check that the JWT header has the "alg" field and is set to one of the following: "RS256", "HS256", "RS384", "HS384", "RS512", or "HS512"
  • Check the data type of the following fields (if they are present) in the JWT payload:
    • The "iat" (issued at), "exp" (expiration time), and "nbf"(not before) claims are numbers greater than 0 and not strings.
    • The "sub" (subject), "iss" (issuer), and "jti" (JWT ID) fields are strings.
    • The "aud" (audience) claim is either a string or an array of strings.
  • Ensure that the following claims are present in the JWT payload: "sub" (subject), "iss" (issuer), and "aud" (audience).

The following is an example of a decoded JWT token that is valid:

{
  "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

Use jwt.io to decode the JWT and make sure that:

  • The "exp" (expiration time) claim exists.
  • 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.
  • 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.
Error: UNKNOWN

Use jwt.io to decode the JWT and ensure that:

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

Error: KEY_RETRIEVAL_ERROR

  • Check that the public key URI specified in the jwksUri in the ApiIssuer annotation is correct and valid.

Error: Issuer not allowed

  • Check that the "iss" (issuer) claim in your JWT token matches the issuer value in the ApiIssuer annotation.

Error: Audience not allowed

If the "aud" (audience) claim in a JWT token matches the Endpoints service name, then Cloud Endpoints Frameworks validates the audience and ignores the values set in the audiences element in the ApiIssuerAudience annotation. For example, if your service name is "myservice.appspot.com", then a JWT with "aud" set to "myservice.appspot.com" or "https://myservice.appspot.com" is a valid audience.

If the "aud" claim isn't the same as the Endpoints service name:

  • Check that the "aud" claim in the JWT matches one of the values in the audiences element in the ApiIssuerAudience annotation.