Implementing JSON Web Tokens in Node.js

Authentication is a fundamental aspect of web applications and APIs. Traditional session-based authentication can be cumbersome, especially in distributed systems or stateless APIs. JSON Web Tokens (JWT) have become a popular solution for stateless authentication, allowing servers to securely verify the identity of users without storing session data.

In this post, we will explore what JWT is, how it works, and how to implement it in a Node.js application. We will cover generating tokens, sending them to clients, verifying tokens on protected routes, and best practices for secure authentication.

Introduction to JSON Web Tokens (JWT)
How JWT Works
Advantages of JWT over Session-Based Authentication
Installing Required Packages in Node.js
Generating JWT Tokens
Sending JWT to Clients
Verifying JWT on Protected Routes
Refresh Tokens and Expiration
Role-Based Access Control with JWT
Error Handling in JWT Authentication
Securing JWTs
JWT in Real-World Applications
Best Practices for Using JWT in Node.js
Conclusion

1. Introduction to JSON Web Tokens (JWT)

JSON Web Tokens (JWT) are an open standard (RFC 7519) for securely transmitting information between parties as a JSON object. JWTs are self-contained, meaning they include all the information needed to authenticate a user and can be verified without accessing a database or server-side session.

A JWT consists of three parts:

Header: Specifies the type of token and signing algorithm.
Payload: Contains the claims, such as user information or token metadata.
Signature: Ensures the token has not been tampered with, generated using a secret key.

Example JWT structure:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.
eyJ1c2VybmFtZSI6ImpvaG4iLCJpYXQiOjE2MTA5MjM5MDAsImV4cCI6MTYxMDkyNzUwMH0
.
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

2. How JWT Works

JWT works through a simple process:

User Login: The user submits credentials (username/password) to the server.
Token Generation: The server validates credentials and generates a JWT containing user information.
Token Transmission: The JWT is sent to the client, usually in the response body or as an HTTP-only cookie.
Client Stores Token: The client stores the token (localStorage, sessionStorage, or cookie) and sends it in subsequent requests to protected routes.
Token Verification: The server verifies the token using the secret key and grants access if the token is valid.

3. Advantages of JWT over Session-Based Authentication

Stateless: No server-side session storage is required.
Scalable: Ideal for distributed systems, microservices, and APIs.
Self-contained: Token contains user information and metadata.
Flexible: Can be used for authentication, authorization, and secure data exchange.

4. Installing Required Packages in Node.js

To implement JWT in Node.js, we need the following packages:

express: For creating server and routes.
jsonwebtoken: For generating and verifying JWT.
bcrypt: For hashing and comparing passwords (optional but recommended).

Install the packages:

npm install express jsonwebtoken bcrypt

5. Generating JWT Tokens

JWT tokens are generated after validating the user’s credentials. You create a payload containing user information, sign it with a secret key, and optionally set an expiration.

Example:

const jwt = require('jsonwebtoken');
const secretKey = 'your_secret_key';

function generateToken(user) {
  const payload = {
id: user.id,
username: user.username,
role: user.role  };

  const token = jwt.sign(payload, secretKey, { expiresIn: '1h' });
  return token;
}

payload: Contains user-specific data to be included in the token.
secretKey: Secret key used for signing the token.
expiresIn: Optional property to define token expiration time.

6. Sending JWT to Clients

After generating the JWT, send it to the client either in the response body or as an HTTP-only cookie.

Sending in Response Body

app.post('/login', (req, res) => {
  const { username, password } = req.body;

  // Validate credentials (example)
  if (username === 'john' && password === 'password123') {
const user = { id: 1, username: 'john', role: 'user' };
const token = generateToken(user);
res.json({ token });  } else {
res.status(401).json({ message: 'Invalid credentials' });  }
});

Sending as HTTP-Only Cookie

res.cookie('token', token, {
  httpOnly: true,
  secure: true, // use true in production
  maxAge: 3600000
});
res.json({ message: 'Login successful' });

Using cookies adds extra security by preventing access to the token via JavaScript (reduces XSS attacks).

7. Verifying JWT on Protected Routes

To protect routes, you need middleware that verifies the JWT before allowing access.

Example Middleware:

function verifyToken(req, res, next) {
  const token = req.headers['authorization']?.split(' ')[1]; // Bearer token

  if (!token) {
return res.status(401).json({ message: 'Access denied. No token provided.' });  }

  try {
const decoded = jwt.verify(token, secretKey);
req.user = decoded; // Attach user info to request object
next();  } catch (err) {
res.status(401).json({ message: 'Invalid or expired token.' });  }
}

Protecting Routes

app.get('/protected', verifyToken, (req, res) => {
  res.json({ message: Welcome ${req.user.username}, user: req.user });
});

verifyToken middleware checks the token validity.
If the token is valid, the request proceeds; otherwise, it is blocked.

8. Refresh Tokens and Expiration

JWT tokens are usually short-lived for security purposes. Refresh tokens allow users to obtain a new JWT without re-authenticating.

Access Token: Short-lived JWT for accessing protected routes.
Refresh Token: Long-lived token stored securely to issue new access tokens.

Example flow:

User logs in and receives both access and refresh tokens.
Access token expires after 1 hour.
User sends refresh token to obtain a new access token.
Server validates refresh token and issues a new access token.

9. Role-Based Access Control with JWT

JWT can include user roles to manage access to different parts of the application.

Example Middleware for Role Verification

function authorizeRoles(...allowedRoles) {
  return (req, res, next) => {
if (!allowedRoles.includes(req.user.role)) {
  return res.status(403).json({ message: 'Access forbidden: insufficient permissions' });
}
next();  };
}

// Protect admin route
app.get('/admin', verifyToken, authorizeRoles('admin'), (req, res) => {
  res.json({ message: 'Welcome, admin!' });
});

10. Error Handling in JWT Authentication

Token Missing: Return 401 Unauthorized
Token Expired: Return 401 and prompt re-login or refresh token
Invalid Token: Return 401 and deny access
Insufficient Permissions: Return 403 Forbidden