认证系统搭建

技能适用场景

以下是需要使用该技能的具体场景：

用户登录系统：为新应用添加用户认证功能时
API安全：为REST API或GraphQL API添加认证层时
权限管理：需要根据用户角色进行访问控制时
认证迁移：将现有认证系统迁移至JWT或OAuth时
SSO集成：集成Google、GitHub、Microsoft等社交登录时

输入格式（Input Format）

需要从用户处获取的输入格式及必填/可选信息：

必填信息

认证方式：从JWT、Session、OAuth 2.0中选择
后端框架：Express、Django、FastAPI、Spring Boot等
数据库：PostgreSQL、MySQL、MongoDB等
安全要求：密码策略、令牌过期时间等

可选信息

MFA支持：是否启用2FA/MFA（默认值：false）
社交登录：OAuth提供商（Google、GitHub等）
会话存储：Redis、内存存储等（使用Session方式时）
Refresh Token：是否使用（默认值：true）

输入示例

请帮我搭建用户认证系统：
- 认证方式: JWT
- 框架: Express.js + TypeScript
- 数据库: PostgreSQL
- MFA: 支持Google Authenticator
- 社交登录: Google, GitHub
- Refresh Token: 使用

操作步骤

以下是需要严格遵循的分步操作流程：

步骤1：数据模型设计

设计用户及认证相关的数据库架构。

工作内容:

设计User表（id、email、password_hash、role、created_at、updated_at）
RefreshToken表（可选）
OAuthProvider表（使用社交登录时）
绝对禁止明文存储密码（必须使用bcrypt/argon2进行哈希）

示例（PostgreSQL）：

sql

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255),  -- 仅使用OAuth时为NULL
    role VARCHAR(50) DEFAULT 'user',
    is_verified BOOLEAN DEFAULT false,
    mfa_secret VARCHAR(255),
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE refresh_tokens (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    token VARCHAR(500) UNIQUE NOT NULL,
    expires_at TIMESTAMP NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_refresh_tokens_user_id ON refresh_tokens(user_id);

步骤2：密码安全实现

实现密码哈希及验证逻辑。

工作内容:

使用bcrypt（Node.js）或argon2（Python）
Salt rounds至少设置为10
密码强度验证（至少8位，包含大小写字母、数字、特殊字符）

选择标准:

Node.js项目 → 使用bcrypt库
Python项目 → 使用argon2-cffi或passlib
注重性能时 → 选择bcrypt
追求最高安全性时 → 选择argon2

示例（Node.js + TypeScript）：

typescript

import bcrypt from 'bcrypt';

const SALT_ROUNDS = 12;

export async function hashPassword(password: string): Promise<string> {
    // 密码强度验证
    if (password.length < 8) {
        throw new Error('密码长度至少为8位');
    }

    const hasUpperCase = /[A-Z]/.test(password);
    const hasLowerCase = /[a-z]/.test(password);
    const hasNumber = /\d/.test(password);
    const hasSpecial = /[!@#$%^&*(),.?":{}|<>]/.test(password);

    if (!hasUpperCase || !hasLowerCase || !hasNumber || !hasSpecial) {
        throw new Error('密码必须包含大写字母、小写字母、数字和特殊字符');
    }

    return await bcrypt.hash(password, SALT_ROUNDS);
}

export async function verifyPassword(password: string, hash: string): Promise<boolean> {
    return await bcrypt.compare(password, hash);
}

步骤3：JWT令牌生成与验证

实现基于JWT的认证令牌系统。

工作内容:

Access Token（短过期时间：15分钟）
Refresh Token（长过期时间：7天~30天）
使用高强度SECRET密钥进行JWT签名（通过环境变量管理）
令牌载荷仅包含必要信息（user_id、role）

示例（Node.js）：

typescript

import jwt from 'jsonwebtoken';

const ACCESS_TOKEN_SECRET = process.env.ACCESS_TOKEN_SECRET!;
const REFRESH_TOKEN_SECRET = process.env.REFRESH_TOKEN_SECRET!;
const ACCESS_TOKEN_EXPIRY = '15m';
const REFRESH_TOKEN_EXPIRY = '7d';

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

export function generateAccessToken(payload: TokenPayload): string {
    return jwt.sign(payload, ACCESS_TOKEN_SECRET, {
        expiresIn: ACCESS_TOKEN_EXPIRY,
        issuer: 'your-app-name',
        audience: 'your-app-users'
    });
}

export function generateRefreshToken(payload: TokenPayload): string {
    return jwt.sign(payload, REFRESH_TOKEN_SECRET, {
        expiresIn: REFRESH_TOKEN_EXPIRY,
        issuer: 'your-app-name',
        audience: 'your-app-users'
    });
}

export function verifyAccessToken(token: string): TokenPayload {
    return jwt.verify(token, ACCESS_TOKEN_SECRET, {
        issuer: 'your-app-name',
        audience: 'your-app-users'
    }) as TokenPayload;
}

export function verifyRefreshToken(token: string): TokenPayload {
    return jwt.verify(token, REFRESH_TOKEN_SECRET, {
        issuer: 'your-app-name',
        audience: 'your-app-users'
    }) as TokenPayload;
}

步骤4：认证中间件实现

编写用于保护API请求的认证中间件。

检查项:

从Authorization头中提取Bearer令牌
验证令牌及检查过期时间
令牌有效时将用户信息添加至req.user
错误处理（401 Unauthorized）

示例（Express.js）：

typescript

import { Request, Response, NextFunction } from 'express';
import { verifyAccessToken } from './jwt';

export interface AuthRequest extends Request {
    user?: {
        userId: string;
        email: string;
        role: string;
    };
}

export function authenticateToken(req: AuthRequest, res: Response, next: NextFunction) {
    const authHeader = req.headers['authorization'];
    const token = authHeader && authHeader.split(' ')[1]; // Bearer TOKEN

    if (!token) {
        return res.status(401).json({ error: '需要Access Token' });
    }

    try {
        const payload = verifyAccessToken(token);
        req.user = payload;
        next();
    } catch (error) {
        if (error.name === 'TokenExpiredError') {
            return res.status(401).json({ error: '令牌已过期' });
        }
        return res.status(403).json({ error: '无效令牌' });
    }
}

// 基于角色的授权中间件
export function requireRole(...roles: string[]) {
    return (req: AuthRequest, res: Response, next: NextFunction) => {
        if (!req.user) {
            return res.status(401).json({ error: '需要认证' });
        }

        if (!roles.includes(req.user.role)) {
            return res.status(403).json({ error: '权限不足' });
        }

        next();
    };
}

步骤5：认证API端点实现

实现注册、登录、令牌刷新等API。

工作内容:

POST /auth/register - 用户注册
POST /auth/login - 用户登录
POST /auth/refresh - 令牌刷新
POST /auth/logout - 用户登出
GET /auth/me - 获取当前用户信息

示例:

typescript

import express from 'express';
import { hashPassword, verifyPassword } from './password';
import { generateAccessToken, generateRefreshToken, verifyRefreshToken } from './jwt';
import { authenticateToken } from './middleware';

const router = express.Router();

// 用户注册
router.post('/register', async (req, res) => {
    try {
        const { email, password } = req.body;

        // 检查邮箱是否已存在
        const existingUser = await db.user.findUnique({ where: { email } });
        if (existingUser) {
            return res.status(409).json({ error: '该邮箱已被注册' });
        }

        // 密码哈希
        const passwordHash = await hashPassword(password);

        // 创建用户
        const user = await db.user.create({
            data: { email, password_hash: passwordHash, role: 'user' }
        });

        // 生成令牌
        const accessToken = generateAccessToken({
            userId: user.id,
            email: user.email,
            role: user.role
        });
        const refreshToken = generateRefreshToken({
            userId: user.id,
            email: user.email,
            role: user.role
        });

        // 存储Refresh Token到数据库
        await db.refreshToken.create({
            data: {
                user_id: user.id,
                token: refreshToken,
                expires_at: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000) // 7天
            }
        });

        res.status(201).json({
            user: { id: user.id, email: user.email, role: user.role },
            accessToken,
            refreshToken
        });
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

// 用户登录
router.post('/login', async (req, res) => {
    try {
        const { email, password } = req.body;

        // 查询用户
        const user = await db.user.findUnique({ where: { email } });
        if (!user || !user.password_hash) {
            return res.status(401).json({ error: '凭证无效' });
        }

        // 验证密码
        const isValid = await verifyPassword(password, user.password_hash);
        if (!isValid) {
            return res.status(401).json({ error: '凭证无效' });
        }

        // 生成令牌
        const accessToken = generateAccessToken({
            userId: user.id,
            email: user.email,
            role: user.role
        });
        const refreshToken = generateRefreshToken({
            userId: user.id,
            email: user.email,
            role: user.role
        });

        // 存储Refresh Token
        await db.refreshToken.create({
            data: {
                user_id: user.id,
                token: refreshToken,
                expires_at: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
            }
        });

        res.json({
            user: { id: user.id, email: user.email, role: user.role },
            accessToken,
            refreshToken
        });
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

// 令牌刷新
router.post('/refresh', async (req, res) => {
    try {
        const { refreshToken } = req.body;

        if (!refreshToken) {
            return res.status(401).json({ error: '需要Refresh Token' });
        }

        // 验证Refresh Token
        const payload = verifyRefreshToken(refreshToken);

        // 检查数据库中的令牌
        const storedToken = await db.refreshToken.findUnique({
            where: { token: refreshToken }
        });

        if (!storedToken || storedToken.expires_at < new Date()) {
            return res.status(403).json({ error: 'Refresh Token无效或已过期' });
        }

        // 生成新的Access Token
        const accessToken = generateAccessToken({
            userId: payload.userId,
            email: payload.email,
            role: payload.role
        });

        res.json({ accessToken });
    } catch (error) {
        res.status(403).json({ error: '无效的Refresh Token' });
    }
});

// 获取当前用户信息
router.get('/me', authenticateToken, async (req: AuthRequest, res) => {
    try {
        const user = await db.user.findUnique({
            where: { id: req.user!.userId },
            select: { id: true, email: true, role: true, created_at: true }
        });

        res.json({ user });
    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

export default router;

输出格式

定义结果需遵循的标准格式。

基础结构

项目目录/
├── src/
│   ├── auth/
│   │   ├── password.ts          # 密码哈希/验证
│   │   ├── jwt.ts                # JWT令牌生成/验证
│   │   ├── middleware.ts         # 认证中间件
│   │   └── routes.ts             # 认证API端点
│   ├── models/
│   │   └── User.ts               # 用户模型
│   └── database/
│       └── schema.sql            # 数据库架构
├── .env.example                  # 环境变量模板
└── README.md                     # 认证系统文档

环境变量文件（.env.example）

bash

# JWT密钥（生产环境必须修改）
ACCESS_TOKEN_SECRET=your-access-token-secret-min-32-characters
REFRESH_TOKEN_SECRET=your-refresh-token-secret-min-32-characters

# 数据库
DATABASE_URL=postgresql://user:password@localhost:5432/myapp

# OAuth（可选）
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

约束规则

明确必须遵守的规则与禁止事项。

必须遵守的规则（MUST）

密码安全：绝对禁止明文存储密码
- 使用bcrypt、argon2等经过验证的哈希算法
- Salt rounds至少设置为10
环境变量管理：所有密钥通过环境变量管理
- 将.env文件添加至.gitignore
- 提供.env.example文件列出所需变量
令牌过期：Access Token设置为短期（15分钟），Refresh Token设置为合理期限（7天）
- 平衡安全性与用户体验
- Refresh Token需存储至数据库以便失效

禁止事项（MUST NOT）

明文密码：绝对禁止明文存储密码或在日志中输出
- 存在严重安全风险
- 可能引发法律责任
JWT密钥硬编码：禁止在代码中直接写入SECRET密钥
- 存在泄露至GitHub的风险
- 导致生产环境安全漏洞
令牌包含敏感信息：禁止在JWT载荷中包含密码、银行卡号等敏感信息
- JWT可被解码（并非加密）
- 仅包含必要信息（user_id、role）

安全规则

速率限制：为登录API添加速率限制（防止暴力破解）
强制HTTPS：生产环境仅使用HTTPS
CORS配置：仅允许指定域名访问API
输入验证：验证所有用户输入（防止SQL注入、XSS攻击）

使用示例

通过实际案例展示技能的应用方法。

示例1：Express.js + PostgreSQL JWT认证

场景：为Node.js Express应用添加基于JWT的用户认证

用户请求：

请为我的Express.js应用添加JWT认证，使用PostgreSQL数据库，
Access Token过期时间设为15分钟，Refresh Token设为7天。

技能应用流程：

安装依赖：

bash

npm install jsonwebtoken bcrypt pg
npm install --save-dev @types/jsonwebtoken @types/bcrypt

创建数据库架构（使用上述SQL示例）

设置环境变量：

bash

ACCESS_TOKEN_SECRET=$(openssl rand -base64 32)
REFRESH_TOKEN_SECRET=$(openssl rand -base64 32)

实现认证模块（使用上述代码示例）

连接API路由：

typescript

import authRoutes from './auth/routes';
app.use('/api/auth', authRoutes);

最终结果：完成JWT认证系统搭建，注册/登录/令牌刷新API可正常运行

示例2：基于角色的访问控制（RBAC）

场景：构建区分管理员与普通用户的权限系统

用户请求：

请创建仅管理员可访问的API，
普通用户访问时需返回403错误。

最终结果：

typescript

// 管理员专用API
router.delete('/users/:id',
    authenticateToken,           // 验证认证
    requireRole('admin'),         // 验证角色
    async (req, res) => {
        // 用户删除逻辑
        await db.user.delete({ where: { id: req.params.id } });
        res.json({ message: '用户已删除' });
    }
);

// 使用示例
// 普通用户（role: 'user'）请求 → 403 Forbidden
// 管理员用户（role: 'admin'）请求 → 200 OK

最佳实践

有效使用该技能的建议。

提升安全性

密码轮换策略：定期更换密码
- 每90天提醒用户更换
- 禁止重复使用最近5个密码
- 平衡用户体验与安全性
多因素认证（MFA）：为重要账号启用2FA
- 使用Google Authenticator、Authy等TOTP应用
- 避免使用SMS（存在SIM卡劫持风险）
- 提供备用验证码
审计日志：记录所有认证事件
- 记录登录成功/失败、IP地址、User Agent
- 用于异常检测与事后分析
- 符合GDPR要求（排除敏感信息）

提升效率

令牌黑名单：登出时失效Refresh Token
Redis缓存：缓存常用用户信息
数据库索引：为email、refresh_token字段添加索引

常见问题（Common Issues）

常见问题及解决方法。

问题1："JsonWebTokenError: invalid signature"

症状:

验证令牌时触发错误
可正常登录但无法访问认证API

原因: Access Token与Refresh Token使用不同的SECRET密钥，却使用同一密钥进行验证

解决方法:

检查环境变量：
```
ACCESS_TOKEN_SECRET
```
、
```
REFRESH_TOKEN_SECRET
```
为每种令牌类型使用对应的SECRET密钥
确认环境变量已正确加载（检查
```
dotenv
```
初始化）

问题2：前端因CORS错误无法登录

症状：浏览器控制台显示"CORS policy"错误

原因：Express服务器未配置CORS

解决方法:

typescript

import cors from 'cors';

app.use(cors({
    origin: process.env.FRONTEND_URL || 'http://localhost:3000',
    credentials: true
}));

问题3：Refresh Token频繁过期

症状：用户频繁被登出

原因：Refresh Token未在数据库中正确管理

解决方法:

确认生成Refresh Token时已存储至数据库
合理设置过期时间（至少7天）
添加定时任务定期清理过期令牌

参考资料

官方文档

安全指南

元数据

版本

当前版本: 1.0.0
最后更新: 2025-01-01
兼容平台: Claude, ChatGPT, Gemini

authentication-setup

NPX安装

标签

SKILL.md 内容（中文）

认证系统搭建

技能适用场景

输入格式（Input Format）

必填信息

可选信息

输入示例

操作步骤

步骤1：数据模型设计

步骤2：密码安全实现

步骤3：JWT令牌生成与验证

步骤4：认证中间件实现

步骤5：认证API端点实现

输出格式

基础结构

环境变量文件（.env.example）

约束规则

必须遵守的规则（MUST）

禁止事项（MUST NOT）

安全规则

使用示例

示例1：Express.js + PostgreSQL JWT认证

示例2：基于角色的访问控制（RBAC）

最佳实践

提升安全性

提升效率

常见问题（Common Issues）

问题1："JsonWebTokenError: invalid signature"

问题2：前端因CORS错误无法登录

问题3：Refresh Token频繁过期

参考资料

官方文档

相关库

安全指南

元数据

版本

相关技能

标签