Introducing JWT Debugger App

Abhishek Tiwari — Fri, 29 May 2020 16:58:12 +0000

JSON Web Token is a compact yet URL-safe token primarily used for OAuth 2 and OpenID based authentication and authorization. A JWT token represents a set of claims as a JSON object that is encoded in a JSON Web Signature (JWS) structure.

JWT Token

A JWT token is made of three URL-safe portions header, payload, and signature separated by period ('.') characters. Each component contains a base64url-encoded value. For instance, the following string represents a JWT token

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1czNvcmphczc5bDAzOHBrMWJwNmoxZCIsIm5hbWUiOiJKb2huIERvZSIsImp0aSI6Ijc4ZjRnMWpkam5naTBpMzJveGtuZCIsImV4cCI6MTU5MDc2OTE1OH0.rP0Ykkr1jjzErb14OAeNTlCSSGpuKQaxRa2hO3-2Olc

Decoding a token

When you decode a JWT token you get a JSON header and JSON payload. The overall token decoding process is really straightforward. You take the first portion, Base64url decode it and remove any line breaks, whitespace, or other additional characters which gives you header. You take the second portion and Base64url decode it and remove any line breaks, whitespace, or other additional characters which gives you payload.

// Token Header decoded from eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
{
 "alg": "HS256",
 "typ": "JWT"
}
// Token Payload decoded from eyJzdWIiOiJ1czNvcmphczc5bDAzOHBrMWJwNmoxZCIsIm5hbWUiOiJKb2huIERvZSIsImp0aSI6Ijc4ZjRnMWpkam5naTBpMzJveGtuZCIsImV4cCI6MTU5MDc2OTE1OH0
{
  "sub":"us3orjas79l038pk1bp6j1d",
  "name":"John Doe",
  "jti":"78f4g1jdjngi0i32oxknd",
  "exp":1590769158
}

Token validation

Validation of the token requires signing key or secrete used to create the signature portion of the token. Signing algorithm is described by alg claim the token header.

If the signing algorithm belongs the family of asymmetrical algorithms i.e. Rivest–Shamir–Adleman (RSA) or Elliptic Curve Digital Signature Algorithm (ECDSA) then you will need the public version of the private key used for token signing. The public key can be in JSON Web Key (JWK) format or PEM format. If you are using an OpenID Connect compliant authorizations server then the public side of JWK keys are served by a JSON Web Key Set (JWKS) endpoint. A JWKS endpoint returns a set of keys which contains the one or more public keys.
If the signing algorithm belongs to the family of symmetrical algorithms HMAC (sometimes expanded as either keyed-hash message authentication code or hash-based message authentication code) you will need the shared key or secret used to sign the token.

Here is an example of JWKS endpoint of Google OAuth 2 server. JWKS endpoint may return more than one public key so you identify relevant key matching the kid parameter of token header and JWK key.

{
{
   "keys":[
      {
         "e":"AQAB",
         "alg":"RS256",
         "use":"sig",
         "n":"qx9oubekMS3x-mmgPJOUeoPJH9aoYwlDfElkRk2XfQnRmsfbxVc8Gna6V8avfWpBcXuyTMkJ4_hmk4Ra3x4KMwpQ3XVZGtFvP2PwTHKbtf47if-gVsh5PZlHovKOS1ixTnagfidzBGpnwAGGSyrIDSVOxPC6GcOIxWtJ56AZ6kcHtI9zGO4AE8T8-TXEgIkUfby-AQCFxzlXDsA_zxWbjka0gscAqiYESB5JLjMrxNWwEPhlvIRO7LospdwYTjZteLAAC5OEWPMlxI6laSB9TzPWLHMsNNEe6_YOylp2sMSwslOb9FFsP5KVaVdBBLwHwFf7ncVaHExFqhwTHIoS8Q",
         "kty":"RSA",
         "kid":"960a7e8e8341ed752f12b186fa129731fe0b04c0"
      },
      {
         "n":"zK8PHf_6V3G5rU-viUOL1HvAYn7q--dxMoUkt7x1rSWX6fimla-lpoYAKhFTLUELkRKy_6UDzfybz0P9eItqS2UxVWYpKYmKTQ08HgUBUde4GtO_B0SkSk8iLtGh653UBBjgXmfzdfQEz_DsaWn7BMtuAhY9hpMtJye8LQlwaS8ibQrsC0j0GZM5KXRITHwfx06_T1qqC_MOZRA6iJs-J2HNlgeyFuoQVBTY6pRqGXa-qaVsSG3iU-vqNIciFquIq-xydwxLqZNksRRer5VAsSHf0eD3g2DX-cf6paSy1aM40svO9EfSvG_07MuHafEE44RFvSZZ4ubEN9U7ALSjdw",
         "kty":"RSA",
         "kid":"fb8ca5b7d8d9a5c6c6788071e866c6c40f3fc1f9",
         "e":"AQAB",
         "alg":"RS256",
         "use":"sig"
      }
   ]
}

Finally, the use of JWKS endpoint for token validation is recommended as it is safe and does not require sharing of the secret key between parties.

Use a JWT Debugger

If you are a developer working with JWT tokens then most likely you use a debugger tool to decode and validate your token. JWT.io is probably one of the most popular out there. JWT.io is an amazing tool but if you are working with sensitive tokens probably you want to avoid pasting them online which is why we created a cross-platform interactive JWT Debugger App.

With JWT Debugger App, use the web version as a progressive web app or install desktop apps for Mac, Window, and Linux. More importantly, [JWT Debugger App] supports token validation using both JWKS Endpoint and PEM/Secret Keys. JWT.io and many other JWT tools currently don't support JWKS Endpoint based token validation.

JWT Debugger App itself is open-source and if you find any issues or like to add a feature just open a Github ticket and we will love to help.

DEV Community: Axioms

Introducing JWT Debugger App

JWT Token

Decoding a token

Token validation

Use a JWT Debugger