JSON Web Tokens — a shallow dive

JWT (JSON Web Token) is an open standard that allows us to send information that can be verified by a digital signature over the web. It contains a cryptographically signed JSON object and a payload containing claims; it is typically used in HTTP Authorization headers or URL query parameters.

Who’s JSON ?

JSON stands for JavaScript Object Notation. JSON is just a text-based representation of data using key-value pairs. It is typically used to exchange information between web clients and web servers. It’s the most popular data format for APIs.

Below is an example of what a JSON might look like

{
   {
      name: "John Doe",
      age: 20
   }
}

How JSON Web Tokens work

A simple model of how JWT works

Using JWT, a user can access a service or resource without authenticating every request with their username and password.

The token contains all the necessary client and user information needed for authentication.This means the server does not need to maintain the state of the user.

As seen above, the user attempts to log into twitter with their username and password. If these details are correct, the server sends a JWT token in the HTTP message.

The client now has hold of a JWT token that can be included in the Authorization header each time it makes a request to Twitter. With each request, the server examines the authenticity of the JWT. Assuming the token is valid, the data requested is sent to the client.

When the user loges out, the JWT is removed from the browser.

The structure of a JSON Web Token

A JSON Web Token is made of three main:

A header —this holds metadata on the cryptographic operations used on the payload
A payload (or claim set) — a JSON object containing identification information on a user
A Signature — used to validate the trustworthiness of a token.

Let’s dive in a little deeper.

This is what a JWT token might look like. It contains all three parts (header, payload and signature). However, they are all encoded and separated by a full stop (.):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

The Header

Think of the header as a JSON Object (a container) holding technical information about the token. When base64url-encoded, the header appears to be an unreadeable random sequence of characters. However, when decoded, it provides parameters that hold key infromation on cryptographic operations.

Encoded: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Below is the decoded header:

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

The alg parameter refers to cryptographic algorithm being used and typ refers to the media type of JWT.

The Payload

The payload is also a JSON object. It contains claims — statements about the user asserted by the JWT issuer.

Encoded:eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ

A decoded payload:

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022
}

As seen above, the claim is a key-value pair, where the key is a string and the value can be any JSON value. Above we have integers (1234567890) and strings (John Doe) . Above we have 3 claims: sub, nameand iat. However, there can be many more.

Here are a few standard claims that you would typically see in a payload:

iss (issuer): The issuer of the JWT
sub (subject): Contains technical data on the use
aud (audience): Recipient for which the JWT is intended
exp (expiration time): The expiration time of the JWT
nbf (not before time): Time before which the token should be rejected.
iat (issued at time): Time at which the JWT was issued.
jti (JWT ID): Unique identifier used to ensure a token is not reused.

You can add custom claims to a token. However they must use the namespace required by Auth0.

The Signature

Encoded: SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

The signature is used to ensure that the sender of the JWT is who it says it is, and the token has not been tampered with.

To create the signature, you need:

Base64-encoded header
Base64-encoded payload
A secret

These are then added together and signed with the cryptographic algorithm specified in the alg part if the header.

I hope this was a nice introduction to JWT. See you later!

Steph