🛠️ Implementing JWT Auth

The Pieces You Need

A JWT auth system is really three responsibilities working together. Credentials must be verified without ever storing a plaintext password — that's bcrypt. Tokens must be issued and later checked — that's jsonwebtoken. And routes must refuse anyone without a valid token — that's middleware. Everything else is plumbing.

Project Setup & Secrets

Start a project and install the essentials. We'll use the modern bcrypt and current jsonwebtoken.

npm init -y
npm install express bcrypt jsonwebtoken dotenv

The signing secret is the single most sensitive value in the whole system — anyone who has it can forge tokens. Keep it out of your code and out of git, in a .env file:

# .env  (add this file to .gitignore!)
JWT_SECRET=replace_me_with_a_long_random_string_at_least_32_bytes
JWT_ACCESS_EXPIRATION=15m
PORT=3000

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Hashing Passwords with bcrypt

Rule zero of authentication: never store a password you could read back. If your database leaks and it holds plaintext passwords, every account is compromised instantly — and because people reuse passwords, so are their accounts elsewhere. Instead you store a one-way hash. bcrypt is purpose-built for this: it's deliberately slow (to resist brute force) and it salts every hash (so identical passwords don't produce identical hashes).

const bcrypt = require('bcrypt');

// When a user registers: hash before saving.
// The number is the "cost factor" — higher is slower and safer. 10-12 is typical.
async function hashPassword(plain) {
  const saltRounds = 12;
  return bcrypt.hash(plain, saltRounds); // returns e.g. "$2b$12$Xa...."
}

// When a user logs in: compare the attempt to the stored hash.
async function checkPassword(plain, storedHash) {
  return bcrypt.compare(plain, storedHash); // resolves true or false
}

Notice you never decrypt anything. bcrypt.compare hashes the incoming attempt with the same salt (which is embedded in the stored hash) and checks whether the results match. For this lesson we'll use a plain in-memory array as our "database" so you can run it with zero setup:

// A stand-in for a real database.
const users = []; // each: { id, email, passwordHash, role }
let nextId = 1;

async function registerUser(email, password, role = 'user') {
  const passwordHash = await hashPassword(password);
  const user = { id: nextId++, email, passwordHash, role };
  users.push(user);
  return user;
}

Signing Tokens

Once a user's password checks out, you issue a token. Keep the payload lean — an id and a role are plenty. Let the library manage exp for you via expiresIn; it also stamps iat automatically.

const jwt = require('jsonwebtoken');

function signAccessToken(user) {
  const payload = {
    sub: user.id,     // subject: who the token is about
    role: user.role,  // a private claim your app understands
  };

  return jwt.sign(payload, process.env.JWT_SECRET, {
    expiresIn: process.env.JWT_ACCESS_EXPIRATION || '15m',
    // Pin the algorithm so it can't be downgraded to "none":
    algorithm: 'HS256',
  });
}

The Login Route

Now assemble register and login into real Express routes. Two details matter for security: return a generic "invalid credentials" message (don't reveal whether the email exists), and always compare with bcrypt even conceptually to avoid leaking timing.

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

// POST /register — create an account
app.post('/register', async (req, res) => {
  const { email, password } = req.body;

  if (!email || !password) {
    return res.status(400).json({ message: 'Email and password are required' });
  }
  if (users.some(u => u.email === email)) {
    return res.status(409).json({ message: 'Email already registered' });
  }

  const user = await registerUser(email, password);
  const token = signAccessToken(user);
  res.status(201).json({ token });
});

// POST /login — verify credentials and issue a token
app.post('/login', async (req, res) => {
  const { email, password } = req.body;
  const user = users.find(u => u.email === email);

  // Same response whether the email is unknown or the password is wrong:
  if (!user || !(await checkPassword(password, user.passwordHash))) {
    return res.status(401).json({ message: 'Invalid credentials' });
  }

  const token = signAccessToken(user);
  res.json({ token });
});

POST /register  { "email": "ada@example.com", "password": "s3cret!" }
→ 201  { "token": "eyJhbGciOiJIUzI1NiI..." }

POST /login     { "email": "ada@example.com", "password": "wrong" }
→ 401  { "message": "Invalid credentials" }

Auth Middleware

Middleware is a function that runs before your route handler. The auth middleware's job: pull the token out of the Authorization header, verify it, and either attach the decoded user to req and call next(), or reject the request. Because jwt.verify throws on any problem, wrap it in try/catch and translate the error type into a helpful message.

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

function requireAuth(req, res, next) {
  const header = req.headers.authorization;

  // Expect exactly: "Bearer <token>"
  if (!header || !header.startsWith('Bearer ')) {
    return res.status(401).json({ message: 'No token provided' });
  }

  const token = header.split(' ')[1];

  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET, {
      algorithms: ['HS256'], // allow-list — never trust the token's own header
    });
    req.user = decoded; // { sub, role, iat, exp }
    next();
  } catch (err) {
    const message =
      err.name === 'TokenExpiredError' ? 'Token has expired' : 'Invalid token';
    return res.status(401).json({ message });
  }
}

module.exports = { requireAuth };

Protecting Routes & Roles

Authentication answers "who are you?"; authorization answers "are you allowed?" Stack a small role-checking middleware after requireAuth to gate admin-only routes.

const { requireAuth } = require('./middleware/auth');

// Authorization helper: use AFTER requireAuth so req.user exists.
function requireRole(role) {
  return (req, res, next) => {
    if (req.user.role !== role) {
      return res.status(403).json({ message: 'Access denied' });
    }
    next();
  };
}

// Any logged-in user:
app.get('/profile', requireAuth, (req, res) => {
  const user = users.find(u => u.id === req.user.sub);
  res.json({ id: user.id, email: user.email, role: user.role });
});

// Admins only — two middlewares run in order:
app.get('/admin', requireAuth, requireRole('admin'), (req, res) => {
  res.json({ message: 'Welcome to the admin panel' });
});

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

Practice & Quiz

app.get('/me', requireAuth, (req, res) => {
  const user = users.find(u => u.id === req.user.sub);
  if (!user) return res.status(404).json({ message: 'User not found' });

  const nowSeconds = Math.floor(Date.now() / 1000);
  const secondsLeft = req.user.exp - nowSeconds;

  res.json({
    email: user.email,
    role: user.role,
    secondsUntilExpiry: secondsLeft,
  });
});

function badAuth(req, res, next) {
  const token = req.headers.authorization.split(' ')[1];
  const decoded = jwt.decode(token); // read the claims
  req.user = decoded;
  next();
}

function goodAuth(req, res, next) {
  const header = req.headers.authorization;
  if (!header || !header.startsWith('Bearer ')) {
    return res.status(401).json({ message: 'No token provided' });
  }
  try {
    req.user = jwt.verify(header.split(' ')[1], process.env.JWT_SECRET, {
      algorithms: ['HS256'],
    });
    next();
  } catch {
    return res.status(401).json({ message: 'Invalid token' });
  }
}

Best Practices & Pitfalls

✅ Do

• Hash with bcrypt at a cost of 10–12; store only the hash
• Keep the secret in process.env, generated from a CSPRNG, and out of git
• Pass an explicit algorithms allow-list to both sign and verify
• Give access tokens a short expiresIn (15 minutes is a common default)
• Return generic "invalid credentials" so you don't leak which emails exist

❌ Don't

• Don't store plaintext passwords or log them anywhere
• Don't use jwt.decode to protect a route
• Don't hard-code the secret or commit your .env
• Don't put sensitive data in the payload — it's readable by anyone
• Don't call .split on the header before checking it exists

Summary

📚 Additional Resources

• jsonwebtoken — full API for sign, verify, and options
• bcrypt on npm — hashing API and cost-factor guidance
• OWASP — Password Storage Cheat Sheet
• MDN — the Authorization header

🚀 What's Next?

Your API issues and checks tokens, but a 15-minute access token would log users out constantly. The next lesson, Token Refresh Strategies, adds long-lived refresh tokens, rotation, and revocation so sessions stay smooth and secure.