Back to Details

jwt-authentication

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

JWT Authentication Skill

JWT 认证技能

Implement secure, scalable authentication in Node.js applications using JSON Web Tokens.
在Node.js应用中使用JSON Web Tokens实现安全、可扩展的认证。

Quick Start

快速开始

JWT authentication in 4 steps:
  1. Install - 
    npm install jsonwebtoken bcryptjs
  2. Register - Hash password, create user, generate token
  3. Login - Verify password, generate token
  4. Protect - Verify token in middleware
4步实现JWT认证：
  1. 安装 - 
    npm install jsonwebtoken bcryptjs
  2. 注册 - 哈希密码、创建用户、生成令牌
  3. 登录 - 验证密码、生成令牌
  4. 保护接口 - 在中间件中验证令牌

Core Concepts

核心概念

Generate JWT

生成JWT

javascript
const jwt = require('jsonwebtoken');

function generateToken(userId) {
  return jwt.sign(
    { id: userId },
    process.env.JWT_SECRET,
    { expiresIn: '1h' }
  );
}

function generateRefreshToken(userId) {
  return jwt.sign(
    { id: userId },
    process.env.JWT_REFRESH_SECRET,
    { expiresIn: '7d' }
  );
}
javascript
const jwt = require('jsonwebtoken');

function generateToken(userId) {
  return jwt.sign(
    { id: userId },
    process.env.JWT_SECRET,
    { expiresIn: '1h' }
  );
}

function generateRefreshToken(userId) {
  return jwt.sign(
    { id: userId },
    process.env.JWT_REFRESH_SECRET,
    { expiresIn: '7d' }
  );
}

User Registration

用户注册

javascript
const bcrypt = require('bcryptjs');

async function register(req, res) {
  const { email, password, name } = req.body;

  // Check if user exists
  const existingUser = await User.findOne({ email });
  if (existingUser) {
    return res.status(409).json({ error: 'User already exists' });
  }

  // Hash password
  const hashedPassword = await bcrypt.hash(password, 10);

  // Create user
  const user = await User.create({
    email,
    password: hashedPassword,
    name
  });

  // Generate tokens
  const accessToken = generateToken(user._id);
  const refreshToken = generateRefreshToken(user._id);

  res.status(201).json({
    user: { id: user._id, email, name },
    accessToken,
    refreshToken
  });
}
javascript
const bcrypt = require('bcryptjs');

async function register(req, res) {
  const { email, password, name } = req.body;

  // Check if user exists
  const existingUser = await User.findOne({ email });
  if (existingUser) {
    return res.status(409).json({ error: 'User already exists' });
  }

  // Hash password
  const hashedPassword = await bcrypt.hash(password, 10);

  // Create user
  const user = await User.create({
    email,
    password: hashedPassword,
    name
  });

  // Generate tokens
  const accessToken = generateToken(user._id);
  const refreshToken = generateRefreshToken(user._id);

  res.status(201).json({
    user: { id: user._id, email, name },
    accessToken,
    refreshToken
  });
}

User Login

用户登录

javascript
async function login(req, res) {
  const { email, password } = req.body;

  // Find user
  const user = await User.findOne({ email });
  if (!user) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }

  // Verify password
  const isValid = await bcrypt.compare(password, user.password);
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }

  // Generate tokens
  const accessToken = generateToken(user._id);
  const refreshToken = generateRefreshToken(user._id);

  res.json({
    user: { id: user._id, email: user.email },
    accessToken,
    refreshToken
  });
}
javascript
async function login(req, res) {
  const { email, password } = req.body;

  // Find user
  const user = await User.findOne({ email });
  if (!user) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }

  // Verify password
  const isValid = await bcrypt.compare(password, user.password);
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }

  // Generate tokens
  const accessToken = generateToken(user._id);
  const refreshToken = generateRefreshToken(user._id);

  res.json({
    user: { id: user._id, email: user.email },
    accessToken,
    refreshToken
  });
}

Authentication Middleware

认证中间件

javascript
async function authenticate(req, res, next) {
  try {
    // Get token from header
    const authHeader = req.headers.authorization;
    if (!authHeader || !authHeader.startsWith('Bearer ')) {
      return res.status(401).json({ error: 'No token provided' });
    }

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

    // Verify token
    const decoded = jwt.verify(token, process.env.JWT_SECRET);

    // Get user
    const user = await User.findById(decoded.id).select('-password');
    if (!user) {
      return res.status(401).json({ error: 'User not found' });
    }

    req.user = user;
    next();
  } catch (error) {
    res.status(401).json({ error: 'Invalid token' });
  }
}

// Usage
router.get('/profile', authenticate, getProfile);
javascript
async function authenticate(req, res, next) {
  try {
    // Get token from header
    const authHeader = req.headers.authorization;
    if (!authHeader || !authHeader.startsWith('Bearer ')) {
      return res.status(401).json({ error: 'No token provided' });
    }

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

    // Verify token
    const decoded = jwt.verify(token, process.env.JWT_SECRET);

    // Get user
    const user = await User.findById(decoded.id).select('-password');
    if (!user) {
      return res.status(401).json({ error: 'User not found' });
    }

    req.user = user;
    next();
  } catch (error) {
    res.status(401).json({ error: 'Invalid token' });
  }
}

// Usage
router.get('/profile', authenticate, getProfile);

Learning Path

学习路径

Beginner (1-2 weeks)

入门级（1-2周）

  • ✅ Understand JWT structure
  • ✅ Implement registration/login
  • ✅ Create authentication middleware
  • ✅ Protect routes
  • ✅ 理解JWT结构
  • ✅ 实现注册/登录功能
  • ✅ 创建认证中间件
  • ✅ 保护接口路由

Intermediate (3-4 weeks)

进阶级（3-4周）

  • ✅ Refresh token flow
  • ✅ Role-based access control
  • ✅ Password reset flow
  • ✅ Token blacklisting
  • ✅ 刷新令牌流程
  • ✅ 基于角色的访问控制
  • ✅ 密码重置流程
  • ✅ 令牌黑名单

Advanced (5-6 weeks)

高级（5-6周）

  • ✅ OAuth integration
  • ✅ Two-factor authentication
  • ✅ Session management
  • ✅ Security best practices
  • ✅ OAuth集成
  • ✅ 双因素认证
  • ✅ 会话管理
  • ✅ 安全最佳实践

Advanced Patterns

高级模式

Role-Based Access Control

基于角色的访问控制

javascript
const authorize = (...roles) => {
  return (req, res, next) => {
    if (!req.user) {
      return res.status(401).json({ error: 'Not authenticated' });
    }

    if (!roles.includes(req.user.role)) {
      return res.status(403).json({ error: 'Insufficient permissions' });
    }

    next();
  };
};

// Usage
router.delete('/users/:id',
  authenticate,
  authorize('admin', 'moderator'),
  deleteUser
);
javascript
const authorize = (...roles) => {
  return (req, res, next) => {
    if (!req.user) {
      return res.status(401).json({ error: 'Not authenticated' });
    }

    if (!roles.includes(req.user.role)) {
      return res.status(403).json({ error: 'Insufficient permissions' });
    }

    next();
  };
};

// Usage
router.delete('/users/:id',
  authenticate,
  authorize('admin', 'moderator'),
  deleteUser
);

Token Refresh

令牌刷新

javascript
async function refreshAccessToken(req, res) {
  const { refreshToken } = req.body;

  try {
    const decoded = jwt.verify(refreshToken, process.env.JWT_REFRESH_SECRET);

    // Verify refresh token exists in database
    const stored = await RefreshToken.findOne({
      token: refreshToken,
      userId: decoded.id
    });

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

    // Generate new access token
    const accessToken = generateToken(decoded.id);

    res.json({ accessToken });
  } catch (error) {
    res.status(401).json({ error: 'Token refresh failed' });
  }
}
javascript
async function refreshAccessToken(req, res) {
  const { refreshToken } = req.body;

  try {
    const decoded = jwt.verify(refreshToken, process.env.JWT_REFRESH_SECRET);

    // Verify refresh token exists in database
    const stored = await RefreshToken.findOne({
      token: refreshToken,
      userId: decoded.id
    });

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

    // Generate new access token
    const accessToken = generateToken(decoded.id);

    res.json({ accessToken });
  } catch (error) {
    res.status(401).json({ error: 'Token refresh failed' });
  }
}

Password Reset Flow

密码重置流程

javascript
async function requestPasswordReset(req, res) {
  const { email } = req.body;
  const user = await User.findOne({ email });

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

  // Generate reset token (short expiry)
  const resetToken = jwt.sign(
    { id: user._id, purpose: 'reset' },
    process.env.JWT_SECRET,
    { expiresIn: '15m' }
  );

  // Send email with reset link
  await sendResetEmail(user.email, resetToken);

  res.json({ message: 'Reset email sent' });
}

async function resetPassword(req, res) {
  const { token, newPassword } = req.body;

  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);

    if (decoded.purpose !== 'reset') {
      return res.status(400).json({ error: 'Invalid token' });
    }

    const hashedPassword = await bcrypt.hash(newPassword, 10);
    await User.findByIdAndUpdate(decoded.id, { password: hashedPassword });

    res.json({ message: 'Password reset successful' });
  } catch (error) {
    res.status(400).json({ error: 'Invalid or expired token' });
  }
}
javascript
async function requestPasswordReset(req, res) {
  const { email } = req.body;
  const user = await User.findOne({ email });

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

  // Generate reset token (short expiry)
  const resetToken = jwt.sign(
    { id: user._id, purpose: 'reset' },
    process.env.JWT_SECRET,
    { expiresIn: '15m' }
  );

  // Send email with reset link
  await sendResetEmail(user.email, resetToken);

  res.json({ message: 'Reset email sent' });
}

async function resetPassword(req, res) {
  const { token, newPassword } = req.body;

  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);

    if (decoded.purpose !== 'reset') {
      return res.status(400).json({ error: 'Invalid token' });
    }

    const hashedPassword = await bcrypt.hash(newPassword, 10);
    await User.findByIdAndUpdate(decoded.id, { password: hashedPassword });

    res.json({ message: 'Password reset successful' });
  } catch (error) {
    res.status(400).json({ error: 'Invalid or expired token' });
  }
}

Security Best Practices

安全最佳实践

  • ✅ Use strong JWT secrets (32+ characters, random)
  • ✅ Short expiry for access tokens (15min - 1h)
  • ✅ Longer expiry for refresh tokens (7d - 30d)
  • ✅ Store refresh tokens in database
  • ✅ Hash passwords with bcrypt (10+ rounds)
  • ✅ Use HTTPS in production
  • ✅ Implement rate limiting
  • ✅ Validate all inputs
  • ✅ Don't store sensitive data in JWT payload
  • ✅ 使用强JWT密钥（32个字符以上，随机生成）
  • ✅ 访问令牌设置短有效期（15分钟-1小时）
  • ✅ 刷新令牌设置较长有效期（7天-30天）
  • ✅ 在数据库中存储刷新令牌
  • ✅ 使用bcrypt哈希密码（10轮以上）
  • ✅ 生产环境使用HTTPS
  • ✅ 实现速率限制
  • ✅ 验证所有输入
  • ✅ 不要在JWT负载中存储敏感数据

JWT Structure

JWT 结构

header.payload.signature

Header (base64):
{
  "alg": "HS256",
  "typ": "JWT"
}

Payload (base64):
{
  "id": "user123",
  "iat": 1516239022,
  "exp": 1516242622
}

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

Header (base64):
{
  "alg": "HS256",
  "typ": "JWT"
}

Payload (base64):
{
  "id": "user123",
  "iat": 1516239022,
  "exp": 1516242622
}

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

Common JWT Claims

常见JWT声明

  • iss
    - Issuer
  • sub
    - Subject (user ID)
  • aud
    - Audience
  • exp
    - Expiration time
  • iat
    - Issued at
  • nbf
    - Not before
  • iss
    - 签发者
  • sub
    - 主题（用户ID）
  • aud
    - 受众
  • exp
    - 过期时间
  • iat
    - 签发时间
  • nbf
    - 生效时间

When to Use

适用场景

Use JWT authentication when:
  • Building stateless REST APIs
  • Need scalability (no server-side sessions)
  • Mobile app authentication
  • Microservices architecture
  • Single sign-on (SSO)
在以下场景使用JWT认证：
  • 构建无状态REST API
  • 需要可扩展性（无服务器端会话）
  • 移动应用认证
  • 微服务架构
  • 单点登录（SSO）

Related Skills

相关技能

  • Express REST API (protect API endpoints)
  • Database Integration (store users)
  • Testing & Debugging (test auth flows)
  • Performance Optimization (token caching)
  • Express REST API（保护API端点）
  • 数据库集成（存储用户）
  • 测试与调试（测试认证流程）
  • 性能优化（令牌缓存）

Resources

参考资源