Understanding Token‑Based Authentication: Concepts, Implementation, and Best Practices

npm install express jsonwebtoken dotenv body-parser

require('dotenv').config();
const express = require('express');
const jwt = require('jsonwebtoken');
const bodyParser = require('body-parser');

const app = express();
app.use(bodyParser.json());

const USERS = [
  { id: 1, username: 'alice', password: 'password123', role: 'admin' },
  { id: 2, username: 'bob', password: 'secret', role: 'user' },
];

// Helper to generate JWTs
function generateAccessToken(user) {
  const payload = {
    sub: user.id,
    name: user.username,
    role: user.role,
  };
  return jwt.sign(payload, process.env.ACCESS_TOKEN_SECRET, {
    expiresIn: '15m',
    audience: 'myapi',
    issuer: 'auth.mycompany.com',
  });
}

// Login endpoint
app.post('/login', (req, res) => {
  const { username, password } = req.body;
  const user = USERS.find(
    (u) => u.username === username && u.password === password
  );

  if (!user) return res.status(401).json({ error: 'Invalid credentials' });

  const accessToken = generateAccessToken(user);
  const refreshToken = jwt.sign(
    { sub: user.id },
    process.env.REFRESH_TOKEN_SECRET,
    { expiresIn: '7d' }
  );

  // In production, store refreshToken in DB or Redis for revocation
  res.json({ accessToken, refreshToken });
});

// Middleware to protect routes
function authenticateToken(req, res, next) {
  const authHeader = req.headers['authorization'];
  const token = authHeader && authHeader.split(' ')[1];
  if (!token) return res.sendStatus(401);

  jwt.verify(
    token,
    process.env.ACCESS_TOKEN_SECRET,
    { audience: 'myapi', issuer: 'auth.mycompany.com' },
    (err, payload) => {
      if (err) return res.sendStatus(403);
      req.user = payload; // Attach payload to request
      next();
    }
  );
}

// Protected route example
app.get('/profile', authenticateToken, (req, res) => {
  res.json({ message: `Hello ${req.user.name}`, role: req.user.role });
});

// Refresh endpoint
app.post('/refresh', (req, res) => {
  const { refreshToken } = req.body;
  if (!refreshToken) return res.sendStatus(401);

  jwt.verify(refreshToken, process.env.REFRESH_TOKEN_SECRET, (err, payload) => {
    if (err) return res.sendStatus(403);
    const user = USERS.find((u) => u.id === payload.sub);
    if (!user) return res.sendStatus(403);
    const newAccessToken = generateAccessToken(user);
    res.json({ accessToken: newAccessToken });
  });
});

app.listen(3000, () => console.log('Server running on :3000'));

pip install Flask PyJWT python-dotenv

import os
import datetime
from flask import Flask, request, jsonify
import jwt
from dotenv import load_dotenv

load_dotenv()
app = Flask(__name__)

USERS = {
    "alice": {"password": "password123", "id": 1, "role": "admin"},
    "bob": {"password": "secret", "id": 2, "role": "user"},
}

def create_access_token(user):
    payload = {
        "sub": user["id"],
        "name": user["username"],
        "role": user["role"],
        "iat": datetime.datetime.utcnow(),
        "exp": datetime.datetime.utcnow() + datetime.timedelta(minutes=15),
        "aud": "myapi",
        "iss": "auth.mycompany.com",
    }
    token = jwt.encode(payload, os.getenv("ACCESS_TOKEN_SECRET"), algorithm="HS256")
    return token

def create_refresh_token(user):
    payload = {
        "sub": user["id"],
        "iat": datetime.datetime.utcnow(),
        "exp": datetime.datetime.utcnow() + datetime.timedelta(days=7),
    }
    token = jwt.encode(payload, os.getenv("REFRESH_TOKEN_SECRET"), algorithm="HS256")
    return token

@app.route("/login", methods=["POST"])
def login():
    data = request.json
    username = data.get("username")
    password = data.get("password")
    user = USERS.get(username)

    if not user or user["password"] != password:
        return jsonify({"error": "Invalid credentials"}), 401

    user_info = {"id": user["id"], "username": username, "role": user["role"]}
    access_token = create_access_token(user_info)
    refresh_token = create_refresh_token(user_info)

    return jsonify({"access_token": access_token, "refresh_token": refresh_token})

def token_required(f):
    from functools import wraps

    @wraps(f)
    def decorated(*args, **kwargs):
        auth = request.headers.get("Authorization", None)
        if not auth or not auth.startswith("Bearer "):
            return jsonify({"error": "Token missing"}), 401
        token = auth.split()[1]

        try:
            payload = jwt.decode(
                token,
                os.getenv("ACCESS_TOKEN_SECRET"),
                algorithms=["HS256"],
                audience="myapi",
                issuer="auth.mycompany.com",
            )
            request.user = payload
        except jwt.ExpiredSignatureError:
            return jsonify({"error": "Token expired"}), 401
        except jwt.InvalidTokenError:
            return jsonify({"error": "Invalid token"}), 403

        return f(*args, **kwargs)

    return decorated

@app.route("/profile")
@token_required
def profile():
    user = request.user
    return jsonify({"message": f"Hello {user['name']}", "role": user["role"]})

@app.route("/refresh", methods=["POST"])
def refresh():
    data = request.json
    refresh_token = data.get("refresh_token")
    if not refresh_token:
        return jsonify({"error": "Refresh token required"}), 401

    try:
        payload = jwt.decode(
            refresh_token,
            os.getenv("REFRESH_TOKEN_SECRET"),
            algorithms=["HS256"],
        )
        # Look up user in DB (omitted for brevity)
        user = {"id": payload["sub"], "username": "alice", "role": "admin"}
        new_access = create_access_token(user)
        return jsonify({"access_token": new_access})
    except jwt.ExpiredSignatureError:
        return jsonify({"error": "Refresh token expired"}), 401
    except jwt.InvalidTokenError:
        return jsonify({"error": "Invalid refresh token"}), 403

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

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-api</artifactId>
    <version>0.11.5</version>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-impl</artifactId>
    <version>0.11.5</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-jackson</artifactId>
    <version>0.11.5</version>
    <scope>runtime</scope>
</dependency>

package com.example.demo.security;

import io.jsonwebtoken.*;
import io.jsonwebtoken.security.Keys;
import org.springframework.stereotype.Component;

import java.security.Key;
import java.util.Date;
import java.util.Map;

@Component
public class JwtUtil {
    private final Key accessKey = Keys.hmacShaKeyFor("VerySecretAccessKey1234567890".getBytes());
    private final Key refreshKey = Keys.hmacShaKeyFor("EvenMoreSecretRefreshKey0987654321".getBytes());

    public String generateAccessToken(Long userId, String username, String role) {
        return Jwts.builder()
                .setSubject(userId.toString())
                .claim("name", username)
                .claim("role", role)
                .setIssuedAt(new Date())
                .setExpiration(new Date(System.currentTimeMillis() + 15 * 60 * 1000)) // 15 min
                .setAudience("myapi")
                .setIssuer("auth.mycompany.com")
                .signWith(accessKey, SignatureAlgorithm.HS256)
                .compact();
    }

    public String generateRefreshToken(Long userId) {
        return Jwts.builder()
                .setSubject(userId.toString())
                .setIssuedAt(new Date())
                .setExpiration(new Date(System.currentTimeMillis() + 7L * 24 * 60 * 60 * 1000)) // 7 days
                .signWith(refreshKey, SignatureAlgorithm.HS256)
                .compact();
    }

    public Jws<Claims> validateAccessToken(String token) throws JwtException {
        return Jwts.parserBuilder()
                .setSigningKey(accessKey)
                .requireAudience("myapi")
                .requireIssuer("auth.mycompany.com")
                .build()
                .parseClaimsJws(token);
    }

    public Jws<Claims> validateRefreshToken(String token) throws JwtException {
        return Jwts.parserBuilder()
                .setSigningKey(refreshKey)
                .build()
                .parseClaimsJws(token);
    }
}

package com.example.demo.security;

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jws;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.http.HttpHeaders;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;
import java.util.Collections;

public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final JwtUtil jwtUtil;

    public JwtAuthenticationFilter(JwtUtil jwtUtil) {
        this.jwtUtil = jwtUtil;
    }

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain) throws ServletException, IOException {
        String header = request.getHeader(HttpHeaders.AUTHORIZATION);
        if (header != null && header.startsWith("Bearer ")) {
            String token = header.substring(7);
            try {
                Jws<Claims> claims = jwtUtil.validateAccessToken(token);
                String username = claims.getBody().get("name", String.class);
                String role = claims.getBody().get("role", String.class);

                UsernamePasswordAuthenticationToken auth = new UsernamePasswordAuthenticationToken(
                        username,
                        null,
                        Collections.singleton(() -> "ROLE_" + role.toUpperCase())
                );
                SecurityContextHolder.getContext().setAuthentication(auth);
            } catch (Exception e) {
                // Invalid token – let Spring handle as unauthenticated
                SecurityContextHolder.clearContext();
            }
        }
        filterChain.doFilter(request, response);
    }
}

package com.example.demo.security;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class SecurityConfig {

    private final JwtUtil jwtUtil;

    public SecurityConfig(JwtUtil jwtUtil) {
        this.jwtUtil = jwtUtil;
    }

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        JwtAuthenticationFilter jwtFilter = new JwtAuthenticationFilter(jwtUtil);

        http.csrf(csrf -> csrf.disable())
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/login", "/refresh").permitAll()
                .anyRequest().authenticated()
            )
            .addFilterBefore(jwtFilter, org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter.class)
            .httpBasic(Customizer.withDefaults());

        return http.build();
    }
}

package com.example.demo.controller;

import com.example.demo.security.JwtUtil;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
public class AuthController {

    private final JwtUtil jwtUtil;

    public AuthController(JwtUtil jwtUtil) {
        this.jwtUtil = jwtUtil;
    }

    // Dummy user store for demo
    private record User(Long id, String username, String password, String role) {}
    private static final User DUMMY = new User(1L, "alice", "password123", "ADMIN");

    @PostMapping("/login")
    public ResponseEntity<?> login(@RequestBody AuthRequest req) {
        if (!DUMMY.username().equals(req.username()) ||
            !DUMMY.password().equals(req.password())) {
            return ResponseEntity.status(401).body("Invalid credentials");
        }

        String access = jwtUtil.generateAccessToken(DUMMY.id(), DUMMY.username(), DUMMY.role());
        String refresh = jwtUtil.generateRefreshToken(DUMMY.id());

        return ResponseEntity.ok(new Tokens(access, refresh));
    }

    @PostMapping("/refresh")
    public ResponseEntity<?> refresh(@RequestBody RefreshRequest req) {
        try {
            var claims = jwtUtil.validateRefreshToken(req.refreshToken());
            Long userId = Long.valueOf(claims.getBody().getSubject());
            // In real code, fetch user from DB
            String newAccess = jwtUtil.generateAccessToken(userId, DUMMY.username(), DUMMY.role());
            return ResponseEntity.ok(new AccessToken(newAccess));
        } catch (Exception e) {
            return ResponseEntity.status(401).body("Invalid refresh token");
        }
    }

    // DTO records
    public record AuthRequest(String username, String password) {}
    public record Tokens(String accessToken, String refreshToken) {}
    public record RefreshRequest(String refreshToken) {}
    public record AccessToken(String accessToken) {}
}