96ed936079
- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块 - 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口 - 描述充值订单状态机及生命周期，支持超时重试和状态迁移 - 介绍签名验证、幂等控制及重复卡密防刷单策略 - 增加商户配置管理、历史记录查询和错误处理机制说明 - 提供API使用示例代码及客户端实现指导 - 删除过时的.drone.yml.bak文件，清理无用配置 - 添加.dockerignore忽略指定目录和文件
7.6 KiB
双因素认证
**本文档中引用的文件** - [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_status_get.go](file://internal/controller/sysUser/sysUser_v1_totp_status_get.go) - [sysUser_v1_totp_reset.go](file://internal/controller/sysUser/sysUser_v1_totp_reset.go) - [totp.go](file://api/sysUser/v1/totp.go) - [sys_user.go](file://internal/service/sys_user.go)目录
简介
本文档全面描述了kami_backend系统中基于时间的一次性密码（TOTP）双因素认证的实现机制。文档涵盖TOTP密钥生成、二维码展示、验证码验证流程，以及用户启用和禁用双因素认证的接口实现与安全考虑。同时解释了MFA工具类的功能和集成方式，包括TOTP验证过程中的时间同步和容错处理，并提供双因素认证的安全最佳实践和用户操作指南。
项目结构
kami_backend的双因素认证功能主要分布在api/sysUser/v1、internal/controller/sysUser和utility/mfa目录中。api目录定义了TOTP相关的API接口，internal/controller/sysUser实现了控制器逻辑，而utility/mfa提供了核心的MFA工具函数。
graph TB
subgraph "API层"
A[totp.go]
end
subgraph "控制器层"
B[sysUser_v1_totp_set.go]
C[sysUser_v1_totp_image_get.go]
D[sysUser_v1_totp_status_get.go]
E[sysUser_v1_totp_reset.go]
end
subgraph "服务层"
F[sys_user.go]
end
subgraph "工具层"
G[mfa.go]
end
A --> B
A --> C
A --> D
A --> E
B --> F
C --> F
D --> F
E --> F
B --> G
C --> G
D --> G
E --> G
F --> G
Diagram sources
- totp.go
- sysUser_v1_totp_set.go
- sysUser_v1_totp_image_get.go
- sysUser_v1_totp_status_get.go
- sysUser_v1_totp_reset.go
- sys_user.go
- mfa.go
Section sources
核心组件
双因素认证的核心组件包括MFA工具类、TOTP状态获取、TOTP设置、TOTP二维码获取和TOTP重置功能。这些组件协同工作，实现了完整的双因素认证流程。
Section sources
- mfa.go
- sysUser_v1_totp_set.go
- sysUser_v1_totp_image_get.go
- sysUser_v1_totp_status_get.go
- sysUser_v1_totp_reset.go
架构概述
双因素认证的架构分为四层：API层、控制器层、服务层和工具层。API层定义了TOTP相关的接口，控制器层处理业务逻辑，服务层提供用户数据操作，工具层实现TOTP的核心算法。
graph TD
A[API层] --> B[控制器层]
B --> C[服务层]
C --> D[工具层]
A --> |HTTP请求| B
B --> |调用| C
C --> |调用| D
D --> |返回| C
C --> |返回| B
B --> |响应| A
Diagram sources
详细组件分析
MFA工具类分析
MFA工具类提供了TOTP密钥生成、二维码生成和验证码验证的核心功能。
classDiagram
class Otp {
+string Secret
+string QrImage
+string Key
}
class mfa {
+GetOtp(userId, username, key, secret) Otp
+ValidCode(code, secret) bool
}
mfa --> Otp : "返回"
Diagram sources
Section sources
TOTP设置流程分析
用户设置TOTP的流程包括验证密码和验证码，然后保存TOTP密钥。
sequenceDiagram
participant Client as "客户端"
participant Controller as "TotpSet控制器"
participant Service as "SysUserService"
participant MFA as "MFA工具"
Client->>Controller : POST /user/totp/set
Controller->>Service : LoginOnlyLogin()
Service-->>Controller : 用户信息
Controller->>MFA : ValidCode(code, otpSecret)
MFA-->>Controller : 验证结果
alt 验证失败
Controller-->>Client : 验证码错误
else 验证成功
Controller->>Service : SetTotp()
Service-->>Controller : 成功
Controller-->>Client : 成功响应
end
Diagram sources
Section sources
TOTP状态获取分析
获取TOTP状态的流程根据用户是否已启用TOTP返回不同信息。
flowchart TD
Start([开始]) --> Auth["验证登录状态"]
Auth --> Check["检查OtpSecret是否为空"]
Check --> |为空| Generate["生成新OTP"]
Generate --> Return["返回二维码和密钥"]
Check --> |不为空| ReturnStatus["返回已启用状态"]
Return --> End([结束])
ReturnStatus --> End
Diagram sources
Section sources
依赖分析
双因素认证功能依赖于多个组件和外部库。
graph TD
A[mfa.go] --> B[gotp]
A --> C[qrcode]
A --> D[grand]
B --> E[TOTP算法]
C --> F[二维码生成]
D --> G[随机字符串生成]
G1[sysUser控制器] --> A
G2[sys_user服务] --> A
Diagram sources
Section sources
性能考虑
双因素认证的性能主要受二维码生成和TOTP验证算法的影响。系统使用了高效的第三方库来处理这些计算密集型任务，确保了良好的响应性能。
故障排除指南
常见问题
- 二维码无法扫描：检查生成的base64编码是否正确，确保数据URI格式正确。
- 验证码验证失败：确认客户端和服务器时间同步，检查TOTP时间窗口设置。
- 密钥生成失败：确保gotp库正确导入并可用。
Section sources
结论
kami_backend的双因素认证系统通过分层架构实现了安全可靠的TOTP认证机制。系统提供了完整的启用、验证和重置功能，结合了高效的第三方库来处理核心算法，确保了良好的安全性和性能表现。建议定期审查和更新MFA实现，以应对不断变化的安全威胁。