API认证 api-authentication

---

name: API认证 description: 使用JWT、OAuth 2.0和API密钥实现安全的API认证。适用于认证系统、第三方集成、服务间通信，或遇到令牌管理、安全头、认证流程错误时。

API认证

使用现代标准和最佳实践实现安全的API认证机制。

认证方法

方法	使用场景	安全等级
JWT	无状态认证，单页应用	高
OAuth 2.0	第三方集成	高
API密钥	服务间通信	中等
会话	传统Web应用	高

JWT实现（Node.js）

const jwt = require('jsonwebtoken');

const generateTokens = (user) => ({
  accessToken: jwt.sign(
    { userId: user.id, role: user.role },
    process.env.JWT_SECRET,
    { expiresIn: '15m' }
  ),
  refreshToken: jwt.sign(
    { userId: user.id, type: 'refresh' },
    process.env.REFRESH_SECRET,
    { expiresIn: '7d' }
  )
});

const authMiddleware = (req, res, next) => {
  const authHeader = req.headers.authorization;

  // 验证授权头格式
  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    return res.status(401).json({ error: '授权头格式错误' });
  }

  const parts = authHeader.split(' ');
  if (parts.length !== 2) {
    return res.status(401).json({ error: '授权头格式错误' });
  }

  const token = parts[1];
  if (!token) {
    return res.status(401).json({ error: '未提供令牌' });
  }

  try {
    req.user = jwt.verify(token, process.env.JWT_SECRET);
    next();
  } catch (err) {
    res.status(401).json({ error: '无效令牌' });
  }
};

安全要求

• 始终使用HTTPS
• 将令牌存储在HttpOnly cookie中（而不是localStorage）
• 使用bcrypt哈希密码（成本因子12+）
• 在认证端点上实施速率限制
• 定期轮换密钥
• 永远不要在URL中传输令牌

安全头

app.use((req, res, next) => {
  res.setHeader('X-Content-Type-Options', 'nosniff');
  res.setHeader('X-Frame-Options', 'DENY');
  res.setHeader('Strict-Transport-Security', 'max-age=31536000');
  next();
});

附加实现

参见 references/python-flask.md 获取：

• 带有基于角色的访问控制装饰器的Flask JWT
• 使用Authlib的OAuth 2.0 Google集成
• 带有安全哈希的API密钥认证

常见错误避免

• 存储明文密码
• 使用弱JWT密钥
• 忽略令牌过期
• 在生产环境中禁用HTTPS
• 记录敏感令牌