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.
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" }
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.
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
x-google-jwks_uri
field in your OpenAPI document is correct and valid.
Error: Issuer not allowed
Check that the
"iss"
(issuer) claim in your JWT token matches thex-google-issuer
field in thesecurityDefinitions
section of the security object in your OpenAPI document.In your OpenAPI document, 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 by using
securityDefinition
and security
objects.
Error: Audience not allowed
Compare the "aud"
(audience) claim in a JWT token to see if it matches the
Endpoints service name, which corresponds to the host
field in
the OpenAPI document.
If the "aud"
claim and the Endpoints service name are
different:
Check that the
"aud"
claim in the JWT matches one of thex-google-audiences
values specified in your OpenAPI document.Make sure that the
x-google-audiences
andx-google-issuer
are in the samesecurityDefinitions
object in your OpenAPI document.
If the "aud"
claim and the Endpoints service name are the same,
the ESP validates the audience and
ignores the
x-google-audiences
values in your OpenAPI document. For example, if your service name
is "myservice.endpoints.example-project-12345.cloud.goog"
, then a JWT with
"aud"
set to "myservice.endpoints.example-project-12345.cloud.goog"
or
"https://myservice.endpoints.example-project-12345.cloud.goog"
is a valid
audience.