JWT - Introduction

JWT - JSON Web Tokens

Next →

In this tutorial series we will learn about JWT or JSON Web Tokens.

What is JWT?

JWT or JSON Web Token is an open standard that defines a compact and self-contained way of authenticating and transmitting data between parties as JSON object.

JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.

Courtesy: https://jwt.io

Important features of JWT

It is compact and self-contained.

Compact means it has a smaller size and can easily be sent through URL, POST request or even in the HTTP header.

Self-contained means its payload contains all the information about the user hence we don't have to query the database more than once.

When to use JWT?

Two common use cases of JWT are authentication and information exchange.

Use of JWT in authentication

This is a very common use case. When a user successfully logs in the server will issue a JWT. So, every subsequent request to the server will use the JWT to validate the user who wants to access the resources.

Structure of JWT

JWT consists of three parts separated by . dots.

HEADER.PAYLOAD.SIGNATURE

So, JWT will look like the following.

aaaaa.bbbbb.ccccc

Header

This consists of the type of the token and the hashing algorithm being used.

Example of header:

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

Where, typ is the type and is set to JWT for JSON Web Tokens.

alg represents the hashing algorithm being used and in this case it is HMAC SHA256.

The header JSON is then Base64Url encoded to form the first part of the JWT.

Payload

This is the second part of the token and contains the claim.

Claims are the statements about an entity, usually the user and some additional metadata.

Claims are of three types: Registered, Public and Private.

Registered claims: These are a list of predefined claims which are optional but recommended to provide additional information.

Like exp tells about the expiration time.

Public claims: This is defined at will.

Private claims: These are custom claims for sharing informatin between parties.

Example of payload:

{
  "uid": "u1",
  "iat": 1523688829,
  "exp": 1523688889
}

uid in this case is user id.

iat stands for issued at (seconds from Unix epoch).

exp in this case is the expiry time (seconds from Unix epoch).

The payload JSON is then Base64Url encoded to form the second part of the JWT.

DO NOT put secret/confidential information in the header or payload of JWT as it can be easily retrieved and read.

If you are planning to put secret data then do encrypt it.

Signature

To create the signature we use the hashing algorithm and hash the encoded header, encoded payload and a secret.

So, if we are using HMAC SHA256 hashing algorithm then we can represent the signature as follows.

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

The signature is used to verify that the message was not tampered.

Generating JWT

In the following example we are going to generate JWT for the given details.

Header

We have the following header for the JWT.

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

So, we will get the following for the Base64Url encoded header.

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9

Payload

We have the following payload for the JWT.

{
  "uid": "u1",
  "iat": 1523688829,
  "exp": 1523688889
}

So, we will get the following for the Base64Url encoded payload.

eyJ1aWQiOiJ1MSIsImlhdCI6MTUyMzY4ODgyOSwiZXhwIjoxNTIzNjg4ODg5fQ

Signature

For the signature we are using the following.

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

Where, helloworld is the secret.

So, we will get the following encoded signature.

tx_uDtlb1creKgJv3Y6fpxaziOvq5mxHgYnE0_UmfJ8

Generated JWT

Combining the three we will get the following JWT for the given header, payload and secret.

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1aWQiOiJ1MSIsImlhdCI6MTUyMzY4ODgyOSwiZXhwIjoxNTIzNjg4ODg5fQ.tx_uDtlb1creKgJv3Y6fpxaziOvq5mxHgYnE0_UmfJ8
Next →