JWT Introduction

JSON Web Tokens

JWT are encoded and digitally signed way of passing claims between two parties. Based on an open standard (RFC 7519) specification. Remember JWTs are encoded and signed not encrypted.

There are many learning resources available online to learn JWT. So I thought of creating a article with basic details and currated links to articles to learn more about JSON Web Tokens (JWT).

State based vs Stateless

When we building apps before Mobile era and SPA trend, We used ‘sessions’ to manage the authentication. Which was a state based authentication mechanism. If explained in simple terms server keeps a record of the logged users. When user logged in it will create a record and map user to that record and also support session based variables which made it stateful. To achieve this applications used cookies to store the session id of created record to to handle the state. So we call this cookie-based authentication.

In JWT on other hand doesn’t have server side records created. Which means stateless. When user logged in token created with some user information to identify the user and send it the authenticated party. Then it uses this token embedded in request header every time when it interact with the server. Server will verify the token and gives access to the requested resources. These features makes easy to implement authentication with modern mobile apps and Single Page Applications (SPA).

For further reading, visit Cookies vs Token Definitive Guide

JSON Web Tokens

JSON web tokens are compact but self-contained encoded JSON objects. Since It is compact It easy to embed in header of requests and since it contain user information server doesn’t need to run additional query to get user information.

So How JSON web token looks like?

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

What is this?

Okay, Let’ simplify this

JSON Web Token’s structure is

header.payload.signature

If you looks close on my above example you can find that whole string is divided in to 3 parts from .

Header

The first part is called Header which includes the algorithm used to hash, such as HMAC SHA256 or RSA and type of the token.

{
  "alg": "HS256",
  "typ": "JWT"
}

Encoding the above string using base64Url you get header part of JWT.

Payload

The middle part of JWT called payload, which includes claims. Claims includes metadata and information about the entity like user.

There is three types of claims.

• Reserved claims: Some JSON object keys are reserved they are not mandatory but useful with authentication.Some notable reserved claims are listed below.
  • iat: issued at, time of JWT created.
  • ext: expires at, time of JWT expiration. This makes JWT to be use only for curtain amount of time.
  • iss: issued by, who issued the token.

For more reading of all available reserved claims, visit JWT reserved claims

• Public claims: these claims need to be either defined in the IANA JSON Web Token Claims registry or or be defined as an URI that contains a collision resistant namespace.

For more reading of all available public claims, visit JWT public claims

• Private claims: These are custom key values pairs which are not reserved or public claims, defined to share information between parties who agreed to use the token.

If we decode the second part of my example JWT token it looks like this.

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true
}

This part too is encoded with base64Url encoding.

Signature

Last part is called signature. This part is created digitally signing the encoded header and encoded payload with secret key using the defined algorithm.

For example if you are using HMACSHA256 algorithm the signature is created like the following way.

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret)

How to use JWT tokens

Normally we store JWT in localstorage and embed it in authorization as bearer token

Authorization: Bearer <JWT>

Tips:

• Keep your token small: Avoid putting unnecessary information to payload. If you payload is big so your token. Which will embedded in each and every request you sent to server. Which makes your request to get heavy.
• Don’t put sensitive information on token: Tokens are encoded not encrypted avoid adding passwords or other sensitive information to payload.
• Keep short expiration time: Unlike session based authentication you can not end the delete session data from server and stop user from accessing the resources. So try to keep your token expireation time minimum and use an refresh mechanism to extend the token time when it get expired.

Tools:

• JWT.io : You can decode JWT tokens using this online tool. It also has chrome extension too.

I got most of these information for the article from jwt.io, they also have JWT guide e-book too.

I’m planning on writing an article on invalidating tokens in future. Please comment your preferred JWT articles and I will update this article with them too.

Awesome JWT

I have created an awesome list for JSON Web tokens: Awesome-JWT. Please don’t forget to contribute there.

---

Disclaimer: I’m an Auth0 ambassador but it’s not a paid position. My articles are based on my own personal views and doesn’t represent any companies I associated with.