609 lines
15 KiB
Markdown
609 lines
15 KiB
Markdown
# 认证机制详解
|
||
|
||
本文档详细说明 Web Rust Template 的 JWT 认证机制、安全特性和最佳实践。
|
||
|
||
## 目录
|
||
|
||
- [认证架构概述](#认证架构概述)
|
||
- [双 Token 机制](#双-token-机制)
|
||
- [认证流程](#认证流程)
|
||
- [Token 管理](#token-管理)
|
||
- [安全特性](#安全特性)
|
||
- [最佳实践](#最佳实践)
|
||
|
||
---
|
||
|
||
## 认证架构概述
|
||
|
||
本系统采用 **JWT (JSON Web Token)** 进行用户认证，使用 **双 Token 机制**：
|
||
|
||
1. **Access Token**：短期有效，用于 API 请求认证
|
||
2. **Refresh Token**：长期有效，用于获取新的 Access Token
|
||
|
||
### 架构特点
|
||
|
||
- ✅ **无状态认证**：服务器不存储会话信息，易于扩展
|
||
- ✅ **安全性**：Token 泄露影响可控，自动过期
|
||
- ✅ **用户体验**：Refresh Token 可减少用户登录次数
|
||
- ✅ **可撤销性**：通过 Redis 存储 Refresh Token，支持主动撤销
|
||
|
||
---
|
||
|
||
## 双 Token 机制
|
||
|
||
### Access Token
|
||
|
||
**用途**：访问需要认证的 API 接口
|
||
|
||
**特点**：
|
||
- 有效期：15 分钟（可配置）
|
||
- 包含用户 ID 和 Token 类型信息
|
||
- 不存储在服务器端（无状态）
|
||
- 每次请求都通过 HTTP Header 传递
|
||
|
||
**格式**：
|
||
```http
|
||
Authorization: Bearer <access_token>
|
||
```
|
||
|
||
### Refresh Token
|
||
|
||
**用途**：获取新的 Access Token
|
||
|
||
**特点**：
|
||
- 有效期：7 天（可配置）
|
||
- 存储在 Redis 中
|
||
- 支持撤销和主动登出
|
||
- 每次刷新会生成新的 Refresh Token
|
||
|
||
**存储位置**：
|
||
- 前端：localStorage 或 sessionStorage
|
||
- 后端：Redis（Key：`auth:refresh_token:<user_id>`）
|
||
|
||
---
|
||
|
||
## 认证流程
|
||
|
||
### 1. 用户注册流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户
|
||
participant Frontend as 前端应用
|
||
participant API as API 服务器
|
||
participant DB as 数据库
|
||
participant Redis as Redis
|
||
|
||
User->>Frontend: 输入邮箱和密码
|
||
Frontend->>API: POST /auth/register
|
||
API->>API: 验证邮箱格式
|
||
API->>API: 生成用户 ID
|
||
API->>API: 哈希密码（Argon2）
|
||
API->>DB: 创建用户记录
|
||
DB-->>API: 用户创建成功
|
||
API->>API: 生成 Access Token (15min)
|
||
API->>API: 生成 Refresh Token (7days)
|
||
API->>Redis: 存储 Refresh Token
|
||
Redis-->>API: 存储成功
|
||
API-->>Frontend: 返回 Access Token + Refresh Token
|
||
Frontend->>Frontend: 存储 Token 到 localStorage
|
||
Frontend-->>User: 注册成功，自动登录
|
||
```
|
||
|
||
**关键点**：
|
||
- 密码使用 Argon2 算法哈希，不可逆
|
||
- Refresh Token 存储在 Redis，支持撤销
|
||
- 注册成功后自动登录，返回 Token
|
||
|
||
### 2. 用户登录流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户
|
||
participant Frontend as 前端应用
|
||
participant API as API 服务器
|
||
participant DB as 数据库
|
||
participant Redis as Redis
|
||
|
||
User->>Frontend: 输入邮箱和密码
|
||
Frontend->>API: POST /auth/login
|
||
API->>DB: 查询用户记录
|
||
DB-->>API: 返回用户信息
|
||
API->>API: 验证密码（Argon2）
|
||
API->>API: 生成 Access Token (15min)
|
||
API->>API: 生成 Refresh Token (7days)
|
||
API->>Redis: 存储/更新 Refresh Token
|
||
Redis-->>API: 存储成功
|
||
API-->>Frontend: 返回 Access Token + Refresh Token
|
||
Frontend->>Frontend: 存储 Token 到 localStorage
|
||
Frontend-->>User: 登录成功
|
||
```
|
||
|
||
**安全特性**：
|
||
- 登录失败不返回具体错误信息（防止账号枚举）
|
||
- 密码错误会记录日志用于风控
|
||
- Refresh Token 每次登录都会更新
|
||
|
||
### 3. 访问受保护接口流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Frontend as 前端应用
|
||
participant API as API 服务器
|
||
participant Redis as Redis
|
||
|
||
Frontend->>API: GET /protected<br/>Authorization: Bearer <access_token>
|
||
API->>API: 验证 JWT 签名
|
||
API->>API: 检查 Token 类型
|
||
API->>API: 检查 Token 过期时间
|
||
alt Token 有效
|
||
API-->>Frontend: 200 OK 返回数据
|
||
else Token 无效或过期
|
||
API-->>Frontend: 401 Unauthorized
|
||
Frontend->>API: POST /auth/refresh
|
||
API->>Redis: 获取 Refresh Token
|
||
Redis-->>API: 返回 Refresh Token
|
||
API->>API: 验证 Refresh Token
|
||
API->>API: 生成新的 Token 对
|
||
API->>Redis: 更新 Refresh Token
|
||
API-->>Frontend: 返回新的 Token
|
||
Frontend->>API: 重试原请求
|
||
API-->>Frontend: 200 OK 返回数据
|
||
end
|
||
```
|
||
|
||
**关键点**：
|
||
- 所有受保护接口都需要在 Header 中携带 Access Token
|
||
- Token 过期时前端自动刷新并重试请求
|
||
- 刷新成功后旧 Refresh Token 立即失效
|
||
|
||
### 4. Token 刷新流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Frontend as 前端应用
|
||
participant API as API 服务器
|
||
participant Redis as Redis
|
||
|
||
Frontend->>API: POST /auth/refresh<br/>{"refresh_token": "..."}
|
||
API->>API: 验证 Refresh Token 签名
|
||
API->>API: 检查 Token 类型（必须是 Refresh Token）
|
||
API->>API: 检查 Token 过期时间
|
||
API->>Redis: 检查 Refresh Token 是否存在
|
||
alt Token 有效
|
||
API->>API: 生成新的 Access Token (15min)
|
||
API->>API: 生成新的 Refresh Token (7days)
|
||
API->>Redis: 删除旧的 Refresh Token
|
||
API->>Redis: 存储新的 Refresh Token
|
||
API-->>Frontend: 返回新的 Token 对
|
||
else Token 无效或过期
|
||
API-->>Frontend: 401 Unauthorized
|
||
Frontend->>Frontend: 清除 Token
|
||
Frontend->>Frontend: 跳转到登录页
|
||
end
|
||
```
|
||
|
||
**Token 轮换**：
|
||
- 每次刷新都会生成新的 Refresh Token
|
||
- 旧的 Refresh Token 立即失效
|
||
- 防止 Token 重放攻击
|
||
|
||
### 5. 用户登出流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户
|
||
participant Frontend as 前端应用
|
||
participant API as API 服务器
|
||
participant Redis as Redis
|
||
|
||
User->>Frontend: 点击登出按钮
|
||
Frontend->>API: POST /auth/delete-refresh-token<br/>Authorization: Bearer <access_token>
|
||
API->>API: 验证 Access Token
|
||
API->>API: 从 Token 中提取 user_id
|
||
API->>Redis: 删除 Refresh Token
|
||
Redis-->>API: 删除成功
|
||
API-->>Frontend: 200 OK
|
||
Frontend->>Frontend: 清除本地 Token
|
||
Frontend->>Frontend: 跳转到登录页
|
||
Frontend-->>User: 登出成功
|
||
```
|
||
|
||
---
|
||
|
||
## Token 管理
|
||
|
||
### Token 生成
|
||
|
||
```rust
|
||
// src/utils/jwt.rs
|
||
|
||
// 生成 Access Token
|
||
pub fn generate_access_token(
|
||
user_id: &str,
|
||
expiration_minutes: u64,
|
||
jwt_secret: &str,
|
||
) -> Result<String> {
|
||
let expiration = Utc::now()
|
||
.checked_add_signed(Duration::minutes(expiration_minutes as i64))
|
||
.expect("invalid expiration timestamp")
|
||
.timestamp() as usize;
|
||
|
||
let claims = Claims {
|
||
sub: user_id.to_string(),
|
||
exp: expiration,
|
||
token_type: TokenType::Access,
|
||
};
|
||
|
||
let token = encode(
|
||
&Header::default(),
|
||
&claims,
|
||
&EncodingKey::from_secret(jwt_secret.as_ref()),
|
||
)?;
|
||
|
||
Ok(token)
|
||
}
|
||
|
||
// 生成 Refresh Token
|
||
pub fn generate_refresh_token(
|
||
user_id: &str,
|
||
expiration_days: i64,
|
||
jwt_secret: &str,
|
||
) -> Result<String> {
|
||
let expiration = Utc::now()
|
||
.checked_add_signed(Duration::days(expiration_days))
|
||
.expect("invalid expiration timestamp")
|
||
.timestamp() as usize;
|
||
|
||
let claims = Claims {
|
||
sub: user_id.to_string(),
|
||
exp: expiration,
|
||
token_type: TokenType::Refresh,
|
||
};
|
||
|
||
let token = encode(
|
||
&Header::default(),
|
||
&claims,
|
||
&EncodingKey::from_secret(jwt_secret.as_ref()),
|
||
)?;
|
||
|
||
Ok(token)
|
||
}
|
||
```
|
||
|
||
### Token 验证
|
||
|
||
```rust
|
||
// src/infra/middleware/auth.rs
|
||
|
||
pub async fn auth_middleware(
|
||
State(state): State<AppState>,
|
||
mut request: Request,
|
||
next: Next,
|
||
) -> Result<Response, ErrorResponse> {
|
||
// 1. 提取 Authorization header
|
||
let auth_header = request
|
||
.headers()
|
||
.get("Authorization")
|
||
.and_then(|h| h.to_str().ok())
|
||
.ok_or_else(|| ErrorResponse::new("缺少 Authorization header".to_string()))?;
|
||
|
||
// 2. 验证 Bearer 格式
|
||
if !auth_header.starts_with("Bearer ") {
|
||
return Err(ErrorResponse::new("Authorization header 格式错误".to_string()));
|
||
}
|
||
|
||
let token = &auth_header[7..]; // 跳过 "Bearer "
|
||
|
||
// 3. 验证 JWT 签名和过期时间
|
||
let claims = decode_token(token, &state.config.auth.jwt_secret)?;
|
||
|
||
// 4. 检查 Token 类型（必须是 Access Token）
|
||
if claims.token_type != TokenType::Access {
|
||
return Err(ErrorResponse::new("Token 类型错误".to_string()));
|
||
}
|
||
|
||
// 5. 将 user_id 添加到请求扩展中
|
||
let user_id = claims.sub;
|
||
request.extensions_mut().insert(user_id);
|
||
|
||
// 6. 继续处理请求
|
||
Ok(next.run(request).await)
|
||
}
|
||
```
|
||
|
||
### Refresh Token 存储
|
||
|
||
```rust
|
||
// src/services/auth_service.rs
|
||
|
||
async fn save_refresh_token(&self, user_id: &str, refresh_token: &str, expiration_days: i64) -> Result<()> {
|
||
let key = RedisKey::new(BusinessType::Auth)
|
||
.add_identifier("refresh_token")
|
||
.add_identifier(user_id);
|
||
|
||
let expiration_seconds = expiration_days * 24 * 3600;
|
||
|
||
self.redis_client
|
||
.set_ex(&key.build(), refresh_token, expiration_seconds as u64)
|
||
.await
|
||
.map_err(|e| anyhow::anyhow!("Redis 保存失败: {}", e))?;
|
||
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
**Redis Key 设计**：
|
||
```
|
||
auth:refresh_token:<user_id>
|
||
```
|
||
|
||
**过期时间**：7 天（与 Refresh Token 有效期一致）
|
||
|
||
---
|
||
|
||
## 安全特性
|
||
|
||
### 1. 密码安全
|
||
|
||
**Argon2 哈希**：
|
||
- 使用 Argon2 算法（内存 hard，抗 GPU/ASIC 破解）
|
||
- 自动生成随机盐值
|
||
- 哈希结果不可逆
|
||
|
||
```rust
|
||
// src/services/auth_service.rs
|
||
|
||
pub fn hash_password(&self, password: &str) -> Result<String> {
|
||
let salt = SaltString::generate(&mut OsRng);
|
||
let argon2 = Argon2::default();
|
||
let password_hash = argon2
|
||
.hash_password(password.as_bytes(), &salt)
|
||
.map_err(|e| anyhow::anyhow!("密码哈希失败: {}", e))?
|
||
.to_string();
|
||
Ok(password_hash)
|
||
}
|
||
```
|
||
|
||
### 2. JWT 安全
|
||
|
||
**签名算法**：HS256 (HMAC-SHA256)
|
||
|
||
**Claims 结构**：
|
||
```rust
|
||
pub struct Claims {
|
||
pub sub: String, // 用户 ID
|
||
pub exp: usize, // 过期时间（Unix 时间戳）
|
||
pub token_type: TokenType, // Token 类型（Access/Refresh）
|
||
}
|
||
```
|
||
|
||
**安全措施**：
|
||
- 使用强密钥（至少 32 位随机字符串）
|
||
- Token 包含过期时间
|
||
- Token 类型区分（防止混用）
|
||
- 签名验证防止篡改
|
||
|
||
### 3. Refresh Token 安全
|
||
|
||
**存储安全**：
|
||
- 存储在 Redis 中，支持快速撤销
|
||
- 每次刷新生成新 Token，旧 Token 失效
|
||
- 支持主动登出，删除 Refresh Token
|
||
|
||
**使用限制**：
|
||
- Refresh Token 只能使用一次
|
||
- 过期后无法续期
|
||
- 需要重新登录
|
||
|
||
### 4. 防护措施
|
||
|
||
**防重放攻击**：
|
||
- Refresh Token 单次使用
|
||
- 刷新后立即失效
|
||
|
||
**防 Token 泄露**：
|
||
- Access Token 短期有效（15 分钟）
|
||
- 只通过 HTTPS 传输
|
||
- 不在 URL 中传递
|
||
|
||
**防暴力破解**：
|
||
- 限制登录频率（可选实现）
|
||
- 记录失败尝试（日志）
|
||
- 密码哈希使用 Argon2
|
||
|
||
---
|
||
|
||
## 最佳实践
|
||
|
||
### 前端集成
|
||
|
||
#### 1. Token 存储
|
||
|
||
**推荐方案**：
|
||
```typescript
|
||
// 存储 Token
|
||
localStorage.setItem('access_token', access_token);
|
||
localStorage.setItem('refresh_token', refresh_token);
|
||
|
||
// 读取 Token
|
||
const accessToken = localStorage.getItem('access_token');
|
||
const refreshToken = localStorage.getItem('refresh_token');
|
||
|
||
// 清除 Token
|
||
localStorage.removeItem('access_token');
|
||
localStorage.removeItem('refresh_token');
|
||
```
|
||
|
||
#### 2. 请求拦截器
|
||
|
||
```typescript
|
||
// 添加 Token 到请求头
|
||
api.interceptors.request.use((config) => {
|
||
const accessToken = localStorage.getItem('access_token');
|
||
if (accessToken) {
|
||
config.headers.Authorization = `Bearer ${accessToken}`;
|
||
}
|
||
return config;
|
||
});
|
||
```
|
||
|
||
#### 3. 响应拦截器（自动刷新 Token）
|
||
|
||
```typescript
|
||
// 处理 401 错误并自动刷新
|
||
api.interceptors.response.use(
|
||
(response) => response,
|
||
async (error) => {
|
||
const originalRequest = error.config;
|
||
|
||
if (error.response?.status === 401 && !originalRequest._retry) {
|
||
originalRequest._retry = true;
|
||
|
||
try {
|
||
const refreshToken = localStorage.getItem('refresh_token');
|
||
const response = await axios.post('/auth/refresh', {
|
||
refresh_token: refreshToken,
|
||
});
|
||
|
||
const { access_token, refresh_token } = response.data.data;
|
||
|
||
localStorage.setItem('access_token', access_token);
|
||
localStorage.setItem('refresh_token', refresh_token);
|
||
|
||
// 重试原请求
|
||
originalRequest.headers.Authorization = `Bearer ${access_token}`;
|
||
return axios(originalRequest);
|
||
} catch (refreshError) {
|
||
// 刷新失败，跳转登录页
|
||
localStorage.clear();
|
||
window.location.href = '/login';
|
||
return Promise.reject(refreshError);
|
||
}
|
||
}
|
||
|
||
return Promise.reject(error);
|
||
}
|
||
);
|
||
```
|
||
|
||
### 后端开发
|
||
|
||
#### 1. 密码强度要求
|
||
|
||
```rust
|
||
// 验证密码强度
|
||
fn validate_password(password: &str) -> Result<()> {
|
||
if password.len() < 8 {
|
||
return Err(anyhow!("密码长度至少 8 位"));
|
||
}
|
||
if password.len() > 100 {
|
||
return Err(anyhow!("密码长度最多 100 位"));
|
||
}
|
||
// 可添加更多规则（如必须包含大小写、数字等）
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
#### 2. JWT 密钥管理
|
||
|
||
**开发环境**：
|
||
|
||
使用 `config/` 目录下的配置文件：
|
||
|
||
```bash
|
||
# 方式1：使用默认配置（推荐）
|
||
# JWT 密钥已在 config/default.toml 中配置
|
||
|
||
# 方式2：创建本地配置文件
|
||
cp config/default.toml config/local.toml
|
||
# 编辑 config/local.toml，修改 jwt_secret
|
||
nano config/local.toml
|
||
|
||
# 运行
|
||
cargo run -- -c config/local.toml
|
||
```
|
||
|
||
**生产环境**：
|
||
```bash
|
||
# 使用强随机密钥
|
||
AUTH_JWT_SECRET=$(openssl rand -base64 32)
|
||
```
|
||
|
||
#### 3. Token 过期时间配置
|
||
|
||
```bash
|
||
# Access Token：15 分钟（推荐）
|
||
AUTH_ACCESS_TOKEN_EXPIRATION_MINUTES=15
|
||
|
||
# Refresh Token：7 天（推荐）
|
||
AUTH_REFRESH_TOKEN_EXPIRATION_DAYS=7
|
||
```
|
||
|
||
**建议**：
|
||
- Access Token：5-30 分钟（权衡安全性和用户体验）
|
||
- Refresh Token：7-30 天（根据应用安全要求）
|
||
|
||
### 生产部署
|
||
|
||
#### 1. HTTPS 强制
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name api.yourdomain.com;
|
||
return 301 https://$server_name$request_uri;
|
||
}
|
||
|
||
server {
|
||
listen 443 ssl;
|
||
server_name api.yourdomain.com;
|
||
# SSL 配置...
|
||
}
|
||
```
|
||
|
||
#### 2. CORS 配置
|
||
|
||
开发环境可以允许所有来源：
|
||
|
||
```rust
|
||
CorsLayer::new()
|
||
.allow_origin(Any)
|
||
.allow_methods(Any)
|
||
.allow_headers(Any)
|
||
```
|
||
|
||
生产环境应该限制允许的来源：
|
||
|
||
```rust
|
||
CorsLayer::new()
|
||
.allow_origin("https://yourdomain.com".parse::<HeaderValue>().unwrap())
|
||
.allow_methods([Method::GET, Method::POST, Method::PUT, Method::DELETE])
|
||
.allow_headers([HeaderName::from_static("content-type"), HeaderName::from_static("authorization")])
|
||
```
|
||
|
||
#### 3. 速率限制
|
||
|
||
防止暴力破解和 DDoS 攻击（需要额外实现）：
|
||
|
||
```rust
|
||
// 使用 governor 库实现速率限制
|
||
use governor::{Quota, RateLimiter};
|
||
|
||
let limiter = RateLimiter::direct(Quota::per_second(5));
|
||
// 每秒最多 5 个请求
|
||
```
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [公开接口文档](endpoints/public.md) - 注册、登录、刷新 Token 接口
|
||
- [受保护接口文档](endpoints/protected.md) - 需要认证的接口
|
||
- [前端集成示例](examples/frontend-integration.md) - 完整的前端集成代码
|
||
- [环境变量配置](../deployment/environment-variables.md) - 认证相关配置说明
|
||
|
||
---
|
||
|
||
**提示**：生产环境部署前务必修改 JWT 密钥为强随机字符串！
|