# 双因素认证

<cite>
**本文档引用的文件**
- [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)
</cite>

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

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

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

**Section sources**
- [mfa.go](file://utility/mfa/mfa.go#L1-L53)
- [sysUser_v1_totp_status_get.go](file://internal/controller/sysUser/sysUser_v1_totp_status_get.go#L1-L37)

## MFA系统架构

```mermaid
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**
- [mfa.go](file://utility/mfa/mfa.go#L1-L53)
- [sys_user.go](file://internal/service/sys_user.go#L1-L102)
- [totp.go](file://internal/logic/sys_user/totp.go#L1-L50)
- [user_info.go](file://internal/logic/base_user_info/user_info.go#L1-L36)

**Section sources**
- [mfa.go](file://utility/mfa/mfa.go#L1-L53)
- [sys_user.go](file://internal/service/sys_user.go#L1-L102)

## TOTP实现机制

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

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

**Diagram sources**
- [mfa.go](file://utility/mfa/mfa.go#L1-L53)
- [sysUser_v1_totp_status_get.go](file://internal/controller/sysUser/sysUser_v1_totp_status_get.go#L1-L37)

### 二维码生成与展示
系统通过`GetOtp`函数生成包含TOTP配置信息的二维码，该二维码可被Google Authenticator等身份验证应用扫描。二维码包含以下信息：
- 用户ID
- 用户名
- 随机生成的密钥
- 服务名称（卡销平台(供销端)）

```mermaid
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**
- [mfa.go](file://utility/mfa/mfa.go#L1-L53)

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

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

**Diagram sources**
- [mfa.go](file://utility/mfa/mfa.go#L1-L53)
- [sysUser_v1_totp_set.go](file://internal/controller/sysUser/sysUser_v1_totp_set.go#L1-L34)

**Section sources**
- [mfa.go](file://utility/mfa/mfa.go#L1-L53)

## MFA功能实现

### MFA启用流程
用户启用MFA需要经过以下步骤：
1. 用户请求获取MFA配置信息
2. 系统生成新的密钥对并返回二维码
3. 用户使用身份验证应用扫描二维码
4. 用户输入当前生成的TOTP验证码进行验证
5. 系统验证成功后保存MFA配置

```mermaid
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**
- [sysUser_v1_totp_status_get.go](file://internal/controller/sysUser/sysUser_v1_totp_status_get.go#L1-L37)
- [sysUser_v1_totp_set.go](file://internal/controller/sysUser/sysUser_v1_totp_set.go#L1-L34)
- [totp.go](file://internal/logic/sys_user/totp.go#L1-L50)

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

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

**Diagram sources**
- [sysUser_v1_totp_reset.go](file://internal/controller/sysUser/sysUser_v1_totp_reset.go#L1-L28)
- [totp.go](file://internal/logic/sys_user/totp.go#L1-L50)

**Section sources**
- [sysUser_v1_totp_set.go](file://internal/controller/sysUser/sysUser_v1_totp_set.go#L1-L34)
- [sysUser_v1_totp_reset.go](file://internal/controller/sysUser/sysUser_v1_totp_reset.go#L1-L28)
- [totp.go](file://internal/logic/sys_user/totp.go#L1-L50)

## 登录流程集成

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

```mermaid
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**
- [sys_user_login_v1_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go#L1-L52)

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

```mermaid
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**
- [sys_user_login_v1_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go#L1-L52)

## 关键操作二次验证

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

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

**Section sources**
- [sysUser_v1_totp_set.go](file://internal/controller/sysUser/sysUser_v1_totp_set.go#L1-L34)

## 配置选项与安全策略

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

```mermaid
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.go](file://utility/mfa/mfa.go#L1-L53)
- [sys_user.go](file://internal/service/sys_user.go#L1-L102)

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

```mermaid
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**
- [mfa.go](file://utility/mfa/mfa.go#L1-L53)
- [sys_user_login_v1_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go#L1-L52)

## 开发者集成指南

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

```mermaid
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**
- [sysUser_v1_totp_status_get.go](file://internal/controller/sysUser/sysUser_v1_totp_status_get.go#L1-L37)
- [sysUser_v1_totp_set.go](file://internal/controller/sysUser/sysUser_v1_totp_set.go#L1-L34)
- [sysUser_v1_totp_reset.go](file://internal/controller/sysUser/sysUser_v1_totp_reset.go#L1-L28)
- [sys_user_login_v1_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go#L1-L52)

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

```mermaid
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**
- [sys_user.go](file://internal/service/sys_user.go#L1-L102)
- [user_info.go](file://internal/logic/base_user_info/user_info.go#L1-L36)
- [mfa.go](file://utility/mfa/mfa.go#L1-L53)

**Section sources**
- [sys_user.go](file://internal/service/sys_user.go#L1-L102)
- [user_info.go](file://internal/logic/base_user_info/user_info.go#L1-L36)

## 用户体验优化建议

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

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

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

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

**Section sources**
- [mfa.go](file://utility/mfa/mfa.go#L1-L53)
- [sysUser_v1_totp_reset.go](file://internal/controller/sysUser/sysUser_v1_totp_reset.go#L1-L28)