What is the difference between DecodeJWT and VerifyJWT?

[dchiesa1]

Apigee Edge has two similar-sounding policies: DecodeJWT and VerifyJWT.

What's the difference?

If I want to design API Proxies that accept JWT for authentication, how do I choose between them?

When would I want to use one versus the other?

for some prior discussion, see: https://community.apigee.com/answers/58939/view.html

[dchiesa1]

As the documentation states,

• the VerifyJWT policy verifies digitally-signed JWTs and claims within those JWTs.
• the DecodeJWT policy decodes signed JWTs without validating signatures on the token.

Signed JWT are comprised of 3 parts:

• a base64-encoded header
• a base64-encoded payload
• a base64-encoded signature of the concatenation of the prior two elements

Because the header and payload are simply base64 encoded, they can be read without verifying the signature. Just as you could look at a paper document and not check the signature to ensure the document is bona fide , it is possible for any app could likewise examine a JWT without verifying the signature to ensure that the JWT is bona fide. It's usually not a good idea to do either!

But DecodeJWT lets you do that with JWTs. It lets you examine the content, without verifying the signature.

WHY would you ever want to do that?

Here's a good use case:

Suppose your application security protocol calls for the client app to generate a JWT, which embeds a number of claims, one of which is a client_id claim. Then the client app signs the JWT with the HS256 algorithm, using the client secret. Then the client transmits the signed JWT to the server (Apigee Edge).

For Apigee Edge to verify that JWT, it must know the client secret. How does it know which client secret to use? Well, it can extract the client secret from the keystore by looking up the client id. So the Apigee Edge proxy could perform this sequence:

1. DecodeJWT, to extract the client_id claim from the inbound JWT
2. VerifyApiKey, to verify the client_id as an API key, and to retrieve any custom attributes on the app. Also this will implicitly retrieve into memory the client_secret.
3. VerifyJWT, using the retrieved client_secret.

You can imagine a similar flow for an RS256 signed JWT, in which each client has its own keypair, and Apigee Edge stores the public key as a custom attribute on the app. After VerifyApiKey, the public key is available in a context variable, so the VerifyJWT (with RS256) would be able to verify the signed JWT.

In general I think it's a very bad idea to rely on the output of DecodeJWT without following it with a VerifyJWT policy. DecodeJWT will simply extract the content of the JWT, without verifying the signature. A malicious app or actor could construct a fake JWT with arbitrary content; if you rely on that content without checking the signature, you could compromise the integrity of your system.

I hope this clears things up!

Be careful and thoughtful about how you employ the JWT policies in Apigee Edge! There's lots of flexibility, and you need to know what you really want to do.