How to Set expiry using koa- jwt

JWT (JSON Web Token) serves as a core mechanism for authentication in modern web applications. Setting the expiration time for JWT (exp claim) is a critical security step, effectively preventing tokens from being abused for extended periods and mitigating session hijacking risks. For example, if a token lacks an expiration time, attackers could access sensitive resources for an extended period by stealing the token. This article explores how to precisely configure JWT expiration time in Koa, combining practical code examples and security recommendations to help developers build robust authentication systems.

Importance of Setting JWT Expiration Time

• Security Risk Prevention: Once a JWT token is generated without the exp (expiration) field, attackers may exploit it for unauthorized actions, such as credential theft or privilege escalation.
• Compliance Requirements: According to OWASP security standards (OWASP Top 10), authentication tokens must have defined expiration times to reduce the attack surface.
• Balancing User Experience: Too short an expiration time (e.g., 5 minutes) may cause frequent re-authentication, while too long (e.g., 30 days) increases risk. A reasonable setting (e.g., 15 minutes) balances security and smooth user experience.

Implementing JWT Expiration Time in Koa

Environment Setup and Dependency Installation

First, ensure your project has the necessary dependencies:

bash
npm install koa koa-router jsonwebtoken@8.5.1

Note: It is recommended to use jsonwebtoken@8.x as it handles the expiresIn parameter more stably. The koa-jwt middleware validates tokens but does not handle expiration logic by default, requiring integration with the jsonwebtoken library.

Setting the exp Field When Generating Tokens

When generating a JWT, specify expiration time using the expiresIn parameter. This accepts strings (e.g., '15m') or numbers (e.g., 600000 milliseconds), which the system automatically converts to a Unix timestamp.

javascript
const jwt = require('jsonwebtoken');
const secret = 'your-strong-secret-key'; // Store securely via environment variables

// Generate token: set 15-minute validity
const token = jwt.sign({ userId: 123 }, secret, {
  expiresIn: '15m', // Key: specify expiration time
  algorithm: 'HS256' // Recommended algorithm for security
});

// Validate token (optional)
console.log('Token:', token);
console.log('Expiration time:', jwt.decode(token, { json: true }).exp);

Key Point: The exp field's value is a Unix timestamp (in seconds). For example, '15m' generates 1715630872 (assuming current time), which is automatically checked during validation.

Integrating Validation and Expiration Handling in Koa Routes

Use the koa-jwt middleware to automatically validate tokens, but explicitly configure expiration logic. Here is a complete example:

javascript
const Koa = require('koa');
const Router = require('koa-router');
const jwt = require('jsonwebtoken');
const app = new Koa();
const router = new Router();

// Initialize middleware: handle expiration errors
app.use(require('koa-jwt')({
  secret: 'your-strong-secret-key',
  // Configuration: throw error when token expires
  getToken: ctx => ctx.headers.authorization?.split(' ')[1],
  // Validation: ensure exp field is valid
  isRevoked: (ctx, token) => {
    const now = Math.floor(Date.now() / 1000);
    if (token.exp < now) {
      ctx.status = 401;
      ctx.body = 'Token expired';
      return true;
    }
    return false;
  }
}));

// Protected route example
router.get('/protected', async (ctx) => {
  ctx.body = { message: 'Access granted', userId: ctx.state.user.id };
});

app.use(router.routes());

// Start server
app.listen(3000, () => console.log('Server started on port 3000'));

Practical Recommendation: In the isRevoked callback, do not rely on jwt.isExpired (as the jsonwebtoken library lacks this method); instead, directly validate the exp field:

Handling Token Expiration Exception Flow

When a token expires, koa-jwt throws a 401 Unauthorized error. Capture and return a user-friendly response in routes:

javascript
router.get('/protected', async (ctx) => {
  try {
    // Middleware validates token; state.user is available
    ctx.body = { message: 'Valid session' };
  } catch (err) {
    if (err.name === 'UnauthorizedError') {
      ctx.status = 401;
      ctx.body = { error: 'Token expired or invalid' };
    } else {
      throw err;
    }
  }
});

Security Enhancement: In production, implement the refresh token mechanism. When the primary token expires, use the refresh token to obtain a new token (e.g., 7-day validity), but store the refresh token server-side with strict security measures (Refresh Token Pattern Details).

Best Practices and Security Recommendations

• Avoid Hardcoding Secrets: Store the secret in environment variables (e.g., .env), using the dotenv library:

bash
npm install dotenv

javascript
require('dotenv').config();
const secret = process.env.JWT_SECRET;

• Set Reasonable Expiration Time: Choose based on business needs:

  • Short Lifespan: 5-15 minutes (high-security scenarios, e.g., financial transactions).
  • Medium Lifespan: 1-7 days (typical web applications).
  • Long Lifespan: Disabled (only for refresh tokens).

• Enforce HTTPS: In Koa, enforce HTTPS when serving static resources with koa-static:

javascript
app.use(require('koa-static')(__dirname + '/public', {
  maxage: 3600000,
  immutable: true
}));

• Logging and Monitoring: Log token creation and validation events for auditing:

javascript
const logger = require('morgan');
app.use(logger('combined'));

Conclusion

Setting JWT expiration time is foundational for security in Koa applications. This article demonstrates how to specify the exp field during token generation and handle expiration logic in routes through practical examples. Core principle: always explicitly set expiresIn, and combine HTTPS with refresh token mechanisms for multi-layered security. Developers should regularly audit token expiration times and refer to the JWT Standard Specification for compliance. Strictly implementing these measures significantly reduces security risks and enhances user trust.

​