Traditional methods often rely on server sessions and cookies. Those work, but they don’t always scale well, especially when you’re building APIs or mobile apps that talk to multiple services. This is why JWTs, or JSON Web Tokens, are useful. They’re small, self-contained tokens that can carry user data safely between a client and a server.

JWTs make it easy to verify users without constantly checking a database – but they also expire fast to reduce risk. To keep users logged in without forcing them to sign in again every few minutes, we use something called a refresh token. It’s a separate, long-lived token that can request new access tokens when the old ones expire.

In this guide, we’ll walk through how to build a secure authentication system using JWTs and refresh tokens. You’ll learn how to generate tokens, validate them, handle expiry, and keep everything safe from common security threats.

Table of Contents

1. Understanding JWTs (JSON Web Tokens)

2. Setting Up the Project

3. How to Implement JWT Authentication

4. How to Verify JWTs and Protect Routes

5. Refresh Tokens and Rotation

6. Conclusion

Understanding JWTs (JSON Web Tokens)

A JWT, short for JSON Web Token, is a compact way to share information between a client and a server. It’s often used to prove that a user is who they say they are. The token is created on the server after a user logs in and is then sent back to the client. The client then includes this token with each request, so the server knows who is making the call.

A JWT has three parts: a header, a payload, and a signature.

• The header usually tells the system which algorithm was used to sign the token.

• The payload contains the data, such as the user’s ID or role.

• The signature is the part that keeps everything secure. It’s created by hashing the header and payload with a secret key.

Once created, a JWT looks like a long string of random characters separated by dots. When the client sends it back to the server, the server verifies the signature using the same secret key. If it matches, the request is trusted.

One of the main benefits of JWTs is that they are stateless. The server doesn’t need to store session data. Everything needed to verify the user is already inside the token. This makes them fast and easy to use in modern APIs and microservices.

JWTs do have a downside: they cannot be revoked easily once issued. If a token is stolen, the attacker can use it until it expires. This is why short token lifetimes matter. It’s also why refresh tokens exist.

In the next section, we’ll finish the basic JWT setup. After that, we’ll add refresh tokens in “Refresh Tokens and Rotation.” That part shows how to handle expiry without making users log in again.

Setting Up the Project

Before writing any code, let’s set up a simple backend where we can build and test our authentication system. For this guide, we’ll use Node.js with Express, since it’s lightweight and easy to follow. You can use any stack later once you understand the flow.

Prerequisites

Make sure you have:

• Node.js and npm installed

• A text editor (VS Code works great)

• Basic knowledge of JavaScript and APIs

1. Initialize the Project

Create a new folder and open it in your terminal.

mkdir jwt-auth-demo
cd jwt-auth-demo
npm init -y

This creates a package.json file that will track your dependencies.

2. Install Dependencies

You’ll need a few packages to get started:

• express: the web framework

• jsonwebtoken: to create and verify tokens

• bcryptjs: to hash passwords

• dotenv: to manage environment variables

Install them all at once like this:

npm install express jsonwebtoken bcryptjs dotenv

If you want auto-reloading while developing, install nodemon as a dev dependency:

npm install --save-dev nodemon

3. Project Structure

Here’s a clean structure to keep things organized:

jwt-auth-demo/
│
├── server.js
├── .env
├── package.json
│
├── config/
│   └── db.js
│
├── middleware/
│   └── auth.js
│
├── routes/
│   └── auth.js
│
└── models/
    └── user.js

4. Basic Express Setup

In server.js, start with a minimal Express server.

require('dotenv').config();
const express = require('express');
const app = express();

app.use(express.json());

app.get('/', (req, res) => {
  res.send('JWT Auth API running');
});

const PORT = process.env.PORT || 5000;
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));

You can now run it using:

node server.js

or, if you’re using nodemon:

npx nodemon server.js

If everything is set up correctly, visiting http://localhost:5000 should display “JWT Auth API running”:

How to Implement JWT Authentication

Now that your server is up, let’s add real authentication. We’ll start with user registration, password hashing, and login. Each user will get a token after logging in, which they can use to access protected routes.

1. Set Up the User Model

We’ll store users in a simple database. For this demo, let’s use MongoDB with Mongoose, since it’s quick to set up and easy to scale later.

Install the required packages:

npm install mongoose

Then create models/user.js:

const mongoose = require('mongoose');

const userSchema = new mongoose.Schema({
  username: { type: String, required: true, unique: true },
  email: { type: String, required: true, unique: true },
  password: { type: String, required: true }
});

module.exports = mongoose.model('User', userSchema);

We store users with a unique email and a hashed password. The database never sees the raw password. Hashing makes stolen data harder to use.

2. Connect to MongoDB

Inside config/db.js:

const mongoose = require('mongoose');

const connectDB = async () => {
  try {
    await mongoose.connect(process.env.MONGO_URI);
    console.log('MongoDB connected');
  } catch (err) {
    console.error(err.message);
    process.exit(1);
  }
};

module.exports = connectDB;

mongoose.connect reads the connection string from .env. If the connection fails, we exit the process so we don’t continue in a broken state.

Update your server.js to include the connection:

const connectDB = require('./config/db');
connectDB();

And don’t forget to add your MongoDB URI in the .env file:

MONGO_URI=mongodb+srv://yourusername:yourpassword@cluster.mongodb.net/auth
JWT_SECRET=your_jwt_secret_key

3. Create Registration and Login Routes

In routes/auth.js:

const express = require('express');
const bcrypt = require('bcryptjs');
const jwt = require('jsonwebtoken');
const User = require('../models/user');

const router = express.Router();

// Register a new user
router.post('/register', async (req, res) => {
  try {
    const { username, email, password } = req.body;

    const existingUser = await User.findOne({ email });
    if (existingUser) return res.status(400).json({ message: 'User already exists' });

    const hashedPassword = await bcrypt.hash(password, 10);

    const newUser = new User({ username, email, password: hashedPassword });
    await newUser.save();

    res.status(201).json({ message: 'User created successfully' });
  } catch (err) {
    res.status(500).json({ message: 'Server error' });
  }
});

// Login and issue JWT
router.post('/login', async (req, res) => {
  try {
    const { email, password } = req.body;

    const user = await User.findOne({ email });
    if (!user) return res.status(400).json({ message: 'Invalid credentials' });

    const isMatch = await bcrypt.compare(password, user.password);
    if (!isMatch) return res.status(400).json({ message: 'Invalid credentials' });

    const payload = { id: user._id, email: user.email };

    const token = jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: '15m' });

    res.json({ token });
  } catch (err) {
    res.status(500).json({ message: 'Server error' });
  }
});

module.exports = router;

Add it to your server in server.js:

const authRoutes = require('./routes/auth');
app.use('/api/auth', authRoutes);

4. Test It Out

You can now test these routes using Postman or Insomnia.

Send a POST request to /api/auth/register with a JSON body:

{
  "username": "demoUser",
  "email": "demo@email.com",
  "password": "mypassword"
}

The register route checks for an existing user by email. It hashes the password with a cost factor of 10 and then returns a 201 on success. We don’t log the password or include it in the response.

Then log in at /api/auth/login to receive a JWT.

The login route finds the user by email and compares the password with bcrypt.compare. If it matches, we sign a token with a small payload: the user ID and email. The JWT_SECRET signs the token so the server can verify it later. The expiresIn: '15m' setting keeps the token short-lived to limit risk. The response only includes the token. User data can be fetched from a protected route.

Once you get the token, copy it, you’ll use it to access protected routes later.

How to Verify JWTs and Protect Routes

Now that login returns a token, we should verify it on each request that needs auth. We will write a small middleware that checks the Authorization header, validates the token, and adds the user info to the request.

1. Create the Auth Middleware

Create middleware/auth.js:

const jwt = require('jsonwebtoken');

function auth(req, res, next) {
  const authHeader = req.headers.authorization || '';
  const [scheme, token] = authHeader.split(' ');

  if (scheme !== 'Bearer' || !token) {
    return res.status(401).json({ message: 'Missing or invalid Authorization header' });
  }

  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = { id: decoded.id, email: decoded.email };
    next();
  } catch (err) {
    if (err.name === 'TokenExpiredError') {
      return res.status(401).json({ message: 'Access token expired' });
    }
    return res.status(401).json({ message: 'Invalid token' });
  }
}

module.exports = auth;

What it does:

• Reads the Authorization header.

• Checks for the Bearer <token> format.

• Verifies the token with the secret.

• Attaches a simple user object to req for later use.

2. Create the Protected Route

Create a small profile route that returns the current user. Add routes/profile.js:

const express = require('express');
const auth = require('../middleware/auth');
const User = require('../models/user');

const router = express.Router();

router.get('/me', auth, async (req, res) => {
  try {
    const user = await User.findById(req.user.id).select('-password');
    if (!user) {
      return res.status(404).json({ message: 'User not found' });
    }
    res.json({ user });
  } catch (err) {
    res.status(500).json({ message: 'Server error' });
  }
});

module.exports = router;

Wire it in server.js:

const profileRoutes = require('./routes/profile');
app.use('/api/profile', profileRoutes);

Now a GET /api/profile/me call will only work with a valid token.

3. Handle Token Expiry Clearly

Short access tokens reduce damage if they leak. We set expiresIn: '15m' during login. When a token expires, the middleware returns a 401 with Access token expired.

We won’t refresh the token here because refresh requires its own endpoint, storage, and rotation rules. You’ll add that in “Refresh Tokens and Rotation.” For now, the 401 proves that the expiry is enforced.

4. Testing the Flow

In this section, we’ll test that the server blocks requests without a valid token and allows requests with a valid token.

Log in at /api/auth/login and copy the token. Then call /api/profile/me with:

Authorization: Bearer <paste_token_here>

You should see the current user without the password field.

Then remove the header or change the token and call again. You should get a 401.

Next, wait for the token to expire or change expiresIn to a very short value for a quick test. Call again and confirm you get Access token expired.

Tips for debugging

• 401 with “Missing or invalid Authorization header” means the header format is wrong. Use Authorization: Bearer <token>.

• 401 with “Invalid token” means the token string is wrong, signed with the wrong secret, or corrupted.

• 401 with “Access token expired” means the expiry check works. You will fix the client experience with the refresh endpoint later.

• If all calls fail, confirm your JWT_SECRET is set in .env and that the server was restarted after changes.

5. Optional Cookie Support

You can store tokens in HTTP-only cookies. The browser sends them automatically. Scripts cannot read HTTP-only cookies, which reduces the risk from XSS.

Install and enable cookies:

npm install cookie-parser

// server.js
const cookieParser = require('cookie-parser');
app.use(cookieParser());

Read the access token from a cookie as a fallback:

// middleware/auth.js
const jwt = require('jsonwebtoken');

function auth(req, res, next) {
  const header = req.headers.authorization || '';
  const [scheme, tokenFromHeader] = header.split(' ');
  const tokenFromCookie = req.cookies?.access_token;

  const token = scheme === 'Bearer' && tokenFromHeader ? tokenFromHeader : tokenFromCookie;

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

  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = { id: decoded.id, email: decoded.email };
    next();
  } catch (err) {
    const msg = err.name === 'TokenExpiredError' ? 'Access token expired' : 'Invalid token';
    return res.status(401).json({ message: msg });
  }
}

module.exports = auth;

How this works:

• The access token can live in a cookie named access_token.

• Mark the cookie as httpOnly and secure in production.

• Set sameSite: 'strict' to reduce CSRF risk.

• For APIs used by browsers, cookies simplify sending tokens. For SPAs that call many domains, an Authorization header may be simpler.

In the next section, we’ll use the same cookie approach for the refresh token. That section explains why refresh belongs in a cookie and how rotation blocks replay.

Refresh Tokens and Rotation

Access tokens are short-lived and used on every request. They prove the user identity quickly. Refresh tokens live longer and are used only to get new access tokens when the old ones expire. This split keeps day-to-day requests fast and limits the damage if a token leaks.

We will store the refresh token in an HTTP-only cookie. This reduces exposure to scripts and keeps the flow smooth.

1. Install and Setup

We already have cookie-parser. We won’t add anything new for now, but we will use Node’s built-in crypto module to hash the refresh token before storing it. As a reminder, hashing means the raw token is never saved. If the database leaks, attackers cannot use the hashes to log in.

Create models/refreshToken.js:

const mongoose = require('mongoose');

const refreshTokenSchema = new mongoose.Schema({
  user: { type: mongoose.Schema.Types.ObjectId, ref: 'User', index: true },
  tokenHash: { type: String, required: true, unique: true },
  jti: { type: String, required: true, index: true },
  expiresAt: { type: Date, required: true, index: true },
  revokedAt: { type: Date, default: null },
  replacedBy: { type: String, default: null }, // new jti when rotated
  createdAt: { type: Date, default: Date.now },
  ip: String,
  userAgent: String
});

module.exports = mongoose.model('RefreshToken', refreshTokenSchema);

2. Token Helpers

Create utils/tokens.js for clean, reusable logic.

const jwt = require('jsonwebtoken');
const crypto = require('crypto');
const RefreshToken = require('../models/refreshToken');

const ACCESS_TTL = '15m';
const REFRESH_TTL_SEC = 60 * 60 * 24 * 7; // 7 days

function hashToken(token) {
  return crypto.createHash('sha256').update(token).digest('hex');
}

function createJti() {
  return crypto.randomBytes(16).toString('hex');
}

function signAccessToken(user) {
  const payload = { id: user._id.toString(), email: user.email };
  return jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: ACCESS_TTL });
}

function signRefreshToken(user, jti) {
  const payload = { id: user._id.toString(), jti };
  const token = jwt.sign(payload, process.env.REFRESH_TOKEN_SECRET, { expiresIn: REFRESH_TTL_SEC });
  return token;
}

async function persistRefreshToken({ user, refreshToken, jti, ip, userAgent }) {
  const tokenHash = hashToken(refreshToken);
  const expiresAt = new Date(Date.now() + REFRESH_TTL_SEC * 1000);
  await RefreshToken.create({ user: user._id, tokenHash, jti, expiresAt, ip, userAgent });
}

function setRefreshCookie(res, refreshToken) {
  const isProd = process.env.NODE_ENV === 'production';
  res.cookie('refresh_token', refreshToken, {
    httpOnly: true,
    secure: isProd,
    sameSite: 'strict',
    path: '/api/auth/refresh',
    maxAge: REFRESH_TTL_SEC * 1000
  });
}

async function rotateRefreshToken(oldDoc, user, req, res) {
  // revoke old
  oldDoc.revokedAt = new Date();
  const newJti = createJti();
  oldDoc.replacedBy = newJti;
  await oldDoc.save();

  // issue new
  const newAccess = signAccessToken(user);
  const newRefresh = signRefreshToken(user, newJti);
  await persistRefreshToken({
    user,
    refreshToken: newRefresh,
    jti: newJti,
    ip: req.ip,
    userAgent: req.headers['user-agent'] || ''
  });
  setRefreshCookie(res, newRefresh);
  return { accessToken: newAccess };
}

module.exports = {
  hashToken,
  createJti,
  signAccessToken,
  signRefreshToken,
  persistRefreshToken,
  setRefreshCookie,
  rotateRefreshToken
};

In this code,

• signAccessToken creates a short token with the user ID and email.

• signRefreshToken creates a long-lived token with a jti value. The jti lets us rotate and track tokens.

• persistRefreshToken hashes the refresh token and stores metadata like expiry and device info.

• setRefreshCookie writes the HTTP-only cookie so the browser sends it to the refresh endpoint automatically.

• rotateRefreshToken revokes the old token, issues a new pair, and saves the new record. Rotation blocks replay if an old refresh token is stolen.

3. Issue Refresh Token on Login

Update your routes/auth.js login handler to create and store a refresh token, then set the cookie.

const express = require('express');
const bcrypt = require('bcryptjs');
const jwt = require('jsonwebtoken');
const User = require('../models/user');
const RefreshToken = require('../models/refreshToken');
const {
  createJti,
  signAccessToken,
  signRefreshToken,
  persistRefreshToken,
  setRefreshCookie
} = require('../utils/tokens');

const router = express.Router();

router.post('/login', async (req, res) => {
  try {
    const { email, password } = req.body;

    const user = await User.findOne({ email });
    if (!user) return res.status(400).json({ message: 'Invalid credentials' });

    const isMatch = await bcrypt.compare(password, user.password);
    if (!isMatch) return res.status(400).json({ message: 'Invalid credentials' });

    const accessToken = signAccessToken(user);

    const jti = createJti();
    const refreshToken = signRefreshToken(user, jti);

    await persistRefreshToken({
      user,
      refreshToken,
      jti,
      ip: req.ip,
      userAgent: req.headers['user-agent'] || ''
    });

    setRefreshCookie(res, refreshToken);

    res.json({ accessToken });
  } catch (err) {
    res.status(500).json({ message: 'Server error' });
  }
});

module.exports = router;

On login, we issue both tokens. The access token goes to the JSON response. The refresh token goes to an HTTP-only cookie scoped to /api/auth/refresh. This keeps the refresh token away from frontend code while still letting the browser send it to the refresh endpoint.

4. The Refresh Endpoint

Create an endpoint that reads the refresh cookie, verifies it, checks the database entry, and rotates it. If all checks pass, it returns a new access token and sets a new refresh cookie.

Add to routes/auth.js:

const { hashToken, rotateRefreshToken } = require('../utils/tokens');

router.post('/refresh', async (req, res) => {
  try {
    const token = req.cookies?.refresh_token;
    if (!token) return res.status(401).json({ message: 'No refresh token' });

    let decoded;
    try {
      decoded = jwt.verify(token, process.env.REFRESH_TOKEN_SECRET);
    } catch (err) {
      return res.status(401).json({ message: 'Invalid or expired refresh token' });
    }

    const tokenHash = hashToken(token);
    const doc = await RefreshToken.findOne({ tokenHash, jti: decoded.jti }).populate('user');

    if (!doc) {
      return res.status(401).json({ message: 'Refresh token not recognized' });
    }
    if (doc.revokedAt) {
      return res.status(401).json({ message: 'Refresh token revoked' });
    }
    if (doc.expiresAt < new Date()) {
      return res.status(401).json({ message: 'Refresh token expired' });
    }

    const result = await rotateRefreshToken(doc, doc.user, req, res);
    return res.json({ accessToken: result.accessToken });
  } catch (err) {
    res.status(500).json({ message: 'Server error' });
  }
});

The refresh endpoint verifies the cookie, checks the database record, confirms it is not expired or revoked, then rotates it. Rotation sets revokedAt on the old record and creates a new one with a fresh jti. The response returns a new access token and sets a new refresh cookie.

5. Logout and Revoke

On logout, revoke the current refresh token and clear the cookie.

router.post('/logout', async (req, res) => {
  try {
    const token = req.cookies?.refresh_token;
    if (token) {
      const tokenHash = hashToken(token);
      const doc = await RefreshToken.findOne({ tokenHash });
      if (doc && !doc.revokedAt) {
        doc.revokedAt = new Date();
        await doc.save();
      }
    }
    res.clearCookie('refresh_token', { path: '/api/auth/refresh' });
    res.json({ message: 'Logged out' });
  } catch (err) {
    res.status(500).json({ message: 'Server error' });
  }
});

Logout revokes the matching refresh token if present and clears the cookie. This ends the session cleanly on the server side and the client side.

6. Client Flow

Here is how the browser app should behave:

• Keep the access token in memory. Do not put it in localStorage.

• Call protected APIs with the Authorization header or let cookies handle it if you chose the cookie approach for access.

• If a call fails with Access token expired, call /api/auth/refresh. The browser sends the refresh cookie automatically.

• Replace the in-memory access token with the new one.

• Retry the original request.

• On logout, call /api/auth/logout and clear any local state.

7. Security Notes

There are some key steps you can take to make sure everything is secure:

Separate secrets

Use a different secret for access and refresh tokens. If the access secret leaks, refresh tokens still use a different key. Set JWT_SECRET and REFRESH_TOKEN_SECRET in .env.

HTTPS only

Serve production traffic over HTTPS. Cookies marked secure: true only travel over HTTPS. This protects tokens in transit.

Rotate on every refresh

Issue a new refresh token and revoke the old one each time you refresh. Rotation makes a stolen old token useless after the next refresh.

Hash refresh tokens in the database

Store a SHA-256 hash, not the raw token. This way a database leak does not give attackers the actual token string.

Scope and flags for cookies

Use httpOnly: true, secure: true in production, sameSite: 'strict', and a narrow path such as /api/auth/refresh. These flags reduce XSS and CSRF risk and limit where the cookie is sent.

Short access TTL and moderate refresh TTL

Keep access tokens short, such as 15 minutes. Use a refresh lifetime like 7 days. This keeps risk low without annoying users.

Device awareness

Store ip and userAgent. If patterns change in a suspicious way, you can revoke or challenge the session.

Auditing and limits

Log refresh events and consider rate limits on the refresh endpoint. This helps detect abuse.’

Add to .env:

REFRESH_TOKEN_SECRET=your_refresh_secret_key

Conclusion

You now have a working authentication system that uses JWTs and refresh tokens to keep users logged in safely. The access token handles quick verification. The refresh token quietly renews access when it expires. Together, they strike a balance between security and convenience.

You built user registration, login, protected routes, and a full refresh flow. You also learned how to rotate refresh tokens, store them securely, and handle logout cleanly. Each step adds another layer of safety that keeps your app and users protected.

From here, you can expand this setup to match your real project. You can add role-based permissions, track user sessions by device, or move the logic into a dedicated authentication service. What matters most is understanding the flow and keeping tokens short-lived and well-guarded.

At its core, a JWT is a JSON-based open standard format that allows you to represent specific claims securely between two parties. The exciting part is how widely JWT is used, especially in microservice architectures and modern authentication systems.

In this article, we’ll break down what JWTs really are, explore their structure, and see exactly how they help secure web applications. By the end, you’ll understand why developers rely on JWTs every single day.

Here’s What We’ll Cover

1. Prerequisites

2. What is a JWT?

3. Why Do We Need Tokens?

   • Session Tokens: The Classic Approach

   • JWT: The Modern Solution

4. JWT Structure: Header, Payload & Signature

5. Example: Decoding a JWT

6. How JWTs Ensure Security: The Signature

7. Security Considerations and Token Management

8. How to Create JWTs in Different Languages

9. Practical Implementation: JWT Authentication with Express + MongoDB

   • 1. Project Setup & Dependencies

   • 2. Project Folder Structure

   • 3. Step-by-Step Implementation

   • 4. How to Test Your API

10. Summary

11. Final Words

Prerequisites

To follow along and get the most out of this guide, you should have:

1. Basic familiarity with JavaScript / Node.js

2. Node.js and npm installed on your local machine

3. Basic understanding of HTTP and REST APIs

4. Understanding of JSON and how to parse/serialize it

5. Basic knowledge of Express (or ability to follow along)

6. A running instance of MongoDB (local or remote)

7. Experience with asynchronous code / Promises / async-await

8. Familiarity with environment variables / .env setup

I’ve also created a video to go along with this article. If you’re the type who likes to learn from video as well as text, you can check it out here:

What is a JWT?

JWTs are most commonly used for authentication today, but that wasn’t actually their original purpose. They were created to provide a standard way for two parties to securely exchange information. In fact, there’s even an industry standard specification (RFC 7519) that lays out exactly how JWTs should be structured and how they’re meant to be used for data exchange. Think of it like ECMAScript, or ES, which defines the standard for JavaScript.

In real-world applications, JWTs are primarily used for authentication, and that’s the angle we’ll focus on in this article.

But remember that JWTs weren’t designed only for authentication. There are other ways to handle authentication too, and one of the most popular alternatives is session tokens.

Why Do We Need Tokens?

Whatever authentication strategy we use, whether it’s a session token or a JWT, the underlying reason is the same: the stateless nature of the HTTP protocol.

When we exchange requests and responses from a browser to a server or between servers using HTTP, the protocol itself does not retain any information.

Stateless means that during interactions between the client and the server, HTTP doesn’t remember any previous requests or data. In other words, every request must carry all the necessary information separately. HTTP doesn’t store any data on its own. Once it receives information, it forgets it. That’s why we say HTTP is stateless, as it has no inherent state or persistent information.

Think of it this way: when we access a webpage from a server, what information do we actually send to the server? If it’s a simple static website, we don’t need to send much. We just send the URL of the page to the server, and the server responds by delivering the corresponding HTML page. This means the server doesn’t need to remember any information or maintain any state, which is exactly how HTTP is designed to work, because HTTP itself is stateless.

But if the web application provides different responses for each user – in other words, if the website is dynamic – then sending only the URL is not sufficient. The user must also send their identity along with the URL to the server.

For example, if a user wants to access page-1, they must tell the server: “I am User A, please give me page-1.” The server will then respond with page-1 accordingly. But next time, if the user requests, “Now give me page-2”, what will the server do? Since HTTP is stateless, if the request doesn’t include the user’s identity, the server won’t know which response to provide. This means that with every request, the user must provide their identity, right?

But if we look at the websites around us, do we really have to provide our identity every single time? Take Facebook as an example. Once we authenticate and log in, the server shows us the homepage when we request it, or our profile page when we request that, without requiring us to authenticate with every single request.

So the question is, if HTTP is stateless, how is this possible? How does the web application remember our browsing session? The answer is that, web applications can maintain sessions in different ways, and one of the most common methods is by using tokens.

Session Tokens: The Classic Approach

There are two popular options for this. One is a Session Token, and the other is a JSON Web Token (JWT). Let’s understand both so that it becomes clear what JWTs are and why they’re used.

Imagine a scenario in a company’s customer care department. A customer calls in with a complaint. The customer support representative listens to the issue and tries various troubleshooting steps but is unable to resolve the problem.

At this point, they forward the case to their higher management team and create a case file for the customer. This file contains all conversations with the customer and details of the troubleshooting attempts. The customer is then given a case ID or ticket ID, so that the next time they call, they don’t have to go through the same steps all over again.

The next day, when the customer calls again, they give their ticket ID to the customer care representative. The representative searches the system using that ticket ID, retrieves the details, and is able to respond accurately to the customer.

This scenario illustrates how authentication works in a web application using a session token. When a user authenticates, the server creates a session and keeps track of it. A session ID is generated for that session and sent back to the user, similar to the support ticket in the earlier example. From then on, whenever the user sends a request to the server, they include this session ID or token. The server looks up the session using that ID and identifies the client. Since the server has to handle multiple clients, this session token method has become an effective and widely used strategy for authentication.

And how the client sends the session ID to the server can vary depending on the implementation. The most common method is to store the session ID in the browser’s cookies. The advantage of this approach is that whenever the browser sends a request to the same server, it automatically adds the cookie information to the request header. This is a built-in behaviour of browsers, so no extra steps are needed.

When the user authenticates, the server saves data in the browser’s cookie, and from then on, that cookie information is sent automatically with every request, allowing the server to recognize the user. This was a very popular method, although in modern applications it has become a bit outdated.

But this mechanism has some issues. The biggest problem is that it assumes there is only a single server. In modern web applications, there are usually multiple servers. In such cases, a load balancer sits in front and decides which server will handle the user’s request.

Let’s say the session token method is being used. When the user sends the first request, the load balancer forwards it to Server-1. Server-1 creates a session ID and sends it back to the client. Later, when the user sends another request, the load balancer routes it to Server-2. But Server-2 doesn’t have that session ID stored, so how will it know which user the request belongs to?

The common solution to this is to store session IDs not on a specific server but in a shared Redis database, so that any server can verify the session ID from there. This is what’s called a Redis cache. But in a microservice architecture, this approach has a weakness. If for some reason the Redis cache goes down, the servers may still be running, but the authentication mechanism will fail. This is exactly where JSON Web Tokens come in, offering a slightly different approach.

JWT: The Modern Solution

Let’s revisit the customer care department example. This time, imagine there’s no phone or system. The customer comes directly to the office and meets the support agent in person. Since the agent doesn’t have any system this time, they can’t store all the information like before. Instead, they write everything down on a piece of paper and tell the customer, “Next time you come, bring this with you.”

This means the method is a bit different from the previous concept, right? But there’s still a problem: “validity”. If the customer isn’t legitimate and acts maliciously, how can the support representative trust them? The next day, if the customer comes in with the same information written on a blank sheet of paper, how can the agent verify the validity of their identity?

In this case, a possible solution is for the customer care executive to sign the paper when giving it to the customer. Then, when the customer brings the paper back, the support representative can verify the signature and confidently provide the service.

JSON Web Tokens work in a similar way. Here, when the client authenticates, instead of the server saving all the information, it sends all the user’s information as a JSON token along with a signature. Later, with each subsequent request, the client sends the entire token along with the request, which contains information like which user it is, their name, and other necessary details.

In this case, the server doesn’t save anything, and all the information stays with the client. Each time the client sends a request with this token, the server can read it, identify which user made the request, and provide the necessary data.

This token is not just a simple ID. It’s a JSON object containing all the information, and this is what we call a JSON Web Token. How the client stores this JWT is entirely up to the client. The most common methods are storing it in the browser’s cookies or local storage.

JWT Structure: Header, Payload, & Signature

As mentioned, the server receives a JSON object, but a JWT doesn’t look like a regular JSON.

In the image above, it may seem a bit unusual. In fact, it’s an encoded version of the JSON object, a kind of scrambled or compact representation. If you look closely, you’ll see that a JWT is divided into three parts, separated by dots. The first part is the header, the second part is the JSON payload, which essentially holds our data, and the third part is the signature.

If we examine each part individually:

• The header is a separate JSON object.

• The payload is also a separate JSON object containing our data.

• The third part is the signature.

But what does the signature mean here? Simply put, the signature is a hash value. Our data is hashed using a secret key to create the signature. This secret key is kept on the server. So, when this JSON Web Token is sent to the server, the server can use that secret key to verify the signature. This ensures that the token is valid and has not been tampered with.

Example: Decoding a JWT

Let’s look at an example. The best website for working with JWTs and understanding their structure is jwt.io. If you paste a JWT into the site, three sections appear: the header, payload, and signature. The payload is shown in the “Decoded Payload” section, which contains content and data. You’ll see there’s an ID, a JSON object with a name, and an expiration time.

The header is also a completely valid JSON object, which specifies an algorithm and shows the type –essentially indicating which algorithm will be used to create or verify this JWT.

So, the main data is in the “Decoded Payload” section, and the third part is the signature. Now there’s an important point to note: you might wonder where this scrambled-looking token comes from. It’s actually very simple. The data in the “Decoded Payload” is Base64 encoded, and that’s what forms the appearance of this scrambled token.

If you copy this part of the JWT and paste it into any online Base64 decoder, you’ll immediately see the data.

What does this mean? It means that if this data is encoded again using Base64, the same token will be generated. The header works the same way as well.

And the final point: the scrambled or encoded part. Is it done for security? No, it’s not for security. It’s done purely for convenience. JSON objects can be quite large, and not all programming languages handle them in the same way. In JavaScript it’s easy, but in other languages, it can sometimes cause issues. So to make it easier to handle, the data is Base64 encoded. This is not for security, as encoding it like this doesn’t make the data secure, because the information can still be viewed publicly.

As you can see in the diagram above, the moment you enter it on this site, your data is immediately visible. This means that no sensitive information should be stored here, only user identification details, like a user ID or other public information. Passwords or any secret keys should never be stored in the token, because they can be easily read. Even though it looks scrambled or encoded, it is actually public.

How JWTs Ensure Security: The Signature

Now let’s move to the security part, which is ensured by the signature. In our earlier paper example, a person could simply add a signature by hand.

But for data, the process of creating a signature is different. For data, the signature is created cryptographically using a secret key, which is the actual signature. The process of creating the signature is as follows:

1. The data is Base64 encoded.

2. It is concatenated with the secret key.

3. It is encoded again in Base64.

The configuration specifies an algorithm. This algorithm can be changed, but the same algorithm used to create the token must be used to verify it. In other words, the algorithm for generating and verifying the token must always be the same.

Finally, the data is hashed using a secret key. This secret key is not available to the public. Instead, it’s kept only on the server, usually stored securely in a server vault. When this JWT reaches the server, the server uses the secret key to verify whether the token is valid. If it doesn’t match correctly, it will display “invalid signature.” This ensures that the server can confirm whether the token has been tampered with and that its integrity is intact.

For example, if you use love-you-all-from-logicbaselabs as the signature, and the server verifies it, it will show “signature verified”. This demonstrates that the secret key exists only on the server. This ensures that even though public information is displayed, the token’s validity can be confirmed.

JSON Web Tokens aren’t like a password, though. They primarily serve to identify the user. The server can check the JWT to determine whether it belongs to a valid user. In other words, the JWT represents the user’s identity. It’s a very important token, containing secure content along with the signature.

Security Considerations and Token Management

One important thing to remember: if someone gets hold of your JWT, meaning they have the exact same token, they can easily log in as that user. They just need to send requests with that token to gain the necessary access.

You could think of it like this: if someone gets hold of your Facebook password, they can log in to your Facebook account. Similarly, if someone obtains your PayPal account PIN, they can easily access your account. In other words, if someone gets hold of your most secure information, there’s no way to protect it.

The same applies to JWTs: keeping the token safely on the client side is absolutely crucial. In this regard, we are somewhat vulnerable.

There is, though, one key difference. In the case of session tokens, if we assume an account has been compromised, the server can invalidate that session. In other words, no one can log in using that session ID anymore.

But with a JWT, the token remains valid until its expiration time. So there’s no direct way to invalidate it. Since the token is cryptographically self-contained and signed with the server’s secret key, once it’s created, it cannot be directly revoked by the server.

The only way to handle this is what’s done on the web: denylisting the token. In other words, the server maintains a separate database listing all JWT tokens that are denylisted. Whenever a request comes in, the server first verifies whether the token is valid. Then, through middleware, it checks whether the token is on the denylist. Only if it’s not on that list is the user allowed access.

So, these are the rules for using JSON Web Tokens. JWTs can be used in any programming language, especially in the context of REST APIs. They are extremely popular and widely used in microservice architectures.

How to Create JWTs in Different Languages

How you create a JWT depends on the programming language you’re using. For example, in Node.js, there are specialized libraries available, like jsonwebtoken, so it’s straightforward. And in PHP, there are easy-to-use options for creating JWTs as well. So, JWTs are a universal tool, not limited to any specific programming language. Many people think they’re only for JavaScript, but that’s not true.

And remember that JWTs aren’t just used for authentication purposes. You can use them to represent any kind of identity. For example, if you’re going to a concert, access could be granted using a JWT instead of a regular ticket. When your client uses that JWT, the gateway or server can read the token, provide access to the information, and verify it using the signature.

Practical Implementation: JWT Authentication with Express + MongoDB

In this section, we will put into practice all the concepts we have learned so far. Using Express.js and MongoDB, we will build a complete JWT authentication system step by step.

Don’t worry if it feels overwhelming at first. We will go carefully, one step at a time, and by the end, you will have a fully working project. Think of it as entering a building floor by floor: we’ll explore each section thoroughly and come out with a solid understanding.

1. Project Setup & Dependencies

Before writing any code, we need to set up our Node.js project and install the required dependencies.

Initialize the Node.js Project

Open your terminal and run:

mkdir jwt-auth-demo
cd jwt-auth-demo
npm init -y

This will create a package.json file with default settings.

Install Dependencies

We need some packages to build our JWT authentication system:

npm install express mongoose bcryptjs jsonwebtoken dotenv

• express: Fast and minimal Node.js web framework to create API routes.

• mongoose: ODM (Object Data Modeling) library to interact with MongoDB easily.

• bcryptjs: Library to hash and compare passwords securely.

• jsonwebtoken: Library to generate and verify JWT tokens.

• dotenv: Loads environment variables from a .env file to keep secrets secure.

Install Dev Dependencies (Optional)

For development convenience, install nodemon to auto-restart the server on file changes:

npm install --save-dev nodemon

Update package.json scripts:

"scripts": {
  "start": "node server.js",
  "dev": "nodemon server.js"
}

• npm start runs the server normally.

• npm run dev runs the server with auto-restart using nodemon.

2. Project Folder Structure

jwt-auth-demo/
│
├── config/
│   └── db.js
│
├── controllers/
│   └── authController.js
│
├── middlewares/
│   └── authMiddleware.js
│
├── models/
│   └── User.js
│
├── routes/
│   └── auth.js
│
├── services/
│   ├── hashService.js
│   └── jwtService.js
│
├── .env
├── server.js
├── package.json

What goes where?

• config/: Database connection and environment config.

• controllers/: Main logic for each endpoint.

• middlewares/: Functions that run before controllers (for example, auth checks).

• models/: Mongoose schemas.

• routes/: API endpoint definitions.

• services/: Reusable logic (hashing, JWT).

• .env: Secrets and config variables.

• server.js: Entry point of the app.

3. Step-by-Step Implementation

Initialize the Express Server

Before doing anything complex, we need to set up a simple server using Express. Think of this as the heart of our application. This server will be responsible for listening to incoming requests (like user login or register) and sending back responses.

File: server.js

// server.js

// Import the express library to build our server
const express = require("express");

// Create an instance of express
const app = express();

// Middleware to parse JSON request bodies (important for APIs)
app.use(express.json());

// Default route to test server
app.get("/", (req, res) => {
  res.send("Hello World! Your server is working 🚀");
});

// Start the server on port 5000
const PORT = process.env.PORT || 5000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

• We import Express and create an app instance.

• We use middleware to parse JSON requests (important for APIs).

• We define a simple route / to test if our server works.

• We start the server on port 5000 and log a message when it's running.

Now, let’s test it:

• Run node server.js or npm run dev.

• Open your browser at http://localhost:5000.

• You should see: Hello World! Your server is working 🚀

Connect MongoDB with Mongoose

In this step, we want to store users in a database. For that, we will use MongoDB. To interact with MongoDB in Node.js easily, we use Mongoose, which is an ODM library.

File: config/db.js

// config/db.js

// Import mongoose
const mongoose = require("mongoose");

// Connect to MongoDB using environment variable
const connectDB = async () => {
  try {
    await mongoose.connect(process.env.MONGO_URI, {
      useNewUrlParser: true,
      useUnifiedTopology: true,
    });
    console.log("✅ MongoDB Connected");
  } catch (err) {
    console.error("❌ MongoDB Connection Error:", err.message);
    process.exit(1); // Stop server if DB fails
  }
};

module.exports = connectDB;

Now our server is connected to MongoDB. Whenever we insert, update, or query data, it will go into this database.

File: .env

PORT=5000
MONGO_URI=mongodb://127.0.0.1:27017/jwt-auth-demo
JWT_SECRET=your_super_secret_key

The .env file stores sensitive information like your database URI, JWT secret, and server port. By using environment variables, you can keep secrets out of your code and easily change configuration without modifying your source files. Never commit .env to public repositories to protect your credentials.

Create User Model

In this step, we need to define how a User looks in our database. Each user will have a name, email, and password.

File: models/User.js

// models/User.js
const mongoose = require("mongoose");

// Define a schema (blueprint of user data)
const userSchema = new mongoose.Schema({
  name: { type: String, required: true },
  email: { type: String, required: true, unique: true },
  password: { type: String, required: true },
});

// Create and export the model
module.exports = mongoose.model("User", userSchema);

As you can see, each user now has a name, email, and hashed password. This ensures that every user we save has these three fields.

Hashing & JWT Services

In this step, we will handle password hashing and JWT management using separate services. This keeps our code organized and reusable.

File: services/hashService.js

//services/hashService.js

const bcrypt = require("bcryptjs");

// Function to hash a plain password
exports.hashPassword = async (plainPassword) => {
  // bcrypt.hash generates a hashed version of the password
  // The number 10 is the salt rounds, which affects the hashing complexity
  return await bcrypt.hash(plainPassword, 10);
};

// Function to compare a plain password with a hashed password
exports.comparePassword = async (plainPassword, hashedPassword) => {
  // bcrypt.compare checks if the plain password matches the hashed one
  return await bcrypt.compare(plainPassword, hashedPassword);
};

• hashPassword(plainPassword): Takes a plain text password and returns a hashed version using bcrypt. Never store plain passwords directly.

• comparePassword(plainPassword, hashedPassword): Compares a user-entered password with the hashed password stored in the database. Returns true if they match.

File: services/jwtService.js

// services/jwtService.js

const jwt = require("jsonwebtoken");

// Function to generate a JWT
exports.generateToken = (payload) => {
  // jwt.sign creates a signed token using our secret key from environment variables
  // expiresIn defines how long the token is valid (1 hour here)
  return jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: "1h" });
};

// Function to verify a JWT
exports.verifyToken = (token) => {
  // jwt.verify checks if the token is valid and not expired
  return jwt.verify(token, process.env.JWT_SECRET);
};

• generateToken(payload): Generates a JWT for a user. The payload typically contains user ID and email.

• verifyToken(token): Verifies that the JWT is valid and returns the decoded payload if successful.

• Using a separate JWT service keeps token logic centralized and easy to manage.

Auth Controller

In this step, we will handle all authentication-related logic in a separate controller. This keeps routes clean and separates business logic from endpoint definitions.

File: controllers/authController.js

// controllers/authController.js

const User = require("../models/User");
const { hashPassword, comparePassword } = require("../services/hashService");
const { generateToken } = require("../services/jwtService");

// Register new user
exports.register = async (req, res) => {
  try {
    const { name, email, password } = req.body; // Get user input

    // Step 1: Check if user already exists
    const existingUser = await User.findOne({ email });
    if (existingUser)
      return res.status(400).json({ message: "User already exists!" });

    // Step 2: Hash password using hashService
    const hashedPassword = await hashPassword(password);

    // Step 3: Save user to database
    const user = new User({ name, email, password: hashedPassword });
    await user.save();

    // Step 4: Send success response
    res.status(201).json({ message: "User registered successfully!" });
  } catch (err) {
    // Handle errors gracefully
    res.status(500).json({ error: err.message });
  }
};

// Login user
exports.login = async (req, res) => {
  try {
    const { email, password } = req.body; // Get user input

    // Step 1: Find user by email
    const user = await User.findOne({ email });
    if (!user)
      return res.status(400).json({ message: "Invalid email or password" });

    // Step 2: Compare provided password with hashed password
    const isMatch = await comparePassword(password, user.password);
    if (!isMatch)
      return res.status(400).json({ message: "Invalid email or password" });

    // Step 3: Generate JWT using jwtService
    const token = generateToken({ id: user._id, email: user.email });

    // Step 4: Send success response with token
    res.json({ message: "Login successful!", token });
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
};

// Protected profile route
exports.profile = (req, res) => {
  // req.user is set by auth middleware after token verification
  res.json({
    message: "Welcome to your profile!",
    user: req.user,
  });
};

• File: controllers/authController.js – Contains all logic related to authentication.

• exports.register handles user registration:

  • Checks if the user exists.

  • Hashes the password using hashService.

  • Saves the new user to MongoDB.

  • Returns a success message.

• exports.login handles user login:

  • Finds the user by email.

  • Compares passwords using hashService.comparePassword.

  • Generates a JWT token if valid.

  • Returns the token in the response.

• exports.profile handles protected profile route:

  • Returns user information from req.user, which is set by the auth middleware.

• Using a controller keeps route definitions clean and separates business logic from endpoint handling.

Auth Middleware

In this step, we create a middleware to protect routes by verifying JWTs. Only authenticated users can access protected endpoints.

File: middlewares/authMiddleware.js

// middlewares/authMiddleware.js

const { verifyToken } = require("../services/jwtService");

// Middleware to protect routes
module.exports = (req, res, next) => {
  // Step 1: Get Authorization header
  const authHeader = req.headers["authorization"];
  if (!authHeader)
    return res.status(401).json({ message: "No token provided" });

  // Step 2: Extract token from format 'Bearer <token>'
  const token = authHeader.split(" ")[1];
  if (!token) return res.status(401).json({ message: "Malformed token" });

  try {
    // Step 3: Verify token using jwtService
    const decoded = verifyToken(token);

    // Step 4: Attach decoded user info to request object
    req.user = decoded;

    // Proceed to next middleware or route handler
    next();
  } catch (err) {
    // If token is invalid or expired
    res.status(401).json({ message: "Invalid or expired token" });
  }
};

• File: middlewares/authMiddleware.js – Middleware for protecting routes.

• Step 1: Checks if the Authorization header is present.

• Step 2: Extracts the token from the Bearer <token> format.

• Step 3: Verifies the token using jwtService.verifyToken.

• Step 4: Attaches the decoded user info to req.user for use in subsequent route handlers.

• If the token is missing, malformed, invalid, or expired, the middleware responds with 401 Unauthorized. This ensures only authenticated users can access protected routes.

Auth Routes

In this step, we will define authentication-related routes and connect them with the controller and middleware.

File: routes/auth.js

// routes/auth.js

const express = require("express");
const router = express.Router();
const authController = require("../controllers/authController");
const authMiddleware = require("../middlewares/authMiddleware");

// Step 1: Register route
// Users send their name, email, and password to this endpoint
router.post("/register", authController.register);

// Step 2: Login route
// Users send email and password to receive JWT
router.post("/login", authController.login);

// Step 3: Protected profile route
// Only accessible to authenticated users with a valid JWT
router.get("/profile", authMiddleware, authController.profile);

module.exports = router;

• File: routes/auth.js – Central file to define authentication endpoints.

• router.post("/register", authController.register): Handles user registration.

• router.post("/login", authController.login): Handles user login and token generation.

• router.get("/profile", authMiddleware, authController.profile): Protected route, requires JWT. The authMiddleware ensures only authenticated users can access it.

• Using routes with controllers and middleware keeps the application organized and professional.

Main Server File

This is the main entry point of our application. It sets up the server, connects to the database, and mounts all routes.

File: server.js

// server.js

require("dotenv").config(); // Step 1: Load environment variables from .env
const express = require("express");
const connectDB = require("./config/db");

const app = express();

// Step 2: Connect to MongoDB
connectDB();

// Step 3: Middleware to parse JSON request bodies
app.use(express.json());

// Step 4: Mount auth routes
// All auth-related routes will start with /api/auth
app.use("/api/auth", require("./routes/auth"));

// Step 5: Default route to test server
app.get("/", (req, res) => {
  res.send("Hello World! Your server is working 🚀");
});

// Step 6: Start server on PORT from .env or default 5000
const PORT = process.env.PORT || 5000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

• Load environment variables: Using dotenv to keep secrets and configuration separate from code.

• Connect to MongoDB: Calls connectDB() from config/db.js.

• Middleware: express.json() allows Express to parse JSON request bodies.

• Mount routes: app.use("/api/auth", ...) registers all authentication routes.

• Default route: A simple GET endpoint to verify server is running.

• Start server: app.listen starts listening on the configured port.

4. How to Test Your API

In this section, you’ll learn how to test your JWT authentication API using tools like Postman or any HTTP client.

Before testing, make sure your server is running. If it’s not running, open a terminal and run:

npm run dev

or

node server.js

This will start your server on the port defined in .env (default 5000).

Make sure your MongoDB is running. If using local MongoDB, start it with:

mongod

or ensure your MongoDB service is active.

Always check the terminal for any errors. If the server or database fails to start, your API requests will not work.

Register a User

Request:

POST http://localhost:5000/api/auth/register
Content-Type: application/json

{
  "name": "sumit",
  "email": "sumit@example.com",
  "password": "mypassword"
}

Response:

{
  "message": "User registered successfully!"
}

This sends a POST request to http://localhost:5000/api/auth/register with user details. If successful, you get a confirmation message.

Login

Request:

POST http://localhost:5000/api/auth/login
Content-Type: application/json

{
  "email": "sumit@example.com",
  "password": "mypassword"
}

Response:

{
  "message": "Login successful!",
  "token": "<JWT_TOKEN>"
}

This sends a POST request to http://localhost:5000/api/auth/login with email and password. If the credentials are correct, you receive a JWT to access protected routes.

Access Protected Route

Request:

GET http://localhost:5000/api/auth/profile
Authorization: Bearer <JWT_TOKEN>

Response:

{
  "message": "Welcome to your profile!",
  "user": {
    "id": "...",
    "email": "sumit@example.com",
    "iat": ...,
    "exp": ...
  }
}

This sends the JWT in the Authorization header using the Bearer scheme.

• Only valid tokens will allow access to this protected route.

• iat and exp indicate issued-at and expiry time of the token.

Note: Always include Authorization: Bearer <token> for protected routes.

Summary

This article gave you a comprehensive overview of JSON Web Tokens (JWTs) and their role in web authentication. It explained the stateless nature of HTTP, the need for tokens, and compares classic session tokens with JWTs.

We covered JWT structure, security mechanisms, and practical implementation using Node.js, Express, and MongoDB. We also discussed security considerations, token management, and how to test a JWT authentication API.

Here’s a Summary of the Key Points:

1. What is JWT?

   • JWT is a JSON-based open standard for securely representing claims between two parties, defined by RFC 7519.

   • Widely used for authorization in modern web applications and microservice architectures.

   • Alternative to session tokens for maintaining user state.

2. Stateless Nature of HTTP

   • HTTP does not retain information between requests, requiring each request to carry necessary data.

   • Tokens (session or JWT) are used to maintain user sessions in dynamic web applications.

3. Session Tokens

   • Classic approach where the server creates and stores a session ID, typically in cookies.

   • Works well for single-server setups but requires shared storage (for example, Redis) in multi-server environments.

   • Vulnerable if the shared cache goes down.

4. JWT: The Modern Solution

   • Server sends a signed JSON token to the client, which stores and sends it with each request.

   • No server-side storage required – all user info is in the token.

   • Signature ensures validity and integrity.

5. JWT Structure

   • Three parts: Header, Payload, Signature (separated by dots).

   • Header and payload are Base64 encoded JSON objects. Signature is a hash using a secret key.

   • Base64 encoding is for convenience, not security.

6. Decoding JWTs

   • Tools like jwt.io can decode JWTs to show header, payload, and signature.

   • Sensitive data should not be stored in JWTs, as payload is publicly readable.

7. JWT Security

   • Signature is created using a secret key and cryptographic algorithm.

   • Server verifies token integrity using the secret key.

   • JWTs identify users but do not act as passwords.

8. Security Considerations & Token Management

   • If a JWT is compromised, the attacker can impersonate the user until the token expires.

   • JWTs cannot be directly revoked; blacklisting is used to invalidate compromised tokens.

   • Session tokens can be invalidated by the server.

9. JWTs in Different Languages

   • JWTs are language-agnostic and can be implemented in Node.js, PHP, and other languages.

   • Useful for authentication and representing any kind of identity.

10. Practical Implementation: JWT Authentication with Express + MongoDB

    • Step-by-step guide to building a JWT authentication system:

      • Project setup and dependencies

      • Folder structure

      • Express server initialization

      • MongoDB connection

      • User model creation

      • Password hashing and JWT services

      • Auth controller and middleware

      • Auth routes

      • Main server file

      • API testing instructions

11. Testing the API

    • Instructions for registering users, logging in, and accessing protected routes using tools like Postman.

    • Example requests and responses provided.

12. Summary & Final Words

    • JWTs are secure, stateless, and widely used for authorization.

    • Security depends on safe token storage and proper management.

Final Words

You can find all the source code from this tutorial in this GitHub repository. If it helped you in any way, consider giving it a star to show your support!

Also, if you found the information here valuable, feel free to share it with others who might benefit from it. I’d really appreciate your thoughts – mention me on X @sumit_analyzen or on Facebook @sumit.analyzen, watch my coding tutorials, or simply connect with me on LinkedIn.

In this article, you'll learn about:

• What a JSON Web Token (JWT) is

• How JWTs are structured and created

• Different JWT signing techniques and algorithms (Symmetric vs. Asymmetric)

• How JWTs are used in real-world authentication flows

• Important security best practices for using JWTs

Table of Contents

• What is a JWT?

  • JSON Web Tokens Are Made Of Three Elements

  • Asymmetric Signing (RS256) Explained

  • Analogy: The Lock and Key for Asymmetric Signatures

• Symmetric Signing: HS256 (HMAC with SHA-256)

  • How HS256 Verification Works

• JWTs in Action: A Typical Authentication Flow

• JWT Security Best Practices & Considerations

What Is a 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.
— Introduction to JWT by jwt.io

While accurate, this definition can be a bit dense at first glance. Imagine you want to send someone a sealed, tamper-proof message. That's essentially what a JSON Web Token (JWT) is. It's a secure message, a special kind of message designed to be sent between two parties which can be assured it came from an expected sender.

Each JWT is digitally signed using either a secret code (for symmetric algorithms like HMAC) or a private key (for asymmetric algorithms like RSA or ECDSA).

This secret code or private key is known only to the system that issues the JWT (often called an authentication provider, like Auth0, AWS Cognito, or Firebase Auth, which handles user logins and identity).

This signature proves two things:

1. Authenticity: It proves the message really came from who it claims to be from.

2. Integrity: It proves that the message hasn't been changed or tampered with since it was signed. If even one character is altered, the signature won't match, and you'll know something is wrong, meaning the contents of the JWT can't be trusted.

JSON Web Tokens Are Made of Three Elements

JWTs are made up of 3 key parts:

1. Header

2. Payload

3. Signature

Header

The header contains metadata information about the token. Think of it like a label on a package – it tells you what’s inside and how it was prepared.

Typically, the header contains:

alg: This specifies the algorithm used to sign the JWT. Common algorithms are HS256 (HMAC with SHA-256) or RS256 (RSA with SHA-256).

typ: This specifies the type of token, which is almost always JWT for standard JSON Web Tokens.

Example (decoded):

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

Payload

This is the second part of the JWT, and it's where the real data or "claims" are stored. Claims are statements about an entity (usually a user) and any other additional data. Using the previous analogy of a package, think of it as the “contents” of the package.

There are three types of claims:

1. Registered Claims: These are predefined claims that are recommended for common use cases. They are not mandatory but are very useful for interoperability. These include:

• iss – issuer, who issued the token (for example, your application’s domain)

• sub – subject, the subject of the token (for example, a User’s ID)

• aud – audience, the audience of the token (that is, who the token is intended for – for example, a specific API)

• exp – expiration, the expiry date as a timestamp

• iat – issued at, when the token was issued as a timestamp

• nbf – not before, when the token becomes valid (that is, the token cannot be used or deemed valid before this timestamp)

• jti – JWT ID, a unique identifier for the token, useful for preventing replay attacks or blacklisting

2. Public Claims: These can be defined by anyone using JWTs. To avoid naming conflicts, it's a good practice to register them or define them using a unique identifier like a URI.

3. Private Claims: These are custom claims created to share specific information between parties who agree on using them. They are entirely up to you and your application's needs.

Example payload:

{
  "sub": "1234567890", //  subject
  "name": "John Doe", // private claim
  "admin": true, // private claim / role
  "iat": 1678886400, // Issued at a specific timestamp
  "exp": 1678890000  // Expires at a specific timestamp
}

Like the header, this JSON object is also Base64Url encoded (a URL-safe variant of Base64 encoding) to form the second part of the JWT string.

Important Note: The payload is encoded*, not encrypted.* This means that anyone can easily decode the JWT and read its contents. Never put sensitive information (like passwords) directly into the payload unless the entire JWT itself is encrypted (which is a separate process called JWE - JSON Web Encryption). The security of a standard JWT comes entirely from the signature, which prevents tampering.

Signature

The signature, as we've already discussed, is the most important part of the JWT. Without it, there's no protection applied to the JWT, meaning no way to validate the origin of the token or its integrity.

The signature is created by taking the encoded header, the encoded payload, and a secret key (or a private key if using asymmetric algorithms like RSA). These are then run through the cryptographic algorithm specified in the header (alg field). For HS256, a shared secret key is used. For RS256, a private key is used to sign, and a corresponding public key is used to verify. We’ll get on to verification soon.

Think of it like a tamper-proof seal on your package, or even better, a wax seal on a letter. If you receive your letter and the wax seal has been broken, you'd naturally believe the contents of the letter may not be original and therefore can't be trusted.

In pseudo-code it would look like this:

Signature = Algorithm( Base64Url(Header) + "." + Base64Url(Payload), SecretKey )

The result of this signing process is the signature, which is also Base64Url encoded to form the third part of the JWT string.

At the end of the whole process your JWT would look like this:

base64EncodedHeader.base64EncodedPayload.base64EncodedSignature

Asymmetric Signing (RS256) Explained

When a JWT uses an algorithm like RS256 (RSA Signature with SHA-256), it employs an asymmetric cryptographic process involving a public and private key pair. This is where the core magic of proving authenticity and integrity happens without needing to share a secret.

The Signing Process (by the Issuer)

The sender (the server that issues the JWT, like Auth0) possesses the private key. This key is kept absolutely secret and secure. Here are the steps:

1. Prepare the data: The server takes the header (which includes the algorithm) and the payload. It Base64Url-encodes them, and then concatenates them with a dot: Base64Url(Header) + "." + Base64Url(Payload).

   For example, with this header:

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

   And this payload:

    {
      "sub": "1234567890",
      "name": "John Doe",
      "admin": true,
      "iat": 1751494086,
      "exp": 1751497686
    }
   

   This would create a Base64Url-encoded header.payload string like the animated example below:

   

2. Calculate the hash: It then calculates a hash (using SHA-256 in this case) of this combined header and payload string.

3. Sign the hash: Finally, it signs this hash using its private key. This cryptographically transformed hash is the signature part of the JWT.

The JWT is then formed by concatenating the Base64Url-encoded header, the Base64Url-encoded payload, and the Base64Url-encoded signature, separated by dots: header.payload.signature.

The top segment below shows the full JWT token (header.payload.signature):

The Verification Process

This is where the magic happens, and it's often a point of confusion. The public key doesn't "decrypt" the original data like a symmetric key does. Instead, it performs a unique verification process.

The receiver (the client or another server that needs to verify the JWT) possesses the public key. This key does not need to be kept secret – it can be freely distributed.

Here's a step-by-step explanation:

1. Separate the parts: The first thing the receiver does is split the incoming JWT string into its three Base64Url-encoded components: the Header, the Payload, and the Signature.

2. Obtain the public key: The verifier needs the public key that corresponds to the private key used by the issuer. Public keys are often available via a JWKS (JSON Web Key Set) endpoint (for example, your-domain.com/.well-known/jwks.json).

3. Re-create the data to be hashed: The receiver takes the received, Base64Url-encoded Header and the received, Base64Url-encoded Payload. It then combines them exactly as the issuer did: EncodedHeader.EncodedPayload.

4. Compute a local hash (Hash A): This combined string is then put through the same hashing algorithm (for example, SHA-256) that was specified in the JWT's header. This produces a new, locally computed hash (let's call this "Hash A"). This local hash represents what the content should look like if it hasn't been tampered with.

5. "Unsign" the received signature with the public key to get the original signed hash (Hash B): This is the core cryptographic step. The verifier uses the public key (obtained in step 2) to perform a mathematical operation on the received signature. This operation does not create a new signature for comparison. Instead, it effectively "unsigns" or "decrypts" the signature to reveal the original hash ("Hash B") that was produced by the issuer's private key.

   • Crucial Point: This process is for verifying authenticity, not decrypting confidential data. The public key confirms that the signature was indeed created by the corresponding private key, and as part of that confirmation, it returns the original hash that was signed.

6. Compare the hashes: The verifier now has two hashes:

   • Hash A: The hash it computed locally from the received header and payload (from step 4).

   • Hash B: The original hash that was extracted from the received Signature using the public key (from step 5)

7. If Hash A matches Hash B: It proves two critical things:

   1. Authenticity: The token was indeed signed by the legitimate holder of the corresponding private key (for example, Auth0).

   2. Integrity: The content of the header and payload has not been tampered with since it was originally signed. If even a single character in the header or payload were changed, Hash A would be different, and it would not match Hash B. In this case, the JWT is considered valid and its contents can be trusted.

8. If the hashes do NOT match: The token is considered invalid and must be rejected. This indicates either that the JWT was signed by an unauthorised party (a forged token) or that its header or payload has been altered after it was signed.

Analogy: The Lock and Key for Asymmetric Signatures

Private Key: A special, unique key that can lock a box (create a signature). Only the owner has this key.

Public Key: A widely distributed key that can test if a box was locked by the corresponding private key. It can't lock a new box, but it can confirm if an existing lock is authentic.

You don't re-lock the box with the public key. You use the public key to check if the existing lock (the signature) is genuine and corresponds to the contents of the box.

Symmetric Signing: HS256 (HMAC With SHA-256)

While RS256 uses a pair of keys (private for signing, public for verifying), many JWTs you'll encounter are signed symmetrically, most commonly with the HS256 algorithm. HS256 stands for HMAC (Hash-based Message Authentication Code) with SHA-256.

The fundamental difference here is the use of a single, shared secret key for both signing and verification.

How HS256 Signing Works

1. Shared secret key: The issuer (for example, your authentication provider) possesses a single, confidential secret key. This key is known only to the issuer and any parties (like your API) that need to verify the token.

2. Combine header and payload: Just like with asymmetric signing, the issuer takes the Base64Url-encoded Header (which specifies "alg": "HS256") and the Base64Url-encoded Payload, and joins them with a dot.

3. Apply HMAC-SHA256: This combined string is then fed into the HMAC-SHA256 algorithm along with the secret key. The HMAC algorithm uses the secret key to create a unique hash (the signature) of the data. In pseudo-code, it looks like this:

   Signature = HMAC-SHA256( Base64Url(Header) + "." + Base64Url(Payload), SecretKey )

4. Form the JWT: The resulting signature (which is also Base64Url-encoded) is appended to the header and payload with a dot, forming the complete JWT: base64EncodedHeader.base64EncodedPayload.base64EncodedSignature.

How HS256 Verification Works

When a receiver gets an HS256-signed JWT, it goes through a verification process.

First, it separates the parts. The JWT is split into its three Base64Url-encoded components: Header, Payload, and Signature, as we did with asymmetric JWTs.

Then, it obtains the shared secret key. The receiver must also possess the exact same secret key that the issuer used to sign the token. This key is not publicly distributed like a public key – it must be securely provisioned to any entity that needs to verify tokens.

Next, it re-calculates the signature. The receiver does this by taking the received Base64Url-encoded Header and Payload, combining them, and then re-applying the HMAC-SHA256 algorithm using the same secret key. This produces a new, locally computed signature.

Finally, the receiver compares the signature it just calculated locally with the signature it received as part of the JWT.

• If the two signatures match: The token is considered valid. This confirms its authenticity (it came from someone who knows the secret) and integrity (it hasn't been tampered with).

• If the signatures do NOT match: The token is invalid and must be rejected. This indicates either tampering or that it was signed with a different, unknown secret key.

Key Differences and Considerations:

• Key management: With HS256, the secret key must be securely shared and kept confidential by all parties involved in both signing and verifying. This can be more challenging to manage securely at scale compared to the public/private key model, where only the private key needs strict secrecy.

• Performance: HS256 is generally faster to compute than asymmetric algorithms like RS256, making it suitable for high-volume scenarios where the secret key can be securely distributed.

JWTs in Action: A Typical Authentication Flow

Now that you understand how JWTs are structured and signed, let's look at how they're typically used in a real-world web application. This authentication flow is a common pattern you'd encounter.

Step 1: User Logs In:

A user opens a client application (for example, a web browser, mobile app) and enters their login credentials (username and password).

The client sends these credentials securely (always over HTTPS!) to an authentication server (like Auth0, AWS Cognito, or your own backend's authentication endpoint).

Step 2: Authentication Server Issues JWT:

Then the authentication server verifies the user's credentials. If valid, it generates a new JWT. This JWT contains claims (like the user's ID, roles, expiration time) in its payload and is digitally signed by the server's private key (for asymmetric algorithms like RS256) or secret key (for symmetric algorithms like HS256).

The server then sends this signed JWT back to the client.

Step 3: Client Stores JWT:

The client receives the JWT and typically stores it in a secure location, such as browser memory storage, session storage, or an HTTP-only cookie. The method of storage depends on the client type and security considerations.

Step 4: Client Makes API Calls:

When the user wants to access a protected resource on a backend API (for example, their profile data, a private feed), the client includes the JWT in the request.

The standard way to do this is by sending the token in the Authorization header of the HTTP request, prefixed with the word Bearer:

Authorization: Bearer <your_jwt_here>

Step 5: API Verifies JWT & Authorises Request:

Now, the backend API receives the request and extracts the JWT from the Authorization header. The API then performs the JWT verification process depending on the algorithm:

• It checks the token's claims, especially the exp (expiration) claim, to ensure it's still valid.

• If the token is valid, the API trusts the claims within the payload (for example, the user's ID) and proceeds to fulfill the request, potentially using the user's roles to determine if they have permission to access the requested resource.

• If the token is invalid (bad signature, expired, and so on), the API rejects the request, typically with an HTTP 401 Unauthorised status.

This flow is powerful because JWTs are stateless: once issued, the authentication server doesn't need to keep a record of active sessions. The API can verify the token independently, which simplifies scaling and reduces server load.

JWT Security Best Practices and Considerations

While JWTs offer powerful authentication capabilities, using them securely requires careful attention to best practices. Misconfigurations or oversight can lead to significant vulnerabilities.

Always Use HTTPS/TLS:

Crucial: JWTs are encoded, not encrypted, by default. This means anyone who intercepts the token during transmission can easily read its payload. Therefore, JWTs (and all authentication traffic) must always be transmitted over HTTPS (TLS) to encrypt the communication channel itself and prevent eavesdropping.

Protect Your Signing Keys:

Whether it's a private key (for RS256) or a shared secret key (for HS256), these keys are paramount. If an attacker gains access to your signing key, they can forge valid JWTs, impersonate users, and compromise your system. Store these keys securely, preferably in dedicated key management services.

Keep Access Tokens Short-Lived (exp claim):

You should always set short expiration times (for example, 5-15 minutes) for your JWTs used as access tokens. This minimises the window of opportunity for an attacker if a token is compromised.

Since JWTs are stateless, they are hard to revoke immediately once issued. A short lifespan is your primary defense against compromised tokens.

Implement Refresh Tokens (for Longer Sessions):

To maintain user experience with short-lived access tokens, use refresh tokens. A refresh token is a separate, longer-lived token (usually stored more securely) that can be exchanged for a new, short-lived access token when the current one expires, without requiring the user to re-authenticate. Refresh tokens can be revoked by the server, offering better control.

Never Put Sensitive Data in the Payload:

Reiterating this crucial point: the JWT payload is Base64Url encoded, which is easily reversible. Do not put passwords, highly sensitive PII (Personally Identifiable Information), or confidential business data directly into the JWT payload. Only include non-sensitive or publicly available information, or data that's already encrypted by other means.

Validate ALL Claims on Verification:

When verifying a JWT, don't just check the signature. Always validate all relevant claims, including:

• exp (Expiration): Ensure the token hasn't expired.

• iss (Issuer): Verify the token came from the expected authentication server.

• aud (Audience): Ensure the token is intended for your specific API/application.

• nbf (Not Before): Check if the token is active yet.

Consider Token Revocation (for critical cases):

For situations requiring immediate revocation (for example, user password change, account deactivation), typical stateless JWTs are challenging. Strategies include:

• Short expiration times (as above).

• A blacklist/revocation list: Store the jti (JWT ID) of revoked tokens in a database, checking this list on every request. This adds a stateful lookup but provides immediate revocation.

Thanks for reading!

I hope you’ve found this tutorial useful, and as always if you want to ask any questions or hear about upcoming articles, you can always follow me on ‘X’, my handle is @grantdotdev and follow by clicking here.

Authentication ensures that only authorized individuals access specific resources or perform certain actions within a system. It provides accountability by enabling the tracking of user actions and holding individuals responsible for their activities.

It also gives companies data on the number of people using their products. Without proper authentication of your software, you may face security risks. Proper implementation prevents unauthorized access and protects sensitive data.

This tutorial will guide you through building a JWT-based user authentication in NestJS and MongoDb.

NestJS is a powerful Node.js framework for building server-side applications. MongoDB is popular NoSQL database and we’ll use it to build the basic authentication endpoints.

In this tutorial, we'll cover the following topics:

• How to creating a new NestJS project and install the necessary dependencies.
• How to create user models and schemas.
• How to implementing login and signup with JWT token.
• How to test the endpoints with postman.

Prerequisites

This tutorial is a hands-on demo. To follow along, you must have the following:

• Node.js v14 and above

• Node package manager

• MongoDB compass

• Basic understanding of Node.js and preferably ExpressJs

• A code editor (for example: VS Code)

How to Set Up the Project.

In this section, we’ll set up the project to build our REST API with NestJS and MongoDB. We’ll start by installing the NestJS CLI and use it to generate new projects.

Install Nest CLI:

$ npm i -g @nestjs/cli

Then create a new NestJS project with this command:

$ nest new project-name

Let’s call the project authentication:

$ nest new authentication

You will see options about which package manager you prefer to install. I used npm.

After successful installation, move into the created directory and open the project with your preferred code editor.

Before we go into creating resources and configuring the project, let’s take a quick look at the src directory and its files:

• src: The root directory for the source code.

• src/app.module.ts: The application's main module for configuring and integrating other modules.

• src/app.controller.ts: Contains a default controller with a single route.

• src/app.service.ts: This includes a basic service using a single method.

• src/main.ts: The entry point of the application.

Next, install dependencies to set up and connect the database. You will have to install the mongoose package, bcrypt:

$ npm i -save @nestjs/mongoose @types/bcrypt mongoose bcrypt

Next, set up your database. The MongooseModule from the @nestjs/mongoose dependency will be used to set up the database.

Go to src/app.module.ts file:

import { AppController } from './app.controller';
import { AppService } from './app.service';
import { MongooseModule } from '@nestjs/mongoose';
import { UsersModule } from './users/users.module';
import { AuthModule } from './auth/auth.module';
import { ConfigModule } from '@nestjs/config';

@Module({
imports: [
MongooseModule.forRoot('mongodb://localhost:27017/auth-workshop'),
UsersModule,
AuthModule,
ConfigModule.forRoot({
envFilePath: '.env',
isGlobal: true,
}),
],
controllers: [AppController],
providers: [AppService],
})
export class AppModule {}

Let's breakdown the code above. The app.module.ts is the root module of the nestjs application and it is responsible for importing dependecies and other modules required by the application, configuring the application such as database connections and environment variables.

We first specified the app.module.ts file as a module by using the @Module({}) decorator:

@Module({})

The imports array specifies the module that this module depends on. We have the MongooseModule.forRoot('') for database connection using mongoose, ConfigModule.forRoot import sets up the configuration module to read from a .env file:

import { MongooseModule } from '@nestjs/mongoose';
import { UsersModule } from './users/users.module';
import { AuthModule } from './auth/auth.module';
import { ConfigModule } from '@nestjs/config';

imports: [
MongooseModule.forRoot('mongodb://localhost:27017/auth-workshop'),
UsersModule,
AuthModule,
ConfigModule.forRoot({
envFilePath: '.env',
isGlobal: true,
}),
]

You can replace the MongooseModule.forRoot() URI string with your own database string.

The controllers array specifies the controller that belongs to this module:

controllers: [AppController]

The providers array specifies the services that belongs to this module:

providers: [AppService]

With these configurations, you can start your application by using the npm run start:dev.

User models and schemas

In this section, we'll define the User model and schema using mongoose. The User model will represent the users of the application, and the schema will define the structure of the data stored in MongoDB. Let’s start by creating a resource module for the users API:

First, create a users resource with the nest CLI:

$ nest generate res users

This command will create a new users resource in the src/users directory with a basic structure of controllers and services.

Then define the schema for the Users in src/users/entities/users.entity.ts:

import { Prop, Schema, SchemaFactory }
from '@nestjs/mongoose';
@Schema()
export class User {
@Prop()
name: string;
@Prop({ unique: true })
email: string;

@Prop()
password: string;
}
export const UserSchema = SchemaFactory.createForClass(User);

The @Schema decorator is what makes the class a schema. This schema defines three fields for the users: name, email, and password. They are all typed string.

Next, register the schema in the users.module.ts file located in src/users/users.module.ts:

import { Module } from '@nestjs/common';
import { UsersService } from './users.service';
import { UsersController } from './users.controller';
import { MongooseModule } from '@nestjs/mongoose';
import { UserSchema, User } from './entities/user.entity';

@Module({
imports: [MongooseModule.forFeature([{ name: User.name, schema:
UserSchema }])],
controllers: [UsersController],
providers: [UsersService],
})
export class UsersModule {}

By importing the MongooseModule.forFeature([{}]), this configures mongoose to use the UserSchema for the User model.

By registering the schema with Mongoose, we created a model that's ready to use in our application. This sets the stage for building services and controllers that can interact with our data and handle incoming requests.

Lastly, define the DTO (data transfer object). This object transfers data between systems. It is a simple object that contains only data and has no behaviour.

Create your CreateUserDto in the src/users/dto/create-user.dto.ts directory:

export class CreateUserDto {
username: string;
email: string;
password: string;
}

User Services and Controllers

We have connected to the database and created the schema and model of Users. Let’s write the basic CRUD methods for the users.

Update your users.service.ts located in src/users/users.service.ts:

import { Injectable, NotFoundException
} from '@nestjs/common';
import { CreateUserDto } from './dto/create-user.dto';
import { UpdateUserDto } from './dto/update-user.dto';
import { InjectModel } from '@nestjs/mongoose';
import { User } from './entities/user.entity';
import { Model } from 'mongoose';

@Injectable()
export class UsersService {
constructor(@InjectModel(User.name) private userModel:
Model<User>) {}
async createUsers(createUserDto: CreateUserDto) {
const user = await this.userModel.create(createUserDto);
return user.save();
}
async findAllUsers() {
const users = this.userModel.find();
return users;
}
async findUser(id: number) {
const user = await this.userModel.findById(id);
if (!user) throw new NotFoundException('could not find the user');
return user;
}
updateUser(id: number, updateUserDto: UpdateUserDto) {
return this.userModel.findByIdAndUpdate(id, updateUserDto, { new: true
});
}
removeUser(id: number) {
return this.userModel.findByIdAndDelete(id);
};
}

Update your users.controller.ts located in src/users/users.controller.ts:

import { Controller, Get, Post, Body, Patch, Param, Delete, } from '@nestjs/common';
import { UsersService } from './users.service';
import { CreateUserDto } from './dto/create-user.dto';
import { UpdateUserDto } from './dto/update-user.dto';

@Controller('users')
export class UsersController {
constructor(private readonly usersService: UsersService) {}

@Post()
async create(@Body() createUserDto: CreateUserDto) {
return await this.usersService.createUsers(createUserDto);
}

@Get()
async findAll() {
return await this.usersService.findAllUsers();
}

@Get(':id')
async findOne(@Param('id') id: string) {
return await this.usersService.findOneUser(+id);
}

@Patch(':id')
async update(@Param('id') id: string, @Body() updateUserDto:
UpdateUserDto) {
return await this.usersService.updateUser(+id, updateUserDto);
}

@Delete(':id')
async remove(@Param('id') id: string) {
return await this.usersService.removeUser(+id);
}
}

We created RESTful APIs using mongoose. The methods include:

• findAllUsers: Retrieves all user documents from the collection.

• getUserById: Finds a single user document by ID.

• createUsers: Adds a new user document to the collection.

• updateUser: Updates details of existing user in the collection.

• removeUser: Removes user document by ID.

How to Implement Sign-up and Log-in

In this section, we'll create an authentication service that generates JSON Web Tokens (JWTs).

This service will have two methods: signup and login. The signup method will take a signup request object containing name, email, and password),and the login method will take a login request object containing email and password. Both methods will return a JWT.

Let’s start by creating a resource module for the authentication APIs.

Create auth resource with Nest CLI:

$ nest generate res auth

Then define the DTO for both signup and login. Go to the dto folder in the src/auth/dto folder:

signup.dto.ts:

export class SignUpDto {
name: string;
email: string;
password: string;
}

login.dto.ts:

export class Login {
email: string;
password: string;
}

Next, create a .env file in the root directory:

JWT_SECRET=secret
JWT_EXPIRES=3d

Then add the PassportModule, JwtModule and JwtStrategy to AuthModule. We'll start by installing these packages:

$ npm i @nestjs/passport @nestjs/jwt passport passport-jwt bcryptjs

Go to src/auth/auth.module.ts and import these packages:

import { Module } from '@nestjs/common';
import { AuthService } from './auth.service';
import { AuthController } from './auth.controller';
import { PassportModule } from '@nestjs/passport';
import { JwtModule } from '@nestjs/jwt';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { MongooseModule } from '@nestjs/mongoose';
import { UserSchema } from 'src/users/entities/user.entity';


@Module({
imports: [
PassportModule.register({ defaultStrategy: 'jwt' }),
JwtModule.registerAsync({
imports: [ConfigModule],
inject: [ConfigService],
useFactory: (config: ConfigService) => {
return {
secret: config.get<string>('JWT_SECRET'),
signOptions: {
expiresIn: config.get<string | number>('JWT_EXPIRES'),
},
};
},
}),
MongooseModule.forFeature([{ name: 'User', schema: UserSchema }]),
],
controllers: [AuthController],
providers: [AuthService],
})
export class AuthModule {}

The PassportModule.register configures the Passport module to use the JWT strategy as the authentication mechanism.

The JwtModule.registerAsync configures the JWT module using asynchronous registration process, such a the token expiration time.

The MongooseModule.forFeature() configures mongoose to us the UserSchema for the User model

These imports enable the authentication module to manage user authentication, JWT generation, and database interaction.

Next, create the AuthServices for signup and login in the src/auth/auth.service.ts directory:

import { Injectable, UnauthorizedException} from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
import { InjectModel } from '@nestjs/mongoose';
import { Model } from 'mongoose';
import { User } from 'src/users/entities/user.entity';
import { SignUpDto } from './dto/signup.dto';
import * as bcrypt from 'bcryptjs';
import { LoginDto } from './dto/login.dto';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class AuthService {
constructor(
@InjectModel(User.name) private userModel: Model<User>,
private jwtService: JwtService,
private configService: ConfigService,
) {}

async signUp(signupDto: SignUpDto) {
const { name, email, password } = signupDto;

const hashedPassword = await bcrypt.hash(password, 10);
const user = await this.userModel.create({
name,
email,
password: hashedPassword,
});

await user.save();

const token = await this.jwtService.sign(
{ id: user.id },
{
secret: this.configService.get('JWT_SECRET'),
expiresIn: this.configService.get('JWT_EXPIRES'),
},
);
return { token };
}

async login(loginDto: LoginDto) {
const { email, password } = loginDto;
const user = await this.userModel.findOne({
email,
});

if (!user) throw new UnauthorizedException('invalid email or
password');
const passwordMatch = await bcrypt.compare(password,
user.password);
if (!passwordMatch)
throw new UnauthorizedException('invalid email or password');
const token = await this.jwtService.sign(
{ id: user.id },
{
secret: this.configService.get('JWT_SECRET'),
},
);
return { token };
}
}

In the AuthService, the signUp method facilitates user registration by:

• Destructuring the SignupDto object to extract user credentials.
• Hashing the password using bcrypt for secure storage.
• Creating a new user document in the database via the userModel.
• Saving the user document to the database.
• Generating a JWT token using jwtService upon successful registration.
• Returning the JWT token to the client.

The login method authenticates users by:

• Destructuring the LoginDto object to verify user credentials.
• Comparing the input password with the stored hash to ensure a match.
• Throwing an UnauthorizedException error if the passwords do not match.
• Utilizing the jwtService to sign the user and generate a JWT token upon successful authentication.
• Returning the JWT token to the client.

Update the AuthController for signup and login in the src/auth/auth.controller.ts directory:

import { Controller, Post, Body } from '@nestjs/common';
import { AuthService } from './auth.service';
import { SignUpDto } from './dto/signup.dto';
import { LoginDto } from './dto/login.dto';

@Controller('auth')
export class AuthController {
constructor(private readonly authService: AuthService) {}

@Post('signup')
signUp(@Body() signupDto: SignUpDto) {
return this.authService.signUp(signupDto);
}

@Post('login')
signin(@Body() loginDto: LoginDto) {
return this.authService.login(loginDto);
}
}

With these steps, you’ve implemented a basic user login and signup in your application. In the next sections, we’ll test the login and signup routes.

Testing in Postman

Now that we've set up our endpoints, it's time to put them to the test. For this example, I'll be using Postman as my API client, but feel free to use any tool or client that suits your needs. Let's see our API in action!

How to Create a User With the /signup Endpoint:

After sending a POST request to the /signup endpoint using Postman, we received a response containing the accessToken. You can verify that a new user has been successfully created by checking the database.

Login as an existing user with the /login endpoint:

Conclusion

Congratulations, you've successfully implemented comprehensive authentication using NestJS, Mongoose, and Passport. We designed a secure signup and login process, and generated JSON Web Tokens (JWTs).

To further improve and expand your knowledge on authentication, look into authorization, protecting routes with authentication middleware, and implementing email verification and password reset functionality.

This foundation provides a solid starting point for building a robust and scalable authentication system. This project was a pleasure to work on, and I hope you found it equally enjoyable.

For your convenience, the project repository is available on Github.

Please don't hesitate to connect with me on Twitter at @Adedot1Abimbola. I'd love to hear from you

As developers, we are tasked with safeguarding these sensitive bits of info, and it's important to implement strong secure measures in our applications.

Now, there are many authentication mechanisms available for securing data, like OAuth, OpenID Connect, and JSON Web Tokens (JWTs).

In this article, I'll show you how to use JWTs when securing information in APIs by integrating JWT-based authentication in a Flask application.

Here's what this article will cover:

• What is a JSON Web Token?
• How Do JWTs Work?
• How to Use JSON Web Tokens to Authenticate Flask Applications
• Install dependencies
• Create a database and user model
• Configure the application for JWT authentication
• Create protected routes
• Create a Login Function
• Conclusion

Prerequisites

To follow along with this tutorial you will need:

• An understanding of HTTP Methods
• An understanding of how to create APIs in Flask
• VS Code (or other similar) editor
• A terminal

What is a JSON Web Token?

JSON Web Tokens, or JWTs, are an authentication mechanism used to securely transmit information between a client and a server in JSON format.

This information can be verified and trusted because it is digitally signed with the HMAC algorithm or a public/private key pair using RSA or ECDSA.

The tokens are encoded into three parts, each divided by a period, like this:

Header.Payload.Signature

• Header: This defines the type of token (JWT) and the signing algorithm used.
• Payload: This carries user-specific data like user ID, username, roles, and any additional claims you want to include. This payload is encoded in Base64 for maximum security.
• Signature: This is a hashed combination of the header, the payload, and the server's secret key. It ensures the token's integrity and that any modifications to the token will be detected.

How Do JWTs Work?

To understand how JWTs work, you need to know what the tokens are meant to do. JWTs are not created to hide data but to ensure that the data being sent is authenticated. This is why the JWT is signed and encoded, not encrypted.

A JWT acts as a stateless means of transmitting data from a client to a server. This means that it doesn't store any session object in the browser, so the browser doesn't maintain a session state between requests.

Instead, JWTs use a token that is sent in a request header each time a request is made. This token confirms that the token sent is authenticated and is allowed access to make that request.

Let's look at how this happens:

1. A user attempts to log in and sends a username and password to be verified by the server.
2. The verification function carries out a check to see if there's a match in the database.
3. A JWT is then generated by the server once the user is successfully authenticated (logged in) using their information (payload), such as user ID or username, and signs it using a secret key.
4. The generated JWT is sent along as a bearer token with every request header to check if the user is authenticated to make that request.

How to Use JSON Web Tokens to Authenticate Flask Applications

To demonstrate how you can implement JWT authentication in Flask, we'll create a simple application that uses JWT for handling login functions and accessing protected routes.

1. Install the dependencies

Run this command to install the dependencies we'll need

pip install flask flask-bcrypt Flask-JWT-Extended

Next, make sure you import the dependencies and initialize your Flask application with this code:

from flask import Flask, jsonify, session, request, redirect, url_for
from flask_jwt_extended import JWTManager, create_access_token, jwt_required, get_jwt_identity, get_jwt


app = Flask(__name__)

////WRITE MAIN CODE HERE


if __name__ == "__main__":
    with app.app_context():
        app.run(debug=True)

2. Create a database and User Model

To do this, we'll use SQL-Alchemy, which is a Python SQL toolkit that makes it less complex to use SQL in Python scripts.

To set up SQL Alchemy in your application, follow these steps:

First, open your terminal or command prompt and enter the following command:

pip install sqlalchemy

This command installs SQLAlchemy in your Python environment, making it available in your project directory.

Next, configure your application to make use of your preferred Database Management System (DBMS). This tutorial will use the SQlite3 DBMS as it doesn't require a separate server:

app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///site.db'

This code snippet instructs Flask-SQLAlchemy to create and use the site.db file in your project directory as the SQLite database for the application.

Then initialize the database in your application:

db = SQLAlchemy(app)

This instance of the database acts as a bridge between the application and the database.

Now create the User Model where we'll store the user's details in this tutorial:

class User(db.Model, UserMixin):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(20), unique=True, nullable=False)
    password = db.Column(db.String(80), nullable=False)
    is_active = db.Column(db.Boolean(), default=True)
    cart = db.Column(JSON, nullable=True, default=list)  # Make cart nullable

    # Define the relationship between User and CartProducts
    cart_products = relationship('CartProducts', backref="user", lazy="dynamic")
    # Define the relationship between User and Wishlists
    wishlists = db.relationship('Wishlists', backref='user', lazy=True)

    def __repr__(self):
        return f'<User {self.username}>'

Note: You can create other models using the same syntax to represent different data entities in your application.

3. Configure the application for JWT Authentication

To implement JWT authentication in your Flask application, import the necessary libraries and set up the appropriate configurations with this code:

from flask import Flask, jsonify, request
from flask_sqlalchemy import SQLAlchemy
from flask_jwt_extended import JWTManager, create_access_token, jwt_required

app = Flask(__name__)

# Configuration
app.config['SECRET_KEY'] = 'your_strong_secret_key'
app.config["JWT_SECRET_KEY"] = 'your_jwt_secret_key'
app.config['JWT_TOKEN_LOCATION'] = ['headers']

# Database Initialization
db = SQLAlchemy(app)

# JWT Initialization
jwt = JWTManager(app)

# Rest of the application code (routes, etc.)

This code snippet imports the following components needed for our application:

• app.config['SECRET_KEY'] sets the Flask application's secret key which is used to securely sign session cookies and other security-related needs.
• app.config['JWT_SECRET_KEY'] sets the secret key used to encode and decode JWTs in for Flask-JWT operations.
• app.config['JWT_TOKEN_LOCATION'] specifies where the application should look for the JWT. Here it's set to look in the HTTP headers.

Once we've set this up, we can create the endpoints and routes that we intend to protect.

4. Create protected routes

Protected routes are the pages that we intend to keep hidden from unauthorized users.

For example, let's assume we are trying to get into a venue that's exclusive to members of a society. But a guard is securing the venue from "unauthorized users" like us. In this situation, we are the application's users, the venue is the URL we are protecting, and the guard protecting the venue is a @jwt_required decorator.

The @jwt_required decorator is used to protect specific routes that require authentication. This decorator will confirm that there's a JWT access token in the request headers before allowing access to the page:

@app.route('/get_name', methods=['GET'])
@jwt_required()
def get_name():
    # Extract the user ID from the JWT
    user_id = get_jwt_identity()
    user = User.query.filter_by(id=user_id).first()

    # Check if user exists
    if user:
        return jsonify({'message': 'User found', 'name': user.name})
    else:
        return jsonify({'message': 'User not found'}), 404

In this code snippet, we created a function that returns the name of the user after authentication. If the token is missing, invalid, or expired, the request will be denied, and typically, the server will return an HTTP 401 Unauthorized status.

5. Create a Login Page

In this endpoint, we'll create a function that accepts username and password credentials from the client request (for example, form data) and compares the credentials gotten from the user with the user data in the database. If there's a match, a JWT access token will be generated containing the user's information.

@app.route('/login', methods=['POST'])
def login():
    data = request.get_json()
    username = data['username']
    password = data['password']
    print('Received data:', username , password)

    user = User.query.filter_by(username=username).first()

    if user and bcrypt.check_password_hash(user.password, password):
        access_token = create_access_token(identity=user.id)
        return jsonify({'message': 'Login Success', 'access_token': access_token})
    else:
        return jsonify({'message': 'Login Failed'}), 401

In this example, the function checks the user's credentials against the database using bcrypt for secure password verification when a POST request is received. If the credentials are valid, the server generates a JWT for the user, allowing them to access protected routes.

Here's an example of a React form sending a POST request to the login endpoint:

import React from "react";
import axios from "axios";
import { useState } from "react";
import Footer from "./Footer";
// import "./Login.css";

function Login() {
  const [password, setPassword] = useState("");
  const [username, setUsername] = useState("");

  const handleLogin = async (event) => {
    event.preventDefault();
    const data = {
      username: username,
      Password: password,
    };

    try {
      const response = await axios.post("http://localhost:5000/login", {
        username,
        password,
      });
      localStorage.setItem("access_token", response.data.access_token);
      // Redirect to protected route
      alert("Login successful");
    } catch (error) {
      console.error(error);
      // Display error message to user
    }
  };

  const handleUsernameChange = (event) => {
    setUsername(event.target.value);
  };

  const handlePasswordChange = (event) => {
    setPassword(event.target.value);
  };

  return (
    <div >

          <form method="post" >
              <input
                type="text"
                id=""
                placeholder="Username"
                name="username"
                required
                value={username}
                onChange={handleUsernameChange}
              />
              <input
                type="text"
                id=""
                placeholder="Your email"
              />
              <input
                type="password"
                required
                placeholder="Your Password"
                name="password"
                value={password}
                onChange={handlePasswordChange}
              />
          </form>
          <button type="submit" onClick={handleLogin}>
            Log In
          </button>

    </div>
  );

}

export default Login;

In this React component, we provided a login form that uses Axios to send a POST request to the login endpoint. It manages username and password inputs using React's useState hook and submits these values once the form is submitted.

If the login is successful, it stores a JWT in local Storage. This allows the client-side application to retrieve the token easily when making authenticated requests to the server.

Conclusion

In this article, we've learned how to secure APIs with JSON Web Tokens in Flask. We covered the basics of JWTs, how they work, and provided a step-by-step process for implementing this method of authentication. This included everything from installing necessary dependencies to creating user models and protecting routes.

You can build upon this foundation, such as by adding refresh tokens, integrating with third-party OAuth providers, or handling more complex user permissions.

My strengths were swimming and basketball. I went home with many gifts or, as my school's game master said, a token of appreciation.

A token is a secure form used to transmit data between two parties. The medals I got from the competitions hold a lot of value for me, and if I gave them to someone else, they would merely be trinkets.

JavaScript Object Notation (JSON) is a format used to present structured data based on JavaScript syntax. We use it to transmit data in web applications by sending the data from the server to the client's display.

JWT (JSON Web Token) is a form of transmitting a JSON object as information between parties. Let's learn more about what JWTs are and how they work.

The Importance of JWTs

JWTs are important for two main reasons:

Authorization: in our competitions, we had to present our school identification cards for verification before getting our medals.

Our school IDs acted like log in requests in applications. These requests, in apps, contain a JWT that allows users to get permission to access any resources that are accessible with that token.

Information exchange: my medals were a badge of honor and a way to get a certificate signed and stamped by our games master for legitimacy.

We use JWTs to exchange information in cases where they are signed – for example using public-private key pairs to make sure that the integrity of the information is not compromised since the payload and header are used to compute signatures.

How Do JWTs Work?

A JWT is an authorization token that is included in requests. Here's an example of what one looks like:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjczNTI3ODMzLCJpYXQiOjE2NzM1Mjc0MzAsImp0aSI6IjNkMGRkMGZiZjA5ZjRmZWU4MTZmMGQyOTQ5OWU3ZmFmIiwidXNlcl9pZCI6IjFmYTBiMGJkLWY4MmMtNDQzNy1iMmViLTMwOTYzMGZkNzQ2NiJ9.-swqFh4MCecycmodQfO8ZmfsDJ3DqoZBsdNzEWhfzhA

You can get a JWT through logging in with a username and password. In exchange the server returns an access and refresh token in the form of a JWT. The tokens access resources on the server.

The lifetimes of the access and refresh tokens vary since access tokens last for five minutes or less while the refresh tokens can last for 24 hours. But you can customize the timelines of both types of tokens.

If the access token expires, the client uses the refresh token to summon a new access token from the server. Once the refresh token expires, the user must log in again with their username and password to get a new pair of tokens.

It works this way to prevent damage that can occur when a token is compromised and to prevent unauthorized access.

Different parts of a JWT

JWTs hold information in three parts, as you can see in the following code blocks:

header.payload.signature

header = eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9F5
payload = eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNTQzODI4NDMxLCJqdGkiOiI3ZjU5OTdiNzE1MGQ0NjU3OWRjMmI0OTE2NzA5N2U3YiIsInVsztZXJfaWQiOjF9
signature = Ju70kdcaHKn1Qaz8H42zrOYk0Jx9kIciuhkTn9Xx7vhikY

The above JWT is encoded using Base64. Once decoded, the information will include something similar to the following parts:

Header

The header contains:

• type: the specification that the token is a JWT
• algorithm: the signing algorithm used to sign said token

Algorithms that are used to sign include RSA, HMAC, or SHA256. The signatures for the tokens serve two purposes – integrity and authenticity.

An example of a header with the algorithm and type is as shown below:

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

Payload

The payload contains the intended messages which are commonly known as claims and metadata, as well as any other information.

There are three types of claims:

1. Registered claims: they include exp (expiration time), iss (issuer), sub (subject) and aud (audience). They are highly recommended since they provide information on the use and condition of use of the token.
2. Public claims: these are claims that are unique to avoid collisions with other services that use JWT.
3. Private claims: these are claims that are used specifically between two parties that understand the meaning and use. Like the example of my medals, my games master and I understood the value.

Below is an example of what a payload looks like.

{
  "token_type": "access",
  "exp": 1543828431,
  "jti": "7f5997b7150d46579dc2b49167097e7b",
  "user_id": 4
}

• token_type is a label that shows what kind of token this is. Case in point, it's an access token.
• exp stands for expiration. It's the time the token will stop working – in this case the number represents date and time in Unix time.
• jti stands for JWT ID. It's a unique identifier for this specific token. The ID is used to keep track of which tokens have been used, to prevent use of the same token more than once.
• user_id: is an identifier of the user this token belongs to. In this case, the number 4 is the user identification.

Signature

The signature verifies that information is only accessed by authorized people. It is issued by the JWT backend using base64 + payload +SECRET_KEY.

The signature is verified for each request. To validate the signature, you use the SECRET_KEY. Remember the purpose of having it called SECRET_KEY is so that it is secret.

Now let's see how JWTs work in practice with an example.

Project Setup

To illustrate how JWTs work, I will use the simple JWT, which is a JSON Web Token authentication plugin for Django Rest Framework (DRF).

Prerequisites

To follow along, you should have some prior knowledge of HTML files and how to set up a Django project. You should also be familiar with what an API (Application Programming Interface) is.

You will also need to have a Django project already setup. You could name it tokenization also add an app called access.

Once your app and project are set up, you are good to go.

Simple JWT Installation

As mentioned, I will be using the simple JWT which provides JWT authentication for the Django Rest Framework (DRF).

DRF is a third-party package for Django used as a toolkit for building Web API's. It provides a seamless experience while you build, test, debug and maintain RESTful APIs using in Django.

RESTful APIs (Representational State Transfer APIs) are a type of web API that allow communication between different applications over the internet in a fast, reliable, and scalable way.

RESTful APIs are stateless. This means that requests contain information to finalize the request, and the server does not need to remember the history of previous requests.

To install simple JWT, use the command below in your terminal:

pip install djangorestframework_simplejwt

How to Set Authentication to Simple JWT

Go to your project (tokenization), and in the settings.py file, add the following code to configure the REST framework to use simple JWT for authentication:

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ],
}

The code above specifies the default authentication class to be used for all API views in the application.

DEFAULT_AUTHENTICATION_CLASSES': [ 'rest_framework_simplejwt.authentication.JWTAuthentication', ] sets the default authentication class to be JWTAuthentication from the rest_framework_simplejwt package. This means that all API views in the project will use JWT authentication by default.

How to Define Uniform Resource Locator Patterns

In your project (tokenization), create a file (if you have not created one yet) named
urls.py . Then add the following code:

from django.urls import path
from rest_framework_simplejwt import views as jwt_views

urlpatterns = [
    path('api/token/', jwt_views.TokenObtainPairView.as_view(), name='token_obtain_pair'),
    path('api/token/refresh/', jwt_views.TokenRefreshView.as_view(), name='token_refresh'),
]

The path function creates a new URL pattern and maps it to the specified view.

The URL (Uniform Resource Locator) path /api/token/ is mapped to the view jwt_views.TokenObtainPairView.as_view(). The as_view()method converts the class-based view to a function-based view used in routing. The name parameter makes it easy to refer to the URL pattern in other parts of your code.

We have now created an endpoint for obtaining JWT tokens. If a request is made to the endpoint, TokenObtainPairView, view handles the request and returns a JWT token in the response for authentication.

How to Customize the Token Timelines

To customize the timeline of the tokens, first add the rest_framework_simplejwt in your installed apps section in the project (tokenization) under the settings.py file. The purpose for adding the rest_framework_simplejwt is for configuration.

To add the timeline we want, we will first create a dictionary called SIMPLE_JWT. Then we'll create variables to hold timelines for the access and refresh token.

The code snippet below shows how to set up the timelines for the tokens:

INSTALLED_APPS = [
    #other files
    'rest_framework_simplejwt',
]

SIMPLE_JWT = {
    'ACCESS_TOKEN_LIFETIME': timedelta(minutes=5),
    'REFRESH_TOKEN_LIFETIME': timedelta(days=1),
}

Before you use the timedelta you will need to import it like this: python from datetime import timedelta.

Visual Interaction of the API

In this section, we will use the Django Rest Framework web interface to access the endpoints.

Testing tokenization

The access and refresh tokens are highlighted in red, as shown above. To get the tokens for a user, you need to input the correct password and username for an existing user.

Use a refresh token through this endpoint for an access token: /api/token/refresh/

Refresh token

A refresh token gets an access token without the user using their login credentials to extend the user's session. This provides a seamless user experience and improves security by reducing the number of times a user has to key in their credentials.

How to Add a Homepage

If you want to create a visually appealing interface, you can build a custom homepage to replace the current display of the API endpoints and error messages.

To add a homepage to your Django project, follow these steps:

1. Create a templates folder in your application (access). Then, add a index.html file inside.
2. Create a static folder in your application (access) and add a img folder inside.
3. In this case, I wanted to display an image, so I added the me.png in the img folder.
4. Add the code below to your html file:

{% load static %}
<!DOCTYPE html>
<html>
<head>
    <title>Home</title>
    <style>
        body {
            background-image: url("{% static 'img/me.png' %}");
            background-size: cover;
        }
    </style>
</head>
</html>

You will notice that we needed to add {% load static %} at the top of the file for proper styling and functioning of the site. {% load static %} serves files like stylesheets(CSS), scripts(JS), and images to your HTML templates to provide the user with a seamless experience while viewing your site.

How to Define the URL Patterns For Your Home Page

In your app's (access) urls.py file (create one if you do not have it) add this:

from django.urls import path
from django.views.generic import TemplateView

app_name='access'

urlpatterns=[
path('', TemplateView.as_view(template_name='home.html'), name='home'),

]

In your project's (tokenization) settings.py file, add the following code so that the static files are served:

# Static files settings
STATIC_ROOT = os.path.join(BASE_DIR, 'static')
STATIC_URL = '/static/'
STATICFILES_DIRS = [os.path.join(BASE_DIR, 'access/static')]

Once you run the server, your home page should be like this:

home page

Bugs and Solutions

At some point, I may have deleted the migrations file which deleted some of the data I had. This caused the following error django.db.utils.OperationalError: no such table: customUser.

I was able to solve this through running the command python manage.py migrate --run-syncdb . The command syncs tables by looking into tables not created and then creating them.

I also had an issue of using a port that was already being used by a program I had left running and forgotten about.

To close a port you should identify the process using it by running the command lsof -i :<port_number>. This will show you the user using it and PID. To stop the process use kill <PID>. Additionally, you can use sudo kill -9 -u <username> <pid> .

It's good to know that to kill the port you will need administrator permissions. Also, stopping a process can cause data loss or unusual behavior so ensure your data is backed up before doing this.

Wrapping Up

In this tutorial, you have learned how JWTs work, the structure of different tokens, how to use JWT and DRF to get tokens, how to create and serve static files in Django, and how to handle deleting migration files and kill a port.

There is so much you can learn about Django and the Django Rest Framework.

The code for this article can be found here.

May your keyboard be swift, your bugs be few, and your fun meter be off the charts as you code away!

Thanks for reading my article on how to implement tokenization using JWT and Django Rest Framework. I'm always up for a good chat about coding and tech, so give me a follow on Twitter and let's continue the conversation there.

If you've ever signed in to a site like freeCodeCamp with your Google or GitHub account, there's a good chance that you're already using a JWT.

In this article, we'll go over how JWTs are used, then dig into what JWTs are, and how they can securely transmit data through the signature and validation process.

How JWTs Are Used

JWTs are usually used to manage user sessions on a website. While they're an important part of the token based authentication process, JWTs themselves are used for authorization, not authentication.

Here's a good overview of how token based authentication works:

Source

When you sign in to a site with a username and password, or with a third party method like Google, you're proving who you are with those sensitive details or access. This process is called authentication.

Once you're signed in, the site's server sends back a JWT that allows you access to things like your settings page, shopping cart, and so on. This process is called authorization.

You send your JWT to the server with each request. When the server receives it, it generates a signature using some data from your JWT, verifies it, and if your JWT is valid, it sends back a response.

What are JWTs?

At their core, JWTs are just bits of encoded JSON data with a cryptographic signature at the end.

Here's an example of a JWT:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlF1aW5jeSBMYXJzb24iLCJpYXQiOjE1MTYyMzkwMjJ9.WcPGXClpKD7Bc1C0CCDA1060E2GGlTfamrd8-W0ghBE

Each JWT is made up of three segments, each separated by a dot (.). These three segments are the header, payload, and signature.

If you copy and paste that JWT into the JWT.io Debugger, you can see the decoded versions of those three segments.

Header Segment

The header segment of a JWT contains information about the algorithm and token type.

Here's the header segment of the example JWT token above:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

The header segment is base 64 URL encoded, and decodes to the following JSON object:

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

"alg" is the type of algorithm used in the last segment, the cryptographic signature. In this case, the HMAC SHA256 algorithm is used, though RSA is also common.

"typ" is the type of token the segmented string is, which in this case is JWT.

Payload Segment

The payload segment of a JWT contains registered claims or identifying information, usually for a user.

Here's the payload segment of the example JWT token above:

eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlF1aW5jeSBMYXJzb24iLCJpYXQiOjE1MTYyMzkwMjJ9

The payload segment is also base 64 URL encoded, and decodes to the following JSON object:

{
  "sub": "1234567890",
  "name": "Quincy Larson",
  "iat": 1516239022
}

Since JWTs are usually used as part of the authentication method for sites, the payload segment usually contains identifying information for a user. These claims fall into three categories: registered, public, and private.

Registered claims are a set of predefined claims defined here that are optional, but recommended when using JWTs.

Public claims are optional claims, usually from the IANA JSON Web Token Registry.

Private claims are optional, and are any claims that don't fall under the registered or public claims categories.

"sub" is the subject of the JWT, and is usually a unique identifying string for a user in an application, usually an email address, username, or id. Subjects are registered claims.

"name" is the full name of the user who was issued the JWT, and is a public claim.

"iat" is the "issued at" date for the token, and is a registered claim.

Signature Segment

The signature segment of a JWT contains the cryptographic signature of the token.

Here's the signature segment of the example JWT token above:

WcPGXClpKD7Bc1C0CCDA1060E2GGlTfamrd8-W0ghBE

The signature segment is made up of the base 64 URL encoded header and payload segments, a secret (usually the contents of a key in a signing algorithm), and hashed using the algorithm defined in the header segment:

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  your-256-bit-secret
)

The signature helps ensure that the data in the header and payload segments haven't been tampered with, and the JWT can be trusted.

However, it's important to note that the cryptographic signature at the end of the JWT is just for validation. It doesn't encrypt any data in the header or payload segments of the token. So you should never send sensitive information like a user's password in a JWT – everything in the header and payload can and should be public.

How to Validate JWT Signatures

The exact method for validating a signature depends on the algorithm defined in the header segment and used to generate the signature itself.

For the HS256 signing algorithm, a private key is shared between two entities, say your application's server and an authentication server. This private key is used both to generate signatures for outgoing JWTs, and to validate signatures from incoming JWTs.

When your authentication server receives an incoming JWT, it uses the incoming JWT's header and payload segments and the shared private key to generate a signature.

If the signature matches, then your application knows that the incoming JWT can be trusted.

Another popular signing algorithm is RS256, which uses public and private key pairs to validate signatures. This is similar to the system used for SSH and SSL.

If you'd like to read more about how RS256 works, check out this article:

Other Helpful Tutorials

If you'd like to learn more about JWTs and how to use them in applications, check out these tutorials:

Thanks for Reading

If you found this article on JWTs helpful, consider sharing it so more people can benefit from it.

Also, feel free to reach out on Twitter and let me know what you think.

FastAPI is a modern, fast, battle tested and light-weight web development framework written in Python. Other popular options in the space are Django, Flask and Bottle.

And since it's new, FastAPI comes with both advantages and disadvantages.

On the positive side, FastAPI implements all the modern standards, taking full advantage of the features supported by the latest Python versions. It has async support and type hinting. And it's also fast (hence the name FastAPI), unopinionated, robust, and easy to use.

On the negative side, FastAPI lacks some complex features like out of the box user management and admin panel that come baked in with Django. The community support for FastAPI is good but not as great as other frameworks that have been out there for years and have hundreds if not thousands of open-source projects for different use cases.

That was a very brief introduction to FastAPI. In this article, you'll learn how to implement JWT (JSON Web Token) authentication in FastAPI with a practical example.

Project Setup

In this example, I am going to use replit (a great web-based IDE). Alternatively, you can simply setup your FastAPI project locally by following the docs or use this replit starter template by forking it. This template has all the required dependencies already installed.

If you have the project setup on your local environment, here are the dependencies that you need to install for JWT authentication (assuming that you have a FastAPI project running):

pip install "python-jose[cryptography]" "passlib[bcrypt]" python-multipart

NOTE: In order to store users, I am going to use replit's built-in database. But you can apply similar operations if you are using any standard database like PostgreSQL, MongoDB, and so on.

If you want to see the complete implementation, I have this full video tutorial that includes everything a production ready FastAPI application might have.

Authentication with FastAPI

Authentication in general can have a lot of moving parts, from handling password hashing and assigning tokens to validating tokens on each request.

FastAPI leverages dependency injection (a software engineering design pattern) to handle authentication schemes. Here is the list of some general steps in the process:

• Password hashing
• Creating and assigning JWT tokens
• User creation
• Validating tokens on each request to ensure authentication

Password Hashing

When creating a user with a username and password, you need to hash passwords before storing them in the database. Let's see how to easily hash passwords.

Create a file named utils.py in the app directory and add the following function to hash user passwords.

from passlib.context import CryptContext

password_context = CryptContext(schemes=["bcrypt"], deprecated="auto")


def get_hashed_password(password: str) -> str:
    return password_context.hash(password)


def verify_password(password: str, hashed_pass: str) -> bool:
    return password_context.verify(password, hashed_pass)

We're using passlib to create the configuration context for password hashing. Here we are configuring it to use bcrypt .

The get_hashed_password function takes a plain password and returns the hash for it that can be safely stored in the database. The verify_password function takes the plain and hashed passwords and return a boolean representing whether the passwords match or not.

How to Generate JWT Tokens

In this section, we will write two helper functions to generate access and refresh tokens with a particular payload. Later we can use these functions to generate tokens for a particular user by passing the user-related payload.

Inside the app/utils.py file that you created earlier, add the following import statements:

import os
from datetime import datetime, timedelta
from typing import Union, Any
from jose import jwt

Add the following constants that will be passed when creating JWTs:

ACCESS_TOKEN_EXPIRE_MINUTES = 30  # 30 minutes
REFRESH_TOKEN_EXPIRE_MINUTES = 60 * 24 * 7 # 7 days
ALGORITHM = "HS256"
JWT_SECRET_KEY = os.environ['JWT_SECRET_KEY']   # should be kept secret
JWT_REFRESH_SECRET_KEY = os.environ['JWT_REFRESH_SECRET_KEY']    # should be kept secret

JWT_SECRET_KEY and JWT_REFRESH_SECRET_KEY can be any strings, but make sure to keep them secret and set them as environment variables.

If you are following along on replit.com, you can set these environment variables from the Secrets tab on the left menu bar.

Add the following functions at the end of the app/utils.py file:

def create_access_token(subject: Union[str, Any], expires_delta: int = None) -> str:
    if expires_delta is not None:
        expires_delta = datetime.utcnow() + expires_delta
    else:
        expires_delta = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)

    to_encode = {"exp": expires_delta, "sub": str(subject)}
    encoded_jwt = jwt.encode(to_encode, JWT_SECRET_KEY, ALGORITHM)
    return encoded_jwt

def create_refresh_token(subject: Union[str, Any], expires_delta: int = None) -> str:
    if expires_delta is not None:
        expires_delta = datetime.utcnow() + expires_delta
    else:
        expires_delta = datetime.utcnow() + timedelta(minutes=REFRESH_TOKEN_EXPIRE_MINUTES)

    to_encode = {"exp": expires_delta, "sub": str(subject)}
    encoded_jwt = jwt.encode(to_encode, JWT_REFRESH_SECRET_KEY, ALGORITHM)
    return encoded_jwt

The only difference between these two functions is that the expiration time for refresh tokens is longer than for access tokens.

The functions simply take the payload to include inside the JWT, which can be anything. Usually you would want to store information like USER_ID here, but this can be anything from strings to objects/dictionaries. The functions return tokens as strings.

In the end your app/utils.py file should look something like this:

from passlib.context import CryptContext
import os
from datetime import datetime, timedelta
from typing import Union, Any
from jose import jwt

ACCESS_TOKEN_EXPIRE_MINUTES = 30  # 30 minutes
REFRESH_TOKEN_EXPIRE_MINUTES = 60 * 24 * 7 # 7 days
ALGORITHM = "HS256"
JWT_SECRET_KEY = os.environ['JWT_SECRET_KEY']     # should be kept secret
JWT_REFRESH_SECRET_KEY = os.environ['JWT_REFRESH_SECRET_KEY']      # should be kept secret

password_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

def get_hashed_password(password: str) -> str:
    return password_context.hash(password)


def verify_password(password: str, hashed_pass: str) -> bool:
    return password_context.verify(password, hashed_pass)


def create_access_token(subject: Union[str, Any], expires_delta: int = None) -> str:
    if expires_delta is not None:
        expires_delta = datetime.utcnow() + expires_delta
    else:
        expires_delta = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)

    to_encode = {"exp": expires_delta, "sub": str(subject)}
    encoded_jwt = jwt.encode(to_encode, JWT_SECRET_KEY, ALGORITHM)
    return encoded_jwt

def create_refresh_token(subject: Union[str, Any], expires_delta: int = None) -> str:
    if expires_delta is not None:
        expires_delta = datetime.utcnow() + expires_delta
    else:
        expires_delta = datetime.utcnow() + timedelta(minutes=REFRESH_TOKEN_EXPIRE_MINUTES)

    to_encode = {"exp": expires_delta, "sub": str(subject)}
    encoded_jwt = jwt.encode(to_encode, JWT_REFRESH_SECRET_KEY, ALGORITHM)
    return encoded_jwt

How to Handle User Signups

Inside the app/app.py file, create another endpoint for handling user signups. The endpoint should take the username/email and password as data. It then checks to make sure another account with the email/username does not exist. Then it creates the user and saves it to the database.

In app/app.py, add the following handler function:

from fastapi import FastAPI, status, HTTPException
from fastapi.responses import RedirectResponse
from app.schemas import UserOut, UserAuth
from replit import db
from app.utils import get_hashed_password
from uuid import uuid4

@app.post('/signup', summary="Create new user", response_model=UserOut)
async def create_user(data: UserAuth):
    # querying database to check if user already exist
    user = db.get(data.email, None)
    if user is not None:
            raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="User with this email already exist"
        )
    user = {
        'email': data.email,
        'password': get_hashed_password(data.password),
        'id': str(uuid4())
    }
    db[data.email] = user    # saving user to database
    return user

How to Handle Logins

FastAPI has a standard way of handling logins to comply with OpenAPI standards. This automatically adds authentication in the swagger docs without any extra configurations.

Add the following handler function for user logins and assign each user access and refresh tokens. Don't forget to include imports.

from fastapi import FastAPI, status, HTTPException, Depends
from fastapi.security import OAuth2PasswordRequestForm
from fastapi.responses import RedirectResponse
from app.schemas import UserOut, UserAuth, TokenSchema
from replit import db
from app.utils import (
    get_hashed_password,
    create_access_token,
    create_refresh_token,
    verify_password
)
from uuid import uuid4

@app.post('/login', summary="Create access and refresh tokens for user", response_model=TokenSchema)
async def login(form_data: OAuth2PasswordRequestForm = Depends()):
    user = db.get(form_data.username, None)
    if user is None:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="Incorrect email or password"
        )

    hashed_pass = user['password']
    if not verify_password(form_data.password, hashed_pass):
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="Incorrect email or password"
        )

    return {
        "access_token": create_access_token(user['email']),
        "refresh_token": create_refresh_token(user['email']),
    }

This endpoint is a bit different from the other post endpoints where you defined the schema for filtering incoming data.

For login endpoints, we use OAuth2PasswordRequestForm as a dependency. This will make sure to extract data from the request and pass is as a form_data argument to the the login handler function. python-multipart is used to extract form data. So make sure that you have installed it.

The endpoint will reflect in the swagger docs with inputs for username and password.

On successful response, you will get tokens as shown here:

How to Add Protected Routes

Now since we have added support for login and signup, we can add protected endpoints. In FastAPI, protected endpoints are handled using dependency injection and FastAPI can infer this from the OpenAPI schema and reflect it in the swagger docs.

Let's see the power of dependency injection. At this point, there is no way we can authenticate from the docs. This is because currently we don't have any protected endpoint, so the OpenAPI schema does not have enough information about the login strategy we are using.

No button in swagger docs to login.

Let's create our custom dependency. It's nothing but a function that is run before the actual handler function to get arguments passed to the hander function. Let's see with a practical example.

Create another file app/deps.py and add include the following function in it:

from typing import Union, Any
from datetime import datetime
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from .utils import (
    ALGORITHM,
    JWT_SECRET_KEY
)

from jose import jwt
from pydantic import ValidationError
from app.schemas import TokenPayload, SystemUser
from replit import db

reuseable_oauth = OAuth2PasswordBearer(
    tokenUrl="/login",
    scheme_name="JWT"
)


async def get_current_user(token: str = Depends(reuseable_oauth)) -> SystemUser:
    try:
        payload = jwt.decode(
            token, JWT_SECRET_KEY, algorithms=[ALGORITHM]
        )
        token_data = TokenPayload(**payload)

        if datetime.fromtimestamp(token_data.exp) < datetime.now():
            raise HTTPException(
                status_code = status.HTTP_401_UNAUTHORIZED,
                detail="Token expired",
                headers={"WWW-Authenticate": "Bearer"},
            )
    except(jwt.JWTError, ValidationError):
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Could not validate credentials",
            headers={"WWW-Authenticate": "Bearer"},
        )

    user: Union[dict[str, Any], None] = db.get(token_data.sub, None)


    if user is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Could not find user",
        )

    return SystemUser(**user)

Here we are defining the get_current_user function as a dependency which in turn takes an instance of OAuth2PasswordBearer as a dependency.

reuseable_oauth = OAuth2PasswordBearer(
    tokenUrl="/login",
    scheme_name="JWT"
)

OAuth2PasswordBearer takes two required parameters. tokenUrl is the URL in your application that handles user login and return tokens. scheme_name set to JWT will allow the frontend swagger docs to call tokenUrl from the frontend and save tokens in memory. Then each subsequent request to the protected endpoints will have the token sent as Authorization headers so OAuth2PasswordBearer can parse it.

Now let's add a protected endpoint that returns user account information as the response. For this, a user has to be logged in and the endpoint will respond with information for the currently logged-in user.

In app/app.py create another handler function. Make sure to include imports as well.

from app.deps import get_current_user

@app.get('/me', summary='Get details of currently logged in user', response_model=UserOut)
async def get_me(user: User = Depends(get_current_user)):
    return user

As soon as you add this endpoint, you will be able to see the Authorize button in the swagger docs and a 🔒 icon in front of the protected endpoint /me.

This is power of dependency injection and FastAPI's ability to generate an automatic OpenAPI schema.

Clicking the Authorize button will open the authorization form with the required fields for login. On a successful response, tokens will be saved and sent to subsequent request in the headers.

Swagger integrated login form

successfully logged in

At this point, you can access all the protected endpoints. To make an endpoint protected, you just need to add the get_current_user function as a dependency. That's all you need to do!

Conclusion

If you followed along, you should have a working FastAPI application with JWT authentication. If not, you can always run this repl and play around with it or visit this deployed version. You can find the GitHub code for this project here.

If you found this article helpful, give me a follow at twitter @abdadeel_. And don't forget that you can always watch this video for detail explanation with a practical example.

Thanks ;)

In the past month, I had a chance to implement JWT auth for a side project. I have previously worked with JWT in Ruby on Rails, but this was my first time in Spring.

In this post, I will try to explain what I have learned and applied in my project to share my experience and hopefully help some people.

We will start by taking a quick look at the theory behind JWT and how it works. Then we will look at how to implement it in a Spring Boot application.

JWT Basics

JWT, or JSON Web Tokens (RFC 7519), is a standard that is mostly used for securing REST APIs. Despite being a relatively new technology, it is gaining rapid popularity.

In the JWT auth process, the front end (client) firstly sends some credentials to authenticate itself (username and password in our case, since we're working on a web application).

The server (the Spring app in our case) then checks those credentials, and if they are valid, it generates a JWT and returns it.

After this step client has to provide this token in the request’s Authorization header in the “Bearer TOKEN” form. The back end will check the validity of this token and authorize or reject requests. The token may also store user roles and authorize the requests based on the given authorities.

Implementation

Now let’s see how we can implement the JWT login and save mechanism in a real Spring application.

Dependencies

You can see the list of Maven dependencies that our example code uses below. Note that the core dependencies like Spring Boot and Hibernate are not included in this screenshot.

Saving Users

We will start by creating controllers to save users securely and authenticate them based on username and password.

We have a model entity called User. It is a simple entity class that maps to the USER table. You can use whatever properties you need depending on your application.

We also have a simple UserRepository class to save users. We need to override the findByUsername method since we will use it in authentication.

public interface UserRepository extends JpaRepository<User, String>{ 
    User findByUsername(String username); 
}

We should never store plaintext passwords in the database because many users tend to use the same password for multiple sites.

There are many different hashing algorithms, but the most commonly used one is BCrypt and it is a recommended method of secure hashing. You can check out this article for more information on the topic.

To hash the password, we will define a BCrypt bean in @SpringBootApplication and annotate the main class as follows:

@Bean public BCryptPasswordEncoder bCryptPasswordEncoder() {
    return new BCryptPasswordEncoder(); 
}

We will call the methods on this bean when we need to hash a password.

We also need a UserController to save users. We create the controller, annotate it with @RestController, and define the corresponding mapping.

In our application, we save the user based on a DTO object that is passed from the front end. You can also pass a User object in @RequestBody.

After we pass the DTO object, we encrypt the password field using the BCrypt bean we created earlier. You could also do this in the controller, but it is a better practice to put this logic in the service class.

@Transactional(rollbackFor = Exception.class) 
public String saveDto(UserDto userDto) { 
    userDto.setPassword(bCryptPasswordEncoder
           .encode(userDto.getPassword())); 
    return save(new User(userDto)).getId(); 
}

Authentication Filter

We need authentication to make sure that the user is really who they claim to be. We will be using the classic username/password pair to accomplish this.

Here are the steps to implement authentication:

1. Create our Authentication Filter that extends UsernamePasswordAuthenticationFilter
2. Create a security configuration class that extends WebSecurityConfigurerAdapter and apply the filter

Here is the code for our Authentication Filter – as you might know, filters are the backbone of Spring Security.

Let’s go over this code step by step.

This class extends UsernamePasswordAuthenticationFilter which is the default class for password authentication in Spring Security. We extend it to define our custom authentication logic.

We make a call to the setFilterProcessesUrl method in our constructor. This method sets the default login URL to the provided parameter.

If you remove this line, Spring Security creates the “/login” endpoint by default. It defines the login endpoint for us, which is why we will not define a login endpoint in our controller explicitly.

After this line our login endpoint will be /api/services/controller/user/login. You can use this function to stay consistent with your endpoints.

We override the attemptAuthentication and successfulAuthentication methods of the UsernameAuthenticationFilter class.

The attemptAuthentication function runs when the user tries to log in to our application. It reads the credentials, creates a user POJO from them, and then checks the credentials to authenticate.

We pass the username, password, and an empty list. The empty list represents the authorities (roles), and we leave it as is since we do not have any roles in our application yet.

If the authentication is successful, the successfulAuthentication method runs. The parameters of this method are passed by Spring Security behind the scenes.

The attemptAuthentication method returns an Authentication object that contains the authorities we passed while attempting.

We want to return a token to user after authentication is successful, so we create the token using username, secret, and expiration date. We need to define the SECRET and EXPIRATION_DATE now.

We create a class to be a container for our constants. You can set the secret to whatever you want, but the best practice is making the secret key as long as your hash. We use the HS256 algorithm in this example, so our secret key is 256 bits/32 chars.

The expiration time is set to 15 minutes, because it is the best practice against secret key brute-forcing attacks. The time is in milliseconds.

We have prepared our Authentication filter, but it is not active yet. We also need an Authorization filter, and then we will apply them both through a configuration class.

This filter will check the existence and validity of the access token on the Authorization header. We will specify which endpoints will be subject to this filter in our configuration class.

Authorization Filter

The doFilterInternal method intercepts the requests then checks the Authorization header. If the header is not present or doesn’t start with “BEARER”, it proceeds to the filter chain.

If the header is present, the getAuthentication method is invoked. getAuthentication verifies the JWT, and if the token is valid, it returns an access token which Spring will use internally.

This new token is then saved to SecurityContext. You can also pass in Authorities to this token if you need for role-based authorization.

Our filters are ready, and now we need to put them into action with the help of a configuration class.

Configuration

We annotate this class with @EnableWebSecurity and extend WebSecurityConfigureAdapter to implement our custom security logic.

We autowire the BCrypt bean that we defined earlier. We also autowire the UserDetailsService to find the user’s account.

The most important method is the one which accepts an HttpSecurity object. Here we specify the secure endpoints and filters that we want to apply. We configure CORS, and then we permit all post requests to our sign up URL that we defined in the constants class.

You can add other ant matchers to filter based on URL patterns and roles, and you can check this StackOverflow question for examples regarding that. The other method configures the AuthenticationManager to use our encoder object as its password encoder while checking the credentials.

Testing

Let’s send a few requests to test if it works properly.

Here we send a GET request to access a protected resource. Our server responds with a 403 code. This is the expected behavior because we haven’t provided a token in the header. Now let’s create a user:

To create a user, we send a post request with our User DTO data. We will use this user to login and get an access token.

Great! We got the token. After this point, we will use this token to access protected resources.

We provide the token in the Authorization header and we are now allowed access to our protected endpoint.

Conclusion

In this tutorial I have walked you through the steps I took when implementing JWT authorization and password authentication in Spring. We also learned how to save a user securely.

Thank you for reading – I hope it was helpful to you. If you are interested in reading more content like this, feel free to subscribe to my blog at https://erinc.io. :)