An introduction to JSON Web Tokens (JWT)

What are they?

JSON Web Token (JWT) is a standard for representing claims securely between two parties. A claim is a name value pair which represents information about the subject, that the server/service hold to be true. A JWT is a string representing a set of claims as a JSON object that is encoded in a JWS (JSON Web Signature) or JWE (JSON Web Encryption), enabling the claims to be digitally signed and optionally encrypted. The JWT can be sent as part of the header of an HTTP request, from client to server, to validate authorisation of the client.

A JWT is a string representing a set of claims as a JSON object that is encoded in a JWS (JSON Web Signature) or JWE (JSON Web Encryption), enabling the claims to be digitally signed and optionally encrypted. The JWT can be sent as part of the header of an HTTP request, from client to server, to validate authorisation of the client.

What’s the difference between authentication and authorisation?

Authentication is the process of determining the identity of an entity to verify that they are who they say they are, whereas the authorisation process is the granting of access rights or claims to an entity, once they have been successfully authenticated.

Where are JWTs useful?

JWTs are great for API authentication and server-to-server authorisation. When a user successfully authenticates to a web server or API, it generates and returns a JWT that can contain the user’s ID as well as additional claims that the user has. The JWT is then sent back to the user’s browser as part of the response and can then be stored in the browser’s session to be submitted on subsequent request to the server.

When the server receives a JWT, it can guarantee that the data it contains has not been modified by a middleman, as its contents have been cryptographically signed. Once the JWT has been validated by the server, it can use the JWT’s claims to check the users access to protected resources.

What’s the structure of a JWT?

A JWT consists of three parts:

Header
Payload
Signature

In its compact form the 3 parts of a JWT are individually Base64URL encoded and separated by dots, i.e. ‘xxxxxx.yyyyyy.zzzzzz’. The Header and Payload parts are individual JSON Objects.

Header

The header normally consists of two fields: the type of token and the signing algorithm that is being used. An example header is as follows:

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

Its corresponding Base64URL encoded format is:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Payload

The payload part of the JWT contains the associated claims for the user. There are 3 types of user claims: registered, public and private. None of these are mandatory and they exist to prevent namespace clashing of claim names.

An example of a payload is as follows, using a combination of registered and public claims:

{
  "sub": "e3dd5610-4e7f-4370-b5f8-d7c3c6ce2f0e",
  "name": "Bob Roberts",
  "iat": 1554108356
}

The “sub” (subject) is a registered claim and identifies the principal that is the subject of the JWT.

The “name” is a public claim defined in the IANA JSON Web Token registry, that is used to identify the user’s name?

The “iat” (issued at) is a registered claim that identifies the time at which the JWT was issued and can be used to determine the age of the JWT.

Its corresponding Base64URL encoded format is:

eyJzdWIiOiJlM2RkNTYxMC00ZTdmLTQzNzAtYjVmOC1kN2MzYzZjZTJmMGUiLCJuY W1lIjoiQm9iIFJvYmVydHMiLCJpYXQiOjE1NTQxMDgzNTZ9

Signature

The signature of the JWT is calculated by combining:

Base64URL encoded header, a ‘.’ and the Base64URL encoded payload
A secret
The algorithm specified in the header

And signing the result.

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  your-256-bit-secret
)

So what you end up with as your compact JWT will look like the following, ‘header.payload.signature’:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJlM2RkNTYxMC00ZTdmLTQzNz AtYjVmOC1kN2MzYzZjZTJmMGUiLCJuYW1lIjoiQm9iIFJvYmVydHMiLCJpYXQiOjE1N TQxMDgzNTZ9.r8F6UP77msP9wgMB9Uqq3RkiO0eAD3Q24TT3eXxfdg0

When the user agent wants to access a protected resource on the server that issued the JWT, it includes the JWT as an HTTP authorisation header as follows:

Authorization: Bearer

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJlM2RkNTYxMC00ZTdmLTQzNz AtYjVmOC1kN2MzYzZjZTJmMGUiLCJuYW1lIjoiQm9iIFJvYmVydHMiLCJpYXQiOjE1N TQxMDgzNTZ9.r8F6UP77msP9wgMB9Uqq3RkiO0eAD3Q24TT3eXxfdg0