Decode JWT runtime error troubleshooting

You're viewing Apigee and Apigee hybrid documentation.
View Apigee Edge documentation.

FailedToDecode

Error code

steps.jwt.FailedToDecode

Error response body

{
  "fault": {
    "faultstring": "Failed to Decode Token: policy({0})",
    "detail": {
       "errorcode": "steps.jwt.FailedToDecode"
     }
  }
}

Cause

This error occurs if the JSON Web Token (JWT) specified in the <Source> element of the Decode JWT policy is malformed, invalid or otherwise not decodable.

A properly structured JWT should contain a header, payload and signature in the following format: header.payload.signature. If the JWT passed to the DecodeJWT policy is missing a component part, then you will get the error. For example, if the JWT has only payload.signature, but is missing its header, the error will occur.

Diagnosis

Identify the variable specified in the <Source> element of the Decode JWT policy. This variable should contain the JWT.

Here's a sample Decode JWT policy:
```
<DecodeJWT name="JWT-Decode-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Source>request.header.authorization</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</DecodeJWT>
```
In the above example, the JWT should be contained in the Authorization request header.
Examine the variable identified in Step 1 and check to see if the JWT it contains is valid. If the input JWT is not valid, then that's the cause for the error.

In the example API request below, the input JWT is passed in the Authorization request header:
```
curl -v "http://$EXTERNAL_IP/v1/decodeJWT" -H "Authorization: Bearer eyJ1c2VySWQiOiJiMDhmODZhZi0zNWRhLTQ4ZjItOGZhYi1jZWYzOTA0NjYwYmQifQ.-xN_h82PHVTCMA9vdoHrcZxH-x5mb11y1537t3rGzcM"
```
Where $EXTERNAL_IP is the IP address of the external load balancer. This IP address is exposed to the internet. For more information, see Customize access routing.

Close examination of the JWT shows that it has the format payload.signature which is invalid. The expected format of the JWT is header.payload.signature. As a result, the Decode JWT policy fails with the error :
```
"faultstring": "Failed to Decode Token: policy({0})"
```

Resolution

Ensure that the JWT passed to the Decode JWT policy contains all three elements, is correctly formatted and is decodable.

To correct the example shown above, you can pass in a valid JWT with the format header.payload.signature. This can be done by making the API call using the cURL command as follows:

curl -v "http://$EXTERNAL_IP/v1/decodeJWT" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiJiMDhmODZhZi0zNWRhLTQ4ZjItOGZhYi1jZWYzOTA0NjYwYmQifQ.-xN_h82PHVTCMA9vdoHrcZxH-x5mb11y1537t3rGzcM"

Where $EXTERNAL_IP is the IP address of the external load balancer. This IP address is exposed to the internet. For more information, see Customize access routing.

InvalidToken

Error code

steps.jwt.InvalidToken

Error response body

{
  "fault": {
    "faultstring": "Invalid token: policy({0})",
    "detail": {
      "errorcode": "steps.jwt.InvalidToken"
     }
  }
}

Cause

This error occurs if the flow variable specified in the <Source> element of the Decode JWT policy is:

out of scope (not available in the specific flow where the policy is being executed) or
can't be resolved (is not defined)

Diagnosis

Identify the variable specified in the <Source> element of the Decode JWT policy. This variable should contain the JWT.

Here's a sample Decode JWT policy:
```
<DecodeJWT name="JWT-Decode-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Source>request.header.authorization</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</DecodeJWT>
```
In the example above, the Authorization request header should contain the JWT.
Determine if the variable identified in Step 1 is defined and available in the flow in which the Decode JWT policy is executed.
If the variable is either:
- out of scope (not available in the specific flow where the policy is being executed) or
- can't be resolved (is not defined)
then that's the cause for the error.

In the example API request below, the JWT is not passed in the authorization request header by the user.
```
curl -v "http://$EXTERNAL_IP/v1/decodeJWT"
```

Where $EXTERNAL_IP is the IP address of the external load balancer. This IP address is exposed to the internet. For more information, see Customize access routing.

Because the authorization request header is not passed, the Decode JWT policy fails with the error:

```
"faultstring": "Invalid token: policy({0})"
```

Resolution

Ensure that the variable referenced in the <Source> element of the Decode JWT policy is defined, contains a valid (decodable) JWT and is available in the specific flow where the Decode JWT policy is being executed.

To correct the example shown above, you can pass a valid JWT in the request authorization header. This can be done by making the API call using the cURL command as follows:

curl -v "http://$EXTERNAL_IP/v1/decodeJWT" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiJiMDhmODZhZi0zNWRhLTQ4ZjItOGZhYi1jZWYzOTA0NjYwYmQifQ.-xN_h82PHVTCMA9vdoHrcZxH-x5mb11y1537t3rGzcM"

Where $EXTERNAL_IP is the IP address of the external load balancer. This IP address is exposed to the internet. For more information, see Customize access routing.