JSON Web Tokens (JWTs)

JSON Web Token is an open standard that defines a compact and self-contained way for securely transmitting digitally signed information between parties as a JSON object.

Compact: it can be sent through an URL, POST parameter, or inside an HTTP header.

Self-contained: the payload has all the necessary information about the user.

Structure of JWT

JWTs contain three parts separated by a dot(.) and they are:

  • Header
  • Payload
  • Signature

So the JWT look like this:

hhhhhhhh.pppppppp.sssssssssss

Each part is Base64url encoded.

Header

The header usually has two parts:

  • The type of the token
  • The hashing algorithm used in signing the token

The image below shows an example of a header

alg: is the algorithm used for signing the token, and here it is the HMAC SHA256
typ: is the type of the token which is always JWT

Payload

The second part of the JWT. It contain claims, which are information about an entity and other data.

Claims are three types: registered (predefined claims), public (User defined), and private(custom claims used to share information between parties).

The image below present an example of a payload

The information contained in the payload are protected against tampering and modification, but they can be read by anyone because they are encoded not encrypted. So you should not put any secret information in the payload unless you encrypt them.

Signature

The signature is the third part of the JWT. it can be created by taking the base64 encoded header, the base64 encoded payload, a secret, the algorithm specified in the header and sign that.

Example:

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

The algorithm used in the previous example is the HMAC SHA256.

An Asymmetric hashing algorithm with a public/private key pair can also be used like RSA.

How JWT work

The image below describes how the JWT is used in authentication.

Implementation

There are libraries for implementing JWT in many different programming language. Every programming language has multiple libraries, and they differ in the syntax.

Java JWT example

The code below show how JWT can be created and verified. The library used in this example is jjwt. The signing was done using RS256 algorithm.

// import the necessary packages
import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jws;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import io.jsonwebtoken.security.Keys

// specifying the algorithm and the public/private key pairs
KeyPair keyPair = Keys.keyPairFor(SignatureAlgorithm.RS256)

// creating the signed JWT
String jws = Jwts.builder()
.setHeaderParam("typ", "JWT")
.claim("Name", "Najy")
.claim("admin", true)
.signWith(keyPair.getPrivate())
.compact();




// Verifying the JWT
try{
Jws jws1;
jws1 = Jwts.parser()
.setSigningKey(keyPair.getPublic())
.parseClaimsJws(jws);
out.println("Signature verified, The JWT can be trusted");
out.println("Header: " + jws1.getHeader());
out.println("Payload: " + jws1.getBody());

} catch (Exception ex){ // in case JWT was altered
  out.println("Error: " + ex.getMessage());
}

References

https://jwt.io/introduction/

https://auth0.com/learn/json-web-tokens/

https://en.wikipedia.org/wiki/JSON_Web_Token

https://github.com/jwtk/jjwt