Blog

Introduction

In the realm of web development, securely transmitting information between parties is paramount. One of the most popular methods to ensure secure and efficient transmission of data is through the use of JSON Web Tokens (JWT). JWT is a compact, URL-safe means of representing claims between two parties. This guide aims to provide a comprehensive understanding of JWT, its structure, use cases, benefits, and implementation.

What is JWT?

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.

Structure of a JWT

A JSON Web Token is divided into three parts, each separated by a dot (.):

1. Header
2. Payload
3. Signature

These three parts are encoded using Base64 URL encoding, and concatenated together with dots to form the JWT.

1. 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 SHA256 or RSA.

Example:

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

This JSON is then Base64 URL encoded to form the first part of the JWT.

2. Payload

The payload contains the claims. Claims are statements about an entity (typically, the user) and additional data. There are three types of claims:

• Registered claims: Predefined claims that are not mandatory but recommended, such as iss (issuer), exp (expiration time), sub (subject), and aud (audience).
• Public claims: Claims that can be defined at will by those using JWTs. These can be public and should be collision-resistant.
• Private claims: Custom claims created to share information between parties that agree on using them.

Example:

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true
}

This JSON is then Base64 URL encoded to form the second part of the JWT.

3. Signature

To create the signature part, you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that.

For example, if you want to use the HMAC SHA256 algorithm, the signature will be created in the following way:

HMACSHA256(
  base64UrlEncode(header) + "." + 
  base64UrlEncode(payload), 
  secret)

The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn’t changed along the way.

The output is three Base64-URL strings separated by dots that can be easily passed in HTML and HTTP environments:

xxxxx.yyyyy.zzzzz

Why Use JWT?

1. Compact

Because of its smaller size, JWTs can be sent via URLs, POST parameters, or inside an HTTP header. This makes JWTs more suitable for usage in mobile devices.

2. Self-contained

The payload contains all the required information about the user, avoiding the need to query the database more than once.

3. Secure

JWTs are signed, ensuring the data contained within the token is trusted and unaltered. When using public/private key pairs, the authenticity of the token is guaranteed.

Use Cases of JWT

1. Authorization

This is the most common scenario for using JWT. Once the user is logged in, each subsequent request will include the JWT, allowing the user to access routes, services, and resources that are permitted with that token.

2. Information Exchange

JWTs are a good way of securely transmitting information between parties. Because JWTs can be signed — for example, using public/private key pairs — you can be sure the senders are who they say they are. Additionally, because the signature is calculated using the header and the payload, you can also verify that the content hasn’t been tampered with.

Creating and Validating JWTs

1. Creating a JWT

To create a JWT, you need to decide on the claims you want to include and then generate the token using a library in your programming language of choice. Here’s an example in JavaScript using the jsonwebtoken library:

const jwt = require('jsonwebtoken');

const payload = {
  sub: '1234567890',
  name: 'John Doe',
  admin: true
};

const secret = 'your-256-bit-secret';

const token = jwt.sign(payload, secret, { algorithm: 'HS256' });

console.log(token);

2. Validating a JWT

To validate a JWT, you decode it and verify its signature using the secret or public key. Here’s how you can do it using the jsonwebtoken library in JavaScript:

const jwt = require('jsonwebtoken');

const token = 'your.jwt.token';
const secret = 'your-256-bit-secret';

jwt.verify(token, secret, (err, decoded) => {
  if (err) {
    console.log('Token is not valid:', err);
  } else {
    console.log('Decoded token:', decoded);
  }
});

3. Handling Token Expiration

Tokens typically have an expiration date to prevent misuse. This is done using the exp claim in the payload. Here’s how you can set the expiration time:

const token = jwt.sign(payload, secret, { algorithm: 'HS256', expiresIn: '1h' });

When the token is validated, if it has expired, it will throw an error.

Best Practices for Using JWT

1. Keep it Secret, Keep it Safe

The signing key (secret or private key) should be kept secure and never exposed to the client or any third party.

2. Use Appropriate Algorithms

Choose the algorithm that fits your security needs. HS256 is common for symmetric signing, while RS256 is used for asymmetric signing with public/private key pairs.

3. Short Lifespan

JWTs should have a short lifespan. This minimizes the risk of token misuse if it is intercepted.

4. Use HTTPS

Always use HTTPS to ensure the JWT is transmitted securely between client and server.

5. Store JWT Securely

Do not store JWTs in local storage due to XSS attacks. Use HTTP-only cookies for storing JWTs securely.

Common Pitfalls and Solutions

1. Large Payloads

JWTs should not contain sensitive or large amounts of data. If you need to store more information, use a reference token that points to a secure location.

2. Invalid Tokens

Always check for the validity of a token before trusting its content. Use proper error handling to manage expired or tampered tokens.

3. Token Revocation

JWTs do not have built-in mechanisms for revocation. To handle token revocation, maintain a blacklist of tokens on the server and check against it.

Conclusion

JSON Web Tokens (JWT) offer a robust and efficient way to transmit information securely between parties. Their compact and self-contained nature makes them ideal for authorization and information exchange in modern web applications. By understanding the structure, use cases, and best practices for JWT, computer science students and software development beginners can effectively implement JWT in their projects, ensuring secure and reliable data transmission.

In this guide, we’ve covered the basics and beyond of JWT, providing you with a solid foundation to start using JWTs in your applications. As you advance in your development journey, continue exploring and applying JWT to enhance the security and functionality of your software projects. Happy coding!