Whether you’re just beginning to learn about OAuth 2.0 or OpenID Connect, or you’re an experienced developer troubleshooting why an API is not accepting a particular JSON Web Token (JWT), you often want to quickly inspect the contents of tokens to see if they contain the correct claims, are signed correctly, and if they have the expected lifetime.
Since we already have a live demo IdentityServer environment, which you can use to try out different authentication flows, it made sense to add a utility to inspect JWT token contents as well. Visit https://jwt.me to try it out!
Let's have a look at why we built this tool, and what it can help you with.
Why We Created Our Own JWT Decoder Tool
You may already know and use an alternative JWT decoder tool, either online or directly in your IDE, for example using the JWT visualizer in JetBrains Rider. Why did we create our own version then?
When we or our partners deliver training, we demonstrate what’s inside a JWT token using the various tools out there. But we often found them lacking functionality in one way or another, which led to us rolling our own version. This also allows us to add more features as we go!
These are some of the current functionalities included in our JWT decoder tool:
- Automatic retrieval of public key data to validate tokens signed using a JSON Web Key (JWK).
- Inline explanation of well-known claim types.
- Color-matching of header, payload and signature in the JWT token and decoded version.
- Presenter mode, useful when showing decoded tokens during training.
- Skipping invalid encoded JWT content, clearly marking the invalid content after parsing.
Let’s highlight some of these features!
Token Validation
Self-contained tokens should always be signed, preferably using a private/public key pair: a signed token helps to identify whether its contents have been tampered with, and when using a private/public key pair, also verifies that the token was issued by the authority that holds the private key.
When validating a JWT, the public key is used to verify that the header and payload matches the signature value. This public key is often announced using a JWK url, which can be found in the discovery document for authorization servers supporting OpenID Connect:
{
"issuer": "https://demo.duendesoftware.com",
"jwks_uri": "https://demo.duendesoftware.com/.well-known/openid-configuration/jwks",
"authorization_endpoint": "https://demo.duendesoftware.com/connect/authorize",
// ...
}
Our JWT Decoder tool uses this information to automatically find the public JWKs to validate a token when you paste it. You can also pre-enter the URL pointing to your issuer - if it has a discovery document hosted at the .well-known/openid-configuration path -, or provide a URL directly to a JSON Web Key set.
Since we prefer using private/public key pairs for signing tokens, we didn’t add support for validating token signatures using a shared secret. At least not in the initial version of our tool 😉.
Inline Explanation of Well-known Claim Types
We intend to use this JWT Decoder tool when teaching about OAuth 2.0 and OpenID Connect, so we wanted a feature to quickly explain some of the content in the token’s header and payload. Using the toggle switch “Show claim information”, you can enable inline explanation: for each well-known claim type, this adds a brief line of information about the claim’s purpose.
In some cases, it will further explain the value as well:
algwill show which signature algorithm is used.typadds information about the token type, in case it’s a commonly used token type.- The
exp,iatandnbfclaims will have their value expanded to a full date/time value.
Conclusion
If you’ve used our live demo environment before, you can now also use it to inspect your tokens, without them leaving your browser. We encourage you to give our JWT Decoder a go and inspect the source code behind it to learn how it functions.
And if you have ideas for new features for the JWT Decoder tool, then share your thoughts on our Duende Community Discussions!