JSON Web Token (JWT) Tutorial

Structure of a JSON Web Token

A JWT is made of 3 parts: the Header, the Payload and the Signature and they are separated by a period “.” like this:

header.payload.signature

The Header – The header typically consists of two parts: the type of the token (which is JWT) and the signing algorithm being used, such as HMAC with SHA256 (HS256 in short) or RSA.

The Payload – This is a set of claims contained within the JWT that contains a series of key/value pairs. In most cases, claims are user details and additional data. The payload can be read by anyone who intercepts our message, so ensure that you don’t add any sensitive information to the payload.

The Signature – This is used to validate that everything in the JWT has not been tampered with in any way. It is generated using the header, the payload and a secret key (like the password). The signature of a JWT can only be produced by someone in possession of both the payload, the header and a given secret key. The most common algorithms used in signature are HS256 (HMAC SHA256 symmetric encryption) and RS256 (RSA asymmetric encryption and private key signature).

An example of a JWT before being encoded is shown below:

Note: A JWT is cryptographically signed (but not encrypted so using HTTPS is mandatory when storing user data in the JWT)

An example of a JWT:

+ The header of above JWT is: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
+ The Payload is: eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6Im5ldHdvcmt0dXQiLCJpYXQiOjEwOTg3NjU0MzI3fQ
+ The Signature is: 0RdkMinxwA9bvLa2B7o5sSNxC7rPj09aKhrpFvakT5U

Each part is encoded in Base64url format. Base64url encoding is a modified version of base64 for the URL format. It is similar to base64, but uses different non-alphanumeric characters and omits padding). Notice that Base64url is just a way to serialize, not encrypt, the token for sending over web, it can be decoded easily if someone intercepts the token.

If you decode the above JWT (by pasting it into such a website like https://jwt.io in the “Encoded textbox”), you will receive the decoded JSON as shown below:

But you don’t know the signature so you will see the “Invalid Signature” at the bottom of that page. We used the secret word “my-very-Secret-Word!” so if you paste this secret into “your-256-bit-secret” textbox on the right under “VERIFY SIGNATURE” then you will see “Signature Verified”.

Our application can verify the JWT by checking the Signature in the same way of the website above. If the result is “Invalid Signature” then this token has been tampered. If the Signature is verified then our Application can believe and proceed the request.

Where is the secret key saved?

The two most popular algorithms that are used with JWT are HS256 and RS256 so we will learn about them:

+ HS256 (HMAC with SHA-256) is a symmetric algorithm, which only uses one secret key to share between the two parties. This secret key is used both to generate and validate the signature. Therefore it must be stored on both Authentication server (where the token is issued) and the Application (where the token is verified).
+ RS256 (RSA Signature with SHA-256) is an asymmetric algorithm. It uses a public/private RSA key pair. RSA is the name of an encryption/decryption algorithm that takes the private key to encrypt and the public key to validate JWT. The private key (which means our secret key) is kept on the Authentication server only. Since the public key, as opposed to the private key, does not need to be kept secured, and in practical most identity providers make it easily available for consumers to obtain and use (usually through a metadata URL).

From above information, we can see RS256 is safer than HS256 algorithm as the secret password is only available on the Authentication server. RS256 is more flexible too because if we need to change the secret key, we only need to change on the Authentication server (and change the public key in a public place where the Applications can access to, usually via the Internet). With HS256 we have to change on all the Applications as well while keeping it secret.