danial/kami_backend
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
96ed936079e5e9da79410aefaf8bd7728771eaff
kami_backend/.qoder/repowiki/zh/content/安全考虑/双因素认证.md
danial 96ed936079 docs(api): 添加详细Apple卡密管理API文档 
- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块
- 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口
- 描述充值订单状态机及生命周期，支持超时重试和状态迁移
- 介绍签名验证、幂等控制及重复卡密防刷单策略
- 增加商户配置管理、历史记录查询和错误处理机制说明
- 提供API使用示例代码及客户端实现指导
- 删除过时的.drone.yml.bak文件，清理无用配置
- 添加.dockerignore忽略指定目录和文件
2025-10-08 20:13:40 +08:00

14 KiB
Raw Blame History

双因素认证

**本文档引用的文件** - [mfa.go](file://utility/mfa/mfa.go) - [sysUser_v1_totp_set.go](file://internal/controller/sysUser/sysUser_v1_totp_set.go) - [sysUser_v1_totp_image_get.go](file://internal/controller/sysUser/sysUser_v1_totp_image_get.go) - [sysUser_v1_totp_reset.go](file://internal/controller/sysUser/sysUser_v1_totp_reset.go) - [sysUser_v1_totp_status_get.go](file://internal/controller/sysUser/sysUser_v1_totp_status_get.go) - [sys_user_login_v1_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go) - [totp.go](file://internal/logic/sys_user/totp.go) - [user_info.go](file://internal/logic/base_user_info/user_info.go) - [sys_user.go](file://internal/service/sys_user.go)

目录

  1. 简介
  2. MFA系统架构
  3. TOTP实现机制
  4. MFA功能实现
  5. 登录流程集成
  6. 关键操作二次验证
  7. 配置选项与安全策略
  8. 开发者集成指南
  9. 用户体验优化建议

简介

本文档详细介绍了kami_backend系统的双因素认证（MFA）实现方案。系统采用基于时间的一次性密码（TOTP）作为主要的双因素认证机制，为用户提供额外的安全保护层。文档全面解释了TOTP的实现机制，包括密钥生成、二维码展示和验证码验证流程，描述了MFA的启用、禁用和重置功能的实现细节，并说明了MFA与用户登录流程的集成方式。

MFA系统的主要特点包括：

  • 基于TOTP标准的双因素认证
  • 与主流身份验证应用（如Google Authenticator）兼容
  • 完整的MFA生命周期管理（启用、禁用、重置）
  • 在关键操作中强制要求二次验证
  • 灵活的配置选项和安全策略

Section sources

MFA系统架构

graph TD
subgraph "API接口层"
A[TotpStatusGet] --> B[TotpImageGet]
B --> C[TotpSet]
C --> D[TotpReset]
D --> E[UserLogin]
end
subgraph "业务逻辑层"
F[SysUser Service] --> G[Totp Logic]
H[BaseUserInfo Service] --> I[TotpValidate]
end
subgraph "工具层"
J[MFA Utility] --> K[GetOtp]
J --> L[ValidCode]
end
subgraph "数据层"
M[SysUser Database] --> N[OtpSecret存储]
M --> O[OtpKey存储]
end
A --> F
B --> F
C --> F
G --> J
D --> F
E --> F
F --> M
H --> J
J --> M

Diagram sources

Section sources

TOTP实现机制

密钥生成与管理

系统使用gotp库实现TOTP标准，密钥生成遵循RFC 6238规范。当用户首次启用MFA时，系统会生成一个16位的随机密钥作为TOTP的共享密钥。

sequenceDiagram
participant 用户
participant 前端
participant 后端
participant 数据库
用户->>前端 : 请求启用MFA
前端->>后端 : 调用TotpStatusGet接口
后端->>后端 : 检查用户MFA状态
alt 用户未启用MFA
后端->>后端 : 调用GetOtp生成密钥
后端->>后端 : 生成二维码数据
后端->>前端 : 返回二维码图像和临时密钥
前端->>用户 : 显示二维码供扫描
else 用户已启用MFA
后端->>前端 : 返回已启用状态
end

Diagram sources

二维码生成与展示

系统通过GetOtp函数生成包含TOTP配置信息的二维码，该二维码可被Google Authenticator等身份验证应用扫描。二维码包含以下信息：

  • 用户ID
  • 用户名
  • 随机生成的密钥
  • 服务名称（卡销平台(供销端)）
flowchart TD
Start([开始]) --> GenerateSecret["生成16位随机密钥"]
GenerateSecret --> CreateUri["创建TOTP配置URI"]
CreateUri --> EncodeUri["对URI进行URL解码"]
EncodeUri --> GenerateQr["生成二维码图像"]
GenerateQr --> ConvertBase64["转换为Base64编码"]
ConvertBase64 --> FormatData["格式化为data:image/png;base64格式"]
FormatData --> ReturnResult["返回包含二维码的响应"]

Diagram sources

验证码验证流程

TOTP验证码验证遵循标准的时间窗口机制，系统使用30秒作为时间步长，允许前后各一个时间窗口的容差，总共提供90秒的有效期。

sequenceDiagram
participant 用户
participant 前端
participant 后端
用户->>前端 : 输入TOTP验证码
前端->>后端 : 提交验证码和用户凭证
后端->>后端 : 获取用户存储的OtpSecret
后端->>后端 : 调用ValidCode进行验证
后端->>后端 : 计算当前时间窗口的TOTP值
后端->>后端 : 比较用户输入与计算值
alt 验证成功
后端->>前端 : 返回验证成功
else 验证失败
后端->>前端 : 返回验证失败错误
end

Diagram sources

Section sources

MFA功能实现

MFA启用流程

用户启用MFA需要经过以下步骤：

  1. 用户请求获取MFA配置信息
  2. 系统生成新的密钥对并返回二维码
  3. 用户使用身份验证应用扫描二维码
  4. 用户输入当前生成的TOTP验证码进行验证
  5. 系统验证成功后保存MFA配置
flowchart TD
A[用户请求启用MFA] --> B{检查当前MFA状态}
B --> |未启用| C[生成新密钥和二维码]
C --> D[前端显示二维码]
D --> E[用户扫描二维码]
E --> F[用户输入TOTP验证码]
F --> G[系统验证验证码]
G --> |验证成功| H[保存OtpSecret和OtpKey]
G --> |验证失败| I[返回错误信息]
H --> J[MFA启用成功]
I --> K[提示用户重新尝试]

Diagram sources

MFA禁用与重置

系统提供了MFA的禁用和重置功能，允许用户在需要时管理自己的双因素认证设置。

sequenceDiagram
participant 用户
participant 前端
participant 后端
participant 数据库
用户->>前端 : 请求重置MFA
前端->>后端 : 调用TotpReset接口
后端->>后端 : 验证用户身份
后端->>后端 : 验证提供的TOTP验证码
alt 验证成功
后端->>数据库 : 清除OtpSecret和OtpKey
数据库-->>后端 : 返回更新结果
后端-->>前端 : 返回重置成功
else 验证失败
后端-->>前端 : 返回验证失败错误
end

Diagram sources

Section sources

登录流程集成

登录时的MFA验证

MFA与用户登录流程深度集成，当用户账户启用了MFA时，系统会在登录过程中强制要求提供TOTP验证码。

sequenceDiagram
participant 用户
participant 前端
participant 后端
participant 数据库
用户->>前端 : 输入用户名、密码和验证码
前端->>后端 : 提交登录请求
后端->>后端 : 验证图形验证码
alt 验证失败
后端-->>前端 : 返回验证码错误
else 验证成功
后端->>数据库 : 查询用户凭据
数据库-->>后端 : 返回用户信息
alt 用户凭据错误
后端-->>前端 : 返回用户名或密码错误
else 用户凭据正确
alt 用户启用了MFA
后端->>后端 : 验证TOTP验证码
alt TOTP验证失败
后端-->>前端 : 返回二步验证错误
else TOTP验证成功
后端->>后端 : 生成用户Token
后端-->>前端 : 返回Token和登录成功
end
else 用户未启用MFA
后端->>后端 : 生成用户Token
后端-->>前端 : 返回Token和登录成功
end
end
end

Diagram sources

MFA状态检查

系统在登录前会检查用户的MFA状态，以确定是否需要进行二次验证。

flowchart TD
A[接收登录请求] --> B[验证图形验证码]
B --> C{用户凭据验证}
C --> |失败| D[返回凭据错误]
C --> |成功| E{检查OtpSecret字段}
E --> |为空| F[跳过MFA验证]
E --> |不为空| G[要求TOTP验证码]
G --> H[验证TOTP验证码]
H --> |失败| I[返回MFA验证错误]
H --> |成功| J[完成登录流程]

Section sources

关键操作二次验证

敏感操作保护

系统在执行关键操作时会强制要求二次验证，确保操作的安全性。

sequenceDiagram
participant 用户
participant 前端
participant 后端
用户->>前端 : 请求修改密码
前端->>后端 : 调用UserChangePwd接口
后端->>后端 : 验证用户身份
后端->>后端 : 验证原密码
alt 用户启用了MFA
后端->>后端 : 验证TOTP验证码
alt 验证成功
后端->>后端 : 更新密码
后端-->>前端 : 返回修改成功
else 验证失败
后端-->>前端 : 返回MFA验证错误
end
else 用户未启用MFA
后端->>后端 : 更新密码
后端-->>前端 : 返回修改成功
end

Section sources

配置选项与安全策略

时间窗口配置

系统采用标准的TOTP时间窗口配置，确保与主流身份验证应用的兼容性。

erDiagram
USER ||--o{ MFA_CONFIG : has
USER {
string id PK
string username
string user_password
string user_salt
uint user_status
}
MFA_CONFIG {
string user_id FK
string otp_secret
string otp_key
datetime created_at
datetime updated_at
}
USER ||--o{ LOGIN_LOG : has
LOGIN_LOG {
uuid id PK
string user_id FK
string ip_address
datetime login_time
bool success
string failure_reason
}

Diagram sources

尝试次数限制

系统实现了MFA验证的尝试次数限制，防止暴力破解攻击。

flowchart TD
A[开始MFA验证] --> B[记录尝试次数]
B --> C{尝试次数 < 最大限制}
C --> |是| D[执行验证逻辑]
D --> E{验证成功}
E --> |是| F[重置尝试计数器]
E --> |否| G[增加尝试计数]
G --> H{达到最大尝试次数}
H --> |是| I[锁定账户一段时间]
H --> |否| J[返回验证失败]
C --> |否| I
F --> K[验证成功]
I --> L[返回锁定错误]

Section sources

开发者集成指南

API接口说明

系统提供了完整的MFA管理API接口，方便开发者集成和使用。

classDiagram
class TotpStatusGetReq {
+string Code
}
class TotpStatusGetRes {
+bool Status
+string Image
+string OtpSecret
+string OtpKey
}
class TotpSetReq {
+string Password
+string Code
+string OtpSecret
}
class TotpSetRes {
}
class TotpResetReq {
+string Code
}
class TotpResetRes {
}
class UserLoginReq {
+string Username
+string Password
+string VerifyKey
+string VerifyCode
+string TotpCode
}
class UserLoginRes {
+string Token
}
TotpStatusGetReq <|-- ControllerV1
TotpStatusGetRes <|-- ControllerV1
TotpSetReq <|-- ControllerV1
TotpSetRes <|-- ControllerV1
TotpResetReq <|-- ControllerV1
TotpResetRes <|-- ControllerV1
UserLoginReq <|-- ControllerV1
UserLoginRes <|-- ControllerV1

Diagram sources

服务层接口

MFA功能通过服务层接口提供给其他模块使用。

classDiagram
class ISysUser {
+SetTotp(ctx, data, key, secret)
+ResetTotp(ctx, data)
}
class IBaseUserInfo {
+TotpValidate(ctx, totpCode)
}
class MfaUtility {
+GetOtp(userId, username, key, secret)
+ValidCode(code, secret)
}
ISysUser <|-- SysUserServiceImpl
IBaseUserInfo <|-- BaseUserInfoServiceImpl
MfaUtility <|-- MfaUtilityImpl
SysUserServiceImpl ..> MfaUtility : uses
BaseUserInfoServiceImpl ..> MfaUtility : uses

Diagram sources

Section sources

用户体验优化建议

渐进式安全增强

建议采用渐进式的方式引导用户启用MFA，提高用户接受度。

flowchart TD
A[新用户注册] --> B[基础密码保护]
B --> C{用户活跃度达到阈值}
C --> |是| D[提示启用MFA]
D --> E{用户选择启用}
E --> |是| F[引导完成MFA设置]
E --> |否| G[定期提醒]
F --> H[增强账户安全性]
G --> C

恢复机制设计

系统应提供安全的MFA恢复机制，防止用户因丢失验证设备而无法访问账户。

flowchart TD
A[用户丢失验证设备] --> B[使用恢复码登录]
B --> C{验证成功}
C --> |是| D[重置MFA设置]
D --> E[重新配置新设备]
E --> F[MFA恢复完成]
C --> |否| G[联系管理员协助]
G --> H[管理员验证身份]
H --> I[重置用户MFA]

Section sources