Troubleshooting JWT Validation

When a client application includes a JSON Web Token (JWT) in a request to an API, Cloud Endpoints validates the JWT before sending the request to the API backend. This page provides troubleshooting information if the JWT validation fails and an error is returned in the response to the client. See RFC7519 for more information about JWTs.

Error: BAD_FORMAT

Use jwt.io to decode the JWT and check the following:

  • Make sure the JWT token is well-formed 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 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/time in the future. The current date/time must be before the expiration date/time listed in the "exp" claim.
  • The "nbf" (not before) claim (If present) is a date/time in the past. The current date/time must be after or equal to the date/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: GRPC_JWT_VERIFIER_KEY_RETRIEVAL_ERROR

  • Check that the public key URI specified in the x-google-jwks_uri field in your OpenAPI configuration file is correct and valid.

Error: Issuer not allowed

  • Check that the "iss" (issuer) claim in your JWT token matches the x-google-issuer field in the securityDefinitions section of the security object in your OpenAPI configuration file.

  • In your OpenAPI configuration file, check that the security object is enabled for the API method invoked.

See the sample openapi.yaml file for an example of how to describe security at the method level using securityDefinition and security objects.

Error: Audience not allowed

If the "aud" (audience) claim in a JWT token matches the Cloud Endpoints service name, then the Extensible Service Proxy validates the audience and ignores the x-google-audiences values in your OpenAPI configuration file. For example, if your service name (which corresponds to the host field in the OpenAPI configuration) is "myservice.endpoints.example-project.cloud.goog", then a JWT with "aud" set to "myservice.endpoints.example-project.cloud.goog" or "https://myservice.endpoints.example-project.cloud.goog" is a valid audience.

If the "aud" claim is not the same as the Cloud Endpoints service name:

  • Check that the "aud" claim in the JWT matches one of the x-google-audiences values specified in your OpenAPI configuration.

  • Make sure that the x-google-audiences and x-google-issuer are in the same securityDefinitions object in your OpenAPI configuration.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Endpoints with OpenAPI