Introduction to JSON Web Tokens (JWTs)

Sample JSON Web Token from jwt.io

JSON Web Token (JWT) is a compact claims representation format intended for space constrained environments such as HTTP Authorization headers and URI query parameters. It represents a set of claims as a JSON object. This JSON object is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted.

JWT Structure

A JWT is represented as a sequence of three parts separated by dots, where each part contains a base64url-encoded value. The three parts are,

• Header
• Payload
• Signature

Following is a sample JWT and let’s explore how each part is generated.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Header

The header of JWT usually contains two parts. “typ” represents the type of the token which is JWT, and “alg” represents the algorithm used in the signing process such as HMAC, SHA256 or RSA. The base64Url encoded value of the above payload is set as the first part of the JWT.

Payload

Following is the decoded value of the second part of the sample JWT.

This payload contains the claims. A claim is a piece of information about an entity such as the user. These claims can be of three types: registered, public and private claims.

Registered claims: These are predefined claims which are not mandatory, but recommended to use which provides useful information. Following are some of the registered claims.

• “iss”: This represents the principal that issued the JWT. This is an optional claim which is a case-sensitive string containing a StringOrURI
  value.
• “sub”: This is the principal that is the subject of the JWT. This is an optional claim which is a case-sensitive string containing a StringOrURI
  value.
• “aud”: This represents the recipients that the JWT is intended for. Each principal processing the JWT must identify itself with a value in the “aud” claim. This can be a array of case-sensitive StringOrURI values or a string containing a case-sensitive StringOrURI value. This is generally application specific.
• “exp”: This identifies the expiration time of the JWT.
• “nbf”: This identifies the time before which the JWT MUST NOT be accepted for processing.
• “iat”: This identifies the time at which the JWT was issued.
• “jti”: This claim provides a unique identifier for the JWT.

Public claims: These are the claims that are defined at will by who use JWTs. To avoid collisions, it should be defined in the IANA JSON Web Token Registry or should be defined as a URI which contains a collision resistant namespace.

Private claims: These are custom claims, which are not registered claims or public claims. These claim names should be used with caution since it’s subjected to collisions.

Signature

Following is the decoded value of the third part of the sample JWT.

The signature is used to verify that the message is not changed along the way. If it’s signed with a private key, the sender also can be verified. This is calculated using the base64Url encoded header, payload, a secret and the algorithm specified in the header.

When to use JWTs?

JWTs are used mostly in following two scenarios.

• Authorization: This allows a logged in user to access resources, services and routes which are allowed with the JWT. Therefore, each subsequent request should be sent along with the JWT. Nowadays, JWTs are widely used for Single-Sign-On feature due to its small overhead and ability to be used across different domains easily.
• Information Exchange: JWTs are used for secure information transmission between parties. Since JWTs are signed, we can ensure the sender is correct. Further, since the signature is calculated using the header and the payload, it is ensured that the information is not tampered.

How JWTs work?

In the authentication flow, when a user is successfully logged into his/her account using credentials, a JWT is issued. This JSON Web Token should be handled with care since it contains credentials. The token should not be kept longer than required. In signed tokens, we shouldn’t put secret information since the other parties can read the information even though they can’t change.

When the user needs to access a protected resource, the JWT should be sent in the request, typically in the Authorization header using the Bearer schema. Following is a sample content of the header.

Authorization: Bearer <token>

The protected server route will check the validity of the JWT and if valid, the user is allowed to access the protected resource. If the token is sent through HTTP headers, we should prevent getting them bigger.

Following is a simple diagram which shows how a JWT is obtained and used to access resources.

1. The client requests authorization to the authorization server.
2. When the authorization is granted, the authorization server returns an access token to the application.
3. The application uses the access token to access a protected resource.

Why JWTs?

Following are some of the advantages of using JWTs.

• JWT is better to be used in HTML and HTTP environments since the encoded size is smaller.
• The difficulty of signing a JSON using a public/private key pair is less compared to signing an XML.
• Since the JSON parsers are common in various programming languages, it’s easy to work with JWT.
• Client-side processing of JWTs on multiple platforms is easy.

Hope this blog provided a basic idea on JSON Web Tokens. For more information on JWTs, please refer RFC7519. Happy reading!