Understanding JWT

Don't get fooled by too many articles out there that make JWT sound more complex and complicated than it actually is. In simple words, JWT is a simple format that aims to transfer claims between two parties in a  compact and secure manner. A claim is a key-value pair that asserts something about a subject. 

The diagram below will give you a very simple idea of how a JWT is layered. It is a set of claims as a JSON object, that is secured by a JWS (JSON Web Signature) or a JWE (JSON Web Encryption) layer.

The diagram below will give you a very simple idea of how a JWT is structured. It is a sequence of URL-safe base64 encoded values separated by '.' characters. 

Example of a JWT

Let's go over a simple example to understand how all of this adds up. This JWT in the example is secured using a JWS signature (Signatures help with integrity checks. For example, it can confirm that the sender of a message is the one who they say they are. Read this for more details). 

Header

The JSON object below is the header of the JWT. All it says is that the JWT is integrity protected using a JWS and is MACed as well using an HMAC SHA-256 algorithm ( Don't worry too much about it for now).

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

To make it eligible to be a part of the resultant JWT token we need to convert it to a base64 encoded string. 

eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9

Payload

The JSON object below is the payload of the JWT. It contains the info that you actually intend to transmit from the sender to the recipient. They are also called claims, as discussed above. 

{"iss":"joe", "exp":1300819380, "http://example.com/is_root":true}

These claims need to be base64 encoded as well. 

eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ

Signature

Now we need to generate the JSON Web Signature for the JWT which is generated with the simple formula:

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

Take the encoded header and the encoded payload

1. Compute the MAC of them combined with the HMAC SHA-256 algorithm and the secret
2. base64-encode the computed result from #2

This formula gives us the resultant value as below:

dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Resultant JWT

This is just the '.' separated sequence of the header, payload, and signature! 

eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.     
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

So, as you can see, you know JWT's now. 

JWT Claims 

A few things to remember about JWT claims:

• Claim names within the JWT must be unique ( no collision )
• The usage of claims in JWT is context-dependent. There are no rules that dictate the type of claims to use etc. 

There are 3 kinds of claims used in JWT and they must be used as appropriate, depending on the use case. 

Registered Claim Names

There are a bunch of registered claim names that are defined in the "JSON Web Token Claims" registry.  There is no rule that enforces the usage of these claim names. Instead, these are helpful standards that can be used as necessary by the developers. 

For example :

• iss Claim - Identifies the issuer of the jWT
• sub Claim - Identifies the subject of the JWT
• exp Claim - Identifies the expiration time of the JWT

Public Claim Names

These can be defined as appropriate by the developers. Collision prevention should be kept in mind while defining these. So, they should ideally be defined in the registry. 

Private Claim Names

These care claim names that are agreed upon by the sender and the recipient of the JWT. These are prone to collisions and hence, uniqueness should be kept in mind while defining these. 

JWT Header

The JWT header generally defines the cryptographic operations applied on the JWT. If you look at the example from above, we used 2 parameters:

• type - Defines the media type of the JWT. 
• alg - Defines the algorithm used to encrypt/secure/sign the JWT. 

If you are wondering whether claims names can also be used as JWT header parameters, the answer is a yes. At the end of the day, this is something you can control while designing your JWT. 

Unsecured JWTs

Yes, they exist! JWTs may be created without any signature or encryption. For such JWTs set the alg header parameter value as "none". Its signature value is also an empty string, something like this : 

eyJhbGciOiJub25lIn0
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.

Uses 

JWTs are used everywhere these days for various purposes. A few of those are explained below

• Authorization of clients in a Client-Server application. It helps determine the identity of the client every time a request is sent to the server, without the server having to store the client's details. The signature in the token suffices. 
• Authorization of a client across multiple servers where the servers agree to use the same JWT to identify the client. For example. if you are the client of Server1 and, Server1 redirects you to Server2 (and Server1 and Server2 agree to use the same JWT), you don't have to worry about authorization with Server2. The same JWT can be sent in your subsequent requests to Server2, and they should be able to identify you.