Intro to Json Web Tokens

What is JWT?

JWT stands for JSON web token and is a secure way to send JSON data between two parties, usually the server and the browser.

This way of communication is largely adopted because a single token can provide integrity and privacy of the data, here we will focus on integrity for now we will talk about privacy later with the signed token.

When can we use it?

A case scenario where JWT is largely used is for sign-in on a web app or an API.

When the user logs in on the app the server generates a token of the user info and sends it back to the client, this token is switched back and forward between the two parties providing the authentication to access the protected endpoints.

JWT structure

A JWT has 3 basic parts required to work,

Header

The JWT header contains the type of the token (usually JWT) and the signature algorithm.

Payload

The payload contains the actual data that's sent from between the two parties, usually some time of info about the user like the username or ID

{
  "name": "John Doe",
  "id": 1
}

Signature

The signature is the part that prevents the token from being tampered with.

The signature is a concatenation of the encoding of the Header and the Payload, run through the signature algorithm with the provided secret getting a unique token that will be appended at the end.

The signature token can't be replicated and a simple change on any of the fields will result in a new signature.

Imagine on the previous example that we change the name from John Doe to Jane Doe when we calculate the signature again on the backend it won't match anymore and the attacker can't generate a valid signature because we don't know the secret that we use on the signature algorithm.

Now we can put the tree parts together on something similar to this

header.payload.signature

and the JWT is ready to be used.

How it works

As we said before when the user logs in the server generate a token for that user and signed it with the secret. That token is sent to the user in the Authorization header using the Bearer schema.

Authorization: Bearer header.payload.signature

This will allow us to send the token back and forward and since it's not on the cookies it won't cause any CORS issue, important for the single sign one (SSO).

Note: The SSO implementation is a complex topic that we will try to cover in another post.

The server when it receives the token validates it using the secret and the signature to be sure that it's valid before dealing with the request.

Please remember that the token is used as user credentials and we must deal with it with care creating an expiration time and not putting sensitive information on it, remember that by default the JWT is only signed and that although it provides integrity of the token it does not provide privacy. By this, we mean that the info on the payload can be easily reverted to plain text.

JWT vs Competitors

Tokens based on JSON have several benefits compared with the XML ones, the most obvious one is the readability and the way that any applications can deal with a JSON, there are several parsers for JSON that work well with nodeJS (our technology of choice). A less obvious one but important nonetheless is the size, the JWT is several times smaller and for a token that will be travelling on all the requests between the two parties the payload size is extremely crucial.