JWT authentication security practices

Basic Principles of JWT Authentication

JSON Web Token (JWT) is an open standard (RFC 7519) for securely transmitting information between parties as a JSON object. A JWT consists of three parts: Header, Payload, and Signature, connected by dots. The Header typically contains the token type and signing algorithm, the Payload contains claims, and the Signature is used to verify the message's integrity.

// JWT structure example
const header = {
  "alg": "HS256",
  "typ": "JWT"
};
const payload = {
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022
};
const signature = HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  'secret'
);
const jwt = base64UrlEncode(header) + "." + base64UrlEncode(payload) + "." + signature;

Implementing JWT Authentication in Koa2

Implementing JWT authentication in Koa2 typically requires the jsonwebtoken and koa-jwt libraries. First, install the dependencies:

npm install jsonwebtoken koa-jwt

The basic implementation process includes generating a JWT when a user logs in and validating the JWT in subsequent requests via middleware. Here is a complete example:

const Koa = require('koa');
const Router = require('koa-router');
const jwt = require('jsonwebtoken');
const jwtMiddleware = require('koa-jwt');

const app = new Koa();
const router = new Router();
const SECRET = 'your-secret-key'; // Use a more complex key in production

// Login route
router.post('/login', async (ctx) => {
  const { username, password } = ctx.request.body;
  
  // Validate user credentials (simplified example)
  if (username === 'admin' && password === 'password') {
    const token = jwt.sign({ username }, SECRET, { expiresIn: '1h' });
    ctx.body = { token };
  } else {
    ctx.status = 401;
    ctx.body = { error: 'Invalid credentials' };
  }
});

// Protected route
router.get('/protected', async (ctx) => {
  ctx.body = { message: 'Protected data', user: ctx.state.user };
});

// Apply middleware
app.use(router.routes());
app.use(jwtMiddleware({ secret: SECRET }).unless({ path: [/^\/login/] }));

app.listen(3000);

Security Risks and Mitigations for JWT

While JWT is convenient, it also presents several security risks:

1. Token Leakage: If a JWT is stolen, attackers can impersonate the user. Mitigations include:

   • Using HTTPS for transmission
   • Setting short expiration times
   • Implementing token revocation mechanisms

2. Algorithm Confusion Attacks: Attackers may modify the algorithm to "none" to bypass validation. Mitigations:

   • Explicitly specify the algorithm during verification

   jwt.verify(token, SECRET, { algorithms: ['HS256'] });
   

3. Brute-Force Attacks on Keys: Weak keys are easily cracked. Measures include:

   • Using sufficiently long and complex keys
   • Regularly rotating keys

Advanced Security Practices

Token Refresh Mechanism

Long-lived tokens pose higher risks; implement a refresh mechanism:

// Generate token pair
function generateTokenPair(user) {
  const accessToken = jwt.sign(user, SECRET, { expiresIn: '15m' });
  const refreshToken = jwt.sign(user, SECRET, { expiresIn: '7d' });
  return { accessToken, refreshToken };
}

// Refresh access token
router.post('/refresh', async (ctx) => {
  const { refreshToken } = ctx.request.body;
  try {
    const decoded = jwt.verify(refreshToken, SECRET);
    const accessToken = jwt.sign({ username: decoded.username }, SECRET, { expiresIn: '15m' });
    ctx.body = { accessToken };
  } catch (err) {
    ctx.status = 401;
    ctx.body = { error: 'Invalid refresh token' };
  }
});

Blacklist Implementation

Even if JWTs have expiration times, sometimes tokens need to be actively revoked:

const tokenBlacklist = new Set();

// Logout endpoint
router.post('/logout', async (ctx) => {
  const token = ctx.headers.authorization.split(' ')[1];
  tokenBlacklist.add(token);
  ctx.body = { message: 'Logged out successfully' };
});

// Middleware to check blacklist
app.use(async (ctx, next) => {
  const token = ctx.headers.authorization?.split(' ')[1];
  if (token && tokenBlacklist.has(token)) {
    ctx.status = 401;
    ctx.body = { error: 'Token revoked' };
    return;
  }
  await next();
});

Performance Optimization Considerations

Although JWT validation is stateless, performance considerations are important in high-concurrency scenarios:

1. Reduce Payload Size: Store only necessary information; avoid large user data
2. Use Efficient Signing Algorithms: HS256 is faster than RS256, but the latter is better for distributed systems
3. Cache Validation Results: Cache results for short-term repeated requests

const cache = new Map();

// Cached validation middleware
async function cachedJwtMiddleware(ctx, next) {
  const token = ctx.headers.authorization?.split(' ')[1];
  if (!token) return await next();
  
  if (cache.has(token)) {
    ctx.state.user = cache.get(token);
    return await next();
  }
  
  try {
    const decoded = jwt.verify(token, SECRET);
    cache.set(token, decoded);
    ctx.state.user = decoded;
    await next();
  } catch (err) {
    ctx.status = 401;
    ctx.body = { error: 'Invalid token' };
  }
}

Deployment Considerations in Production

When deploying JWT authentication in production:

1. Key Management:

   • Avoid hardcoding keys in the code
   • Use environment variables or key management services
   • Implement key rotation strategies

2. CORS Configuration:

   app.use(async (ctx, next) => {
     ctx.set('Access-Control-Allow-Origin', 'trusted-domain.com');
     ctx.set('Access-Control-Allow-Headers', 'Authorization, Content-Type');
     ctx.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
     await next();
   });
   

3. Monitoring and Logging:

   • Log failed authentication attempts
   • Monitor abnormal token usage patterns
   • Implement rate limiting to prevent brute-force attacks

Comparison with Other Authentication Methods

JWT has pros and cons compared to traditional session authentication:

1. Stateless vs. Stateful:

   • JWT does not require server-side session storage
   • Session authentication requires server or database storage

2. Scalability:

   • JWT is better suited for distributed systems and microservices
   • Session authentication is simpler for single-server or small-scale deployments

3. Flexibility:

   • JWT can carry custom claims
   • Session authentication typically stores only session IDs

4. Performance:

   • JWT reduces database queries
   • But tokens are usually larger than session IDs

Solutions to Common Issues

Handling Token Expiration

Frontend should handle token expiration gracefully:

// Frontend API request wrapper example
async function request(url, options = {}) {
  const response = await fetch(url, {
    ...options,
    headers: {
      'Authorization': `Bearer ${localStorage.getItem('accessToken')}`,
      ...options.headers
    }
  });
  
  if (response.status === 401) {
    // Attempt to refresh the token
    const refreshResponse = await fetch('/refresh', {
      method: 'POST',
      body: JSON.stringify({
        refreshToken: localStorage.getItem('refreshToken')
      })
    });
    
    if (refreshResponse.ok) {
      const { accessToken } = await refreshResponse.json();
      localStorage.setItem('accessToken', accessToken);
      // Retry the original request
      return request(url, options);
    } else {
      // Refresh failed, redirect to login
      window.location.href = '/login';
    }
  }
  
  return response;
}

Multi-Device Login Management

To limit the number of concurrent devices per user:

// Add device identifiers to user model
const userSchema = new mongoose.Schema({
  username: String,
  password: String,
  devices: [{
    deviceId: String,
    lastLogin: Date
  }],
  maxDevices: { type: Number, default: 3 }
});

// Check device count during login
router.post('/login', async (ctx) => {
  const { username, password, deviceId } = ctx.request.body;
  const user = await User.findOne({ username });
  
  if (user.devices.length >= user.maxDevices) {
    // Remove the oldest device
    user.devices.sort((a, b) => a.lastLogin - b.lastLogin);
    user.devices.shift();
  }
  
  user.devices.push({ deviceId, lastLogin: new Date() });
  await user.save();
  
  // Generate token...
});

Testing Strategies

Comprehensive testing is crucial for JWT security:

1. Unit Tests:

   describe('JWT Authentication', () => {
     it('should generate a valid JWT', () => {
       const token = generateToken({ username: 'test' });
       const decoded = jwt.verify(token, SECRET);
       expect(decoded.username).to.equal('test');
     });
     
     it('should reject expired JWTs', async () => {
       const token = jwt.sign({ username: 'test' }, SECRET, { expiresIn: '-1s' });
       await request(app)
         .get('/protected')
         .set('Authorization', `Bearer ${token}`)
         .expect(401);
     });
   });
   

2. Integration Tests:

   describe('Protected Routes', () => {
     let token;
     
     before(async () => {
       const res = await request(app)
         .post('/login')
         .send({ username: 'admin', password: 'password' });
       token = res.body.token;
     });
     
     it('should allow access with a valid token', async () => {
       await request(app)
         .get('/protected')
         .set('Authorization', `Bearer ${token}`)
         .expect(200);
     });
   });
   

3. Security Tests:

   • Test invalid signatures
   • Test modified tokens
   • Test "none" algorithm tokens
   • Test expired tokens

Logging and Auditing

Comprehensive logging aids security analysis and troubleshooting:

// Authentication logging middleware
app.use(async (ctx, next) => {
  const start = Date.now();
  try {
    await next();
    const ms = Date.now() - start;
    console.log(`${ctx.method} ${ctx.url} - ${ms}ms - ${ctx.status}`);
    
    // Log authentication-related info
    if (ctx.state.user) {
      console.log(`Authenticated request by ${ctx.state.user.username}`);
    }
  } catch (err) {
    // Log authentication errors
    if (err.status === 401) {
      console.warn(`Unauthorized attempt: ${ctx.ip} - ${ctx.headers['user-agent']}`);
    }
    throw err;
  }
});