Understanding JWT Tokens in 3 Minutes

JSON Web Tokens (JWT) play a crucial role in authentication on the Internet (via websites and mobile apps).

In this article, we'll explore together the concept of JWTs, understand their purpose and how they work to guarantee data integrity (notably the signature).

Usage

The first thing to understand is that JWT tokens are used in authentication (or identification) systems, but they alone are not enough to handle all of authentication!

A token is simply a token, an identifier that will be exchanged

At the casino, you exchange a piece of plastic (the chip) for a financial value (say €50), and well, in an application, you're going to exchange your token for data and access rights.

But unlike casino chips, your "token" contains information about you (the user) and allows you to be identified, and to prove that it is indeed you who is making the request!

And the advantage is that you don't lose your token by sharing it with an authentication server, you simply send a copy of this token, which can be read by the server to identify you!

But how does it actually work?

How it works

The structure of a JWT token

Here's an example token:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiZXhwIjoxNjM4MzA2MzYyfQ.tzN8XdOlxOQo6fEOMY25Gbn6cNF5iYAOXA-oy89fJEg

That looks like any encrypted unique identifier, you might say!

And yet, we're far from it, because a JWT token is not encrypted, it is signed, which is very different: this means, among other things, that its content is completely public!

Proof of this: if you copy-paste the previous token onto the jwt.io site, you'll get the following result:

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

// payload
{
  "sub": "1234567890",
  "name": "John Doe",
  "exp": 1638306362
}

Look at the payload, you'll see two important pieces of information, a name and an id: "John Doe" and "1234567890"

A JWT is made up of three parts: the header, the payload, and the signature (which we'll look at right after).

The header and the payload are simply two JSON objects, and to form the token (the string of characters), you just need to change their encoding to Base64, like this:

const str = JSON.Stringify({
  "alg": "HS256",
  "typ": "JWT"
})

const header = btoa(str); //eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

The btoa(…) method converts to Base64, and you would just need to do the same thing with the payload to reconstruct our token (except for the signature)

But let's now break down the content of the latter:

Header

The header contains metadata about the token type and the signing algorithm used. It looks something like this:

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

Payload

The payload carries everything you'll need to identify a user, a basic example:

{
  "sub": "1234567890",
  "name": "John Doe"
  "exp": 1638306362
}

It's up to you to decide what you need in the payload!

But there are a few conventions that are useful to follow:

• "sub" represents the user identifier
• "exp" represents the token's expiration date (timestamp)

Signature

But the most important part of a token, which we still need to explain, is the signature!

It's like on a check for the bank, but more secure…

One might think that if it's possible to transform a simple JSON object, and convert it to Base64, it would be possible to impersonate any user!

Except that you'll be missing the signature… And when the server opens the falsified token, and sees that the signature doesn't match the expected one, it will reject the token immediately!

To create this signature, we need three things:

• the token's header
• the token's payload
• a secret key (never to be shared)
• an algorithm specified in the header (in our example, "HS256")

And it's by running all of this through the wringer that we'll be able to sign our token!

And since the secret key never leaves the server, then it will be impossible for anyone else to issue a falsified token!

In other words, if the server validates the signature, it can use the information contained in the "payload" with total confidence, and identify the user!

This is also referred to as "public read, private write"

Conclusion

A JWT token is an identification token containing the information a server needs to authenticate the user (often the latter's identifier in the database).

The server can trust the token if and only if the signature matches the expected one; this acts as a virtual seal that guarantees the data is reliable and intact.

Only the server is authorized to create a valid JWT token, because it alone possesses the private key!