JSON Web Tokens (JWT) Basics

According to the spec,

JSON Web Token is a secure way of representing a set of information (claims) to be transferred between two parties.

JWT is a valid JSON Object. When you create a JWT, it should consist some necessary parts. They are,

1. Header
2. Payload
3. Signature

They should be separated by a ‘.’

So the format of a JWT should be like,

header.payload.signature

Header

The header normally consists of two things.

1. the type of the token (how the payload can be interpreted)
2. the name of the algorithm used to make the signature

example of a header

This header tells how signature of the token should be computed. “typ” indicates that this is a JWT token and “alg” tells about the algorithm used to make the signature.

In the above example, signature is generated using HS256 algorithm. In some other examples you may see RS256. Later we will see the difference between both algorithms.

This signature will also be encoded into base64. After encoding it will be look like this.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Let’s assume the above encoded header as X.

Payload

The payload is a JSON object of data. You can put whatever you want in it. This consists the claims.

example of payload

There are three classes of claim names: Registered Claim Names,
Public Claim Names, and Private Claim Names. None of the claims
defined below are intended to be mandatory to use or implement in all
cases, but rather they provide a starting point for a set of useful,
inter-operable claims.

• “iss” (Issuer) Claim- The “iss” (issuer) claim identifies the server(principal) that issued the token.
• “sub” (Subject) Claim- a locally unique identifier within the issuer for the end-user)
• “aud” (Audience)Claim- identifies the recipients that the JWT is
  intended for.
• “exp” (Expiration time)Claim- identifies the expiration time on
  or after which the JWT MUST NOT be accepted for processing.
• “iat” (Issued at)- time at which JWT was issued.
• “jti” (JWT ID) Claim- provides a unique identifier for the JWT.

example of a payload

These are some essential claims in a JWT, but they are not mandatory to use.

Then, this also will be encoded in to base64.

eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9

Let’s assume the above encoded payload as Y.

Signature

For signing, we get the encoded header and payload.

1. data= encoded header+ “.” encoded payload = X + “.” + Y
2. then we hash the data using a hashing algorithm (e.g: SHA 256 )
3. then we encrypt the hashed message using private key (asymmetric cryptography) or or secret key(symmetric cryptography).

Digital signature using asymmetric cryptography

Normally in JWT, we use RS256 (RSA with SHA256) or HS256 (HMAC with SHA-256). So for signature algorithms, we can use RS256 or HS256.

• RS256 (RSA with SHA-256) is an asymmetric algorithm, and it uses a public/private key pair. The identity provider has a private (secret) key used to generate the signature, and the consumer of the JWT gets a public key to validate the signature. Since the public key, as opposed to the private key, doesn't need to be kept secured, most identity providers make it easily available for consumers to obtain and use (usually through a metadata URL).
• HS256 (HMAC with SHA-256), on the other hand, is a symmetric algorithm, with only one (secret) key that is shared between the two parties. Since the same key is used both to generate the signature and to validate it, care must be taken to ensure that the key is not compromised.

TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

is an example of the signature. assume this as Z. By siging the JWT, receiver can authenticate the token.

What to do next?

As I mentioned earlier, a JWT token should be look like header.payload.signature. So now we should get all the decoded header, payload and signature from above and concatenate all using “.”

So it should be

header.payload.signature= X.Y.Z

Now the real JWT token is shown below.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

Now JWT token is ready!

You can go to this jwt.io site and decode the above JWT token. You can see header, payload and signature separately.

Can we send private data in payload? Are they secured?

We encode and sign JWT tokens. But we don’t encrypt token. By signing we can just validate this token is sent by a particular identity server. Since the token is not encrypted, we cannot send any private data. Because anyone can capture the token, decode it and get the data. So data like, credit card number should not be sent as a claim in JWT tokens.

Usage of JWT

But there are so many advantages of JWT tokens. They can be used as an alternative to cookies. OpenID Connect also use ID token as a JSON Web Token to send the end user’s information to the Relying Party.

References:

RFC 7519 - JSON Web Token (JWT)