JWT Authentication: Implementation Guide

JSON Web Tokens (JWTs) enable stateless authentication. Here's how to implement them securely.

JWT Structure#

Header.Payload.Signature

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

Payload:
{
  "sub": "user123",
  "iat": 1704067200,
  "exp": 1704070800,
  "role": "user"
}

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

Token Creation#

import jwt from 'jsonwebtoken';

interface TokenPayload {
  sub: string;
  role: string;
  email: string;
}

const ACCESS_TOKEN_SECRET = process.env.ACCESS_TOKEN_SECRET!;
const REFRESH_TOKEN_SECRET = process.env.REFRESH_TOKEN_SECRET!;

function createAccessToken(user: User): string {
  const payload: TokenPayload = {
    sub: user.id,
    role: user.role,
    email: user.email,
  };

  return jwt.sign(payload, ACCESS_TOKEN_SECRET, {
    expiresIn: '15m',
    issuer: 'your-app',
    audience: 'your-app',
  });
}

function createRefreshToken(user: User): string {
  return jwt.sign(
    { sub: user.id, tokenVersion: user.tokenVersion },
    REFRESH_TOKEN_SECRET,
    {
      expiresIn: '7d',
      issuer: 'your-app',
    }
  );
}

// Token pair
function createTokenPair(user: User): TokenPair {
  return {
    accessToken: createAccessToken(user),
    refreshToken: createRefreshToken(user),
  };
}

Token Validation#

function verifyAccessToken(token: string): TokenPayload {
  try {
    return jwt.verify(token, ACCESS_TOKEN_SECRET, {
      issuer: 'your-app',
      audience: 'your-app',
    }) as TokenPayload;
  } catch (error) {
    if (error instanceof jwt.TokenExpiredError) {
      throw new AuthError('Token expired', 'TOKEN_EXPIRED');
    }
    if (error instanceof jwt.JsonWebTokenError) {
      throw new AuthError('Invalid token', 'INVALID_TOKEN');
    }
    throw error;
  }
}

// Authentication middleware
async function authenticate(
  req: Request,
  res: Response,
  next: NextFunction
): Promise<void> {
  const authHeader = req.headers.authorization;

  if (!authHeader?.startsWith('Bearer ')) {
    res.status(401).json({ error: 'No token provided' });
    return;
  }

  const token = authHeader.slice(7);

  try {
    const payload = verifyAccessToken(token);

    // Optionally fetch user from database
    const user = await prisma.user.findUnique({
      where: { id: payload.sub },
      select: { id: true, role: true, email: true },
    });

    if (!user) {
      res.status(401).json({ error: 'User not found' });
      return;
    }

    req.user = user;
    next();
  } catch (error) {
    if (error instanceof AuthError) {
      res.status(401).json({ error: error.message, code: error.code });
      return;
    }
    res.status(401).json({ error: 'Invalid token' });
  }
}

Refresh Token Flow#

// Store refresh tokens in database
model RefreshToken {
  id        String   @id @default(cuid())
  token     String   @unique
  userId    String
  user      User     @relation(fields: [userId], references: [id])
  expiresAt DateTime
  createdAt DateTime @default(now())
  revokedAt DateTime?

  @@index([userId])
  @@index([token])
}

// Refresh endpoint
app.post('/auth/refresh', async (req, res) => {
  const { refreshToken } = req.body;

  if (!refreshToken) {
    return res.status(400).json({ error: 'Refresh token required' });
  }

  try {
    // Verify token signature
    const payload = jwt.verify(refreshToken, REFRESH_TOKEN_SECRET) as {
      sub: string;
    };

    // Check token in database
    const storedToken = await prisma.refreshToken.findUnique({
      where: { token: refreshToken },
      include: { user: true },
    });

    if (!storedToken || storedToken.revokedAt || storedToken.expiresAt < new Date()) {
      return res.status(401).json({ error: 'Invalid refresh token' });
    }

    // Rotate refresh token
    await prisma.refreshToken.update({
      where: { id: storedToken.id },
      data: { revokedAt: new Date() },
    });

    // Create new tokens
    const newRefreshToken = createRefreshToken(storedToken.user);

    await prisma.refreshToken.create({
      data: {
        token: newRefreshToken,
        userId: storedToken.userId,
        expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
      },
    });

    res.json({
      accessToken: createAccessToken(storedToken.user),
      refreshToken: newRefreshToken,
    });
  } catch (error) {
    res.status(401).json({ error: 'Invalid refresh token' });
  }
});

Token Revocation#

// Logout - revoke refresh token
app.post('/auth/logout', authenticate, async (req, res) => {
  const { refreshToken } = req.body;

  if (refreshToken) {
    await prisma.refreshToken.updateMany({
      where: {
        token: refreshToken,
        userId: req.user.id,
      },
      data: { revokedAt: new Date() },
    });
  }

  res.status(204).send();
});

// Logout from all devices
app.post('/auth/logout-all', authenticate, async (req, res) => {
  await prisma.refreshToken.updateMany({
    where: {
      userId: req.user.id,
      revokedAt: null,
    },
    data: { revokedAt: new Date() },
  });

  res.status(204).send();
});

// Password change - invalidate all tokens
async function changePassword(userId: string, newPassword: string): Promise<void> {
  const hashedPassword = await bcrypt.hash(newPassword, 12);

  await prisma.$transaction([
    prisma.user.update({
      where: { id: userId },
      data: { password: hashedPassword },
    }),
    prisma.refreshToken.updateMany({
      where: { userId, revokedAt: null },
      data: { revokedAt: new Date() },
    }),
  ]);
}

// More secure for web applications
const COOKIE_OPTIONS: CookieOptions = {
  httpOnly: true,
  secure: process.env.NODE_ENV === 'production',
  sameSite: 'strict',
  path: '/',
};

app.post('/auth/login', async (req, res) => {
  // Validate credentials...
  const user = await validateCredentials(req.body);

  const tokens = createTokenPair(user);

  // Store refresh token in HTTP-only cookie
  res.cookie('refreshToken', tokens.refreshToken, {
    ...COOKIE_OPTIONS,
    maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
  });

  // Access token in response body
  res.json({ accessToken: tokens.accessToken });
});

// Refresh using cookie
app.post('/auth/refresh', async (req, res) => {
  const refreshToken = req.cookies.refreshToken;

  if (!refreshToken) {
    return res.status(401).json({ error: 'No refresh token' });
  }

  // Validate and rotate...
  const tokens = await rotateTokens(refreshToken);

  res.cookie('refreshToken', tokens.refreshToken, {
    ...COOKIE_OPTIONS,
    maxAge: 7 * 24 * 60 * 60 * 1000,
  });

  res.json({ accessToken: tokens.accessToken });
});

// Logout - clear cookie
app.post('/auth/logout', (req, res) => {
  res.clearCookie('refreshToken', COOKIE_OPTIONS);
  res.status(204).send();
});

Client-Side Token Management#

// Token storage and refresh
class AuthClient {
  private accessToken: string | null = null;
  private refreshPromise: Promise<string> | null = null;

  async getAccessToken(): Promise<string> {
    if (this.accessToken && !this.isTokenExpired(this.accessToken)) {
      return this.accessToken;
    }

    return this.refresh();
  }

  private async refresh(): Promise<string> {
    // Prevent multiple simultaneous refresh requests
    if (this.refreshPromise) {
      return this.refreshPromise;
    }

    this.refreshPromise = this.doRefresh();

    try {
      return await this.refreshPromise;
    } finally {
      this.refreshPromise = null;
    }
  }

  private async doRefresh(): Promise<string> {
    const response = await fetch('/auth/refresh', {
      method: 'POST',
      credentials: 'include', // Include cookies
    });

    if (!response.ok) {
      this.accessToken = null;
      throw new Error('Refresh failed');
    }

    const { accessToken } = await response.json();
    this.accessToken = accessToken;
    return accessToken;
  }

  private isTokenExpired(token: string): boolean {
    try {
      const payload = JSON.parse(atob(token.split('.')[1]));
      // Add 30 second buffer
      return payload.exp * 1000 < Date.now() + 30000;
    } catch {
      return true;
    }
  }
}

// Axios interceptor
axios.interceptors.request.use(async (config) => {
  const token = await authClient.getAccessToken();
  config.headers.Authorization = `Bearer ${token}`;
  return config;
});

Security Best Practices#

Tokens:
✓ Short-lived access tokens (15 minutes)
✓ Longer-lived refresh tokens (7 days)
✓ Rotate refresh tokens on use
✓ Store refresh tokens in database

Storage:
✓ HttpOnly cookies for refresh tokens
✓ Memory for access tokens (not localStorage)
✓ Secure flag in production
✓ SameSite=Strict

Validation:
✓ Verify signature, issuer, audience
✓ Check expiration
✓ Validate user still exists
✓ Handle token revocation

General:
✓ Use strong secrets (256+ bits)
✓ Different secrets for access/refresh
✓ Implement logout from all devices
✓ Rotate tokens on password change

JWT authentication requires careful implementation. Use short-lived access tokens with longer-lived refresh tokens. Store refresh tokens in HTTP-only cookies, rotate them on use, and implement proper revocation. Never store JWTs in localStorage—use memory or secure cookies.