# 系统认证逻辑

<cite>
**本文档引用的文件**
- [rbac_model.conf](file://resource/casbin/rbac_model.conf)
- [auth.go](file://internal/middleware/auth.go)
- [mfa.go](file://utility/mfa/mfa.go)
- [sys_user.go](file://internal/logic/sys_user/sys_user.go)
- [sys_casbin.go](file://internal/logic/sys_casbin/sysCasbin.go)
- [sys_role.go](file://internal/service/sys_role.go)
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go)
- [sysUser.go](file://internal/model/sys_user.go)
- [sys_role.go](file://internal/model/sys_role.go)
- [sys_auth_rule.go](file://internal/model/sys_auth_rule.go)
- [sys_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go)
- [sysUser.go](file://internal/controller/sysUser/sysUser.go)
- [user_login_out.go](file://internal/controller/sysUser/sysUser_v1_user_login_out.go)
- [totp_set.go](file://internal/controller/sysUser/sysUser_v1_totp_set.go)
- [totp_reset.go](file://internal/controller/sysUser/sysUser_v1_totp_reset.go)
</cite>

## 目录
1. [引言](#引言)
2. [RBAC权限控制系统](#rbac权限控制系统)
3. [TOTP双因素认证](#totp双因素认证)
4. [用户登录与会话管理](#用户登录与会话管理)
5. [权限验证中间件](#权限验证中间件)
6. [权限配置最佳实践](#权限配置最佳实践)
7. [安全审计建议](#安全审计建议)
8. [结论](#结论)

## 引言
kami_backend系统采用基于Casbin的RBAC（基于角色的访问控制）权限模型，结合TOTP双因素认证机制，构建了完整的系统认证体系。该系统实现了用户角色、权限规则和菜单权限的精细化管理，确保了系统的安全性和可扩展性。本文档详细阐述了认证业务逻辑的实现细节，包括权限控制、双因素认证、会话管理等核心功能。

## RBAC权限控制系统

kami_backend系统采用Casbin作为权限控制引擎，实现了基于角色的访问控制（RBAC）模型。该系统通过定义用户、角色和权限之间的关系，实现了灵活的权限管理机制。

### RBAC模型配置
系统使用`rbac_model.conf`文件定义了RBAC模型的核心规则：

```mermaid
classDiagram
class CasbinModel {
+request_definition : r = sub, obj, act
+policy_definition : p = sub, obj, act
+role_definition : g = _, _
+policy_effect : e = some(where (p.eft == allow))
+matchers : m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act
}
```

**Diagram sources**
- [rbac_model.conf](file://resource/casbin/rbac_model.conf#L1-L13)

**Section sources**
- [rbac_model.conf](file://resource/casbin/rbac_model.conf#L1-L13)

### 用户角色管理
系统通过`ISysRole`接口提供角色管理功能，包括角色的创建、编辑、删除和权限分配。角色与用户通过Casbin的分组策略（Grouping Policy）进行关联。

```mermaid
classDiagram
class ISysRole {
+GetRoleListSearch(ctx, req) res, err
+GetRoleList(ctx) list, err
+AddRoleRule(ctx, ruleIds, roleId) err
+DelRoleRule(ctx, roleId) err
+AddRole(ctx, req) err
+Get(ctx, id) res, err
+GetFilteredNamedPolicy(ctx, id) gpSlice, err
+EditRole(ctx, req) err
+DeleteByIds(ctx, ids) err
}
```

**Diagram sources**
- [sys_role.go](file://internal/service/sys_role.go#L14-L30)

**Section sources**
- [sys_role.go](file://internal/service/sys_role.go#L14-L30)
- [sys_role.go](file://internal/model/sys_role.go#L1-L20)

### 权限规则与菜单管理
系统通过`ISysAuthRule`接口管理权限规则和菜单结构。权限规则分为目录、菜单和按钮三种类型，通过树形结构组织。

```mermaid
classDiagram
class ISysAuthRule {
+GetMenuListSearch(ctx, req) res, err
+GetIsMenuList(ctx) list, err
+GetMenuList(ctx) list, err
+GetIsButtonList(ctx) list, err
+Add(ctx, req) err
+BindRoleRule(ctx, ruleId, roleIds) err
+Get(ctx, id) rule, err
+GetMenuRoles(ctx, id) roleIds, err
+Update(ctx, req) err
+UpdateRoleRule(ctx, ruleId, roleIds) err
+GetMenuListTree(pid, list) tree
+DeleteMenuByIds(ctx, ids) err
+FindSonByParentId(list, pid) children
}
class SysAuthRule {
+CommonIntId
+Name string
+Title string
+MenuType uint
+Weigh int
+IsHide uint
+Path string
+IdAdmin int
+Component string
+Children []*SysAuthRule
}
ISysAuthRule --> SysAuthRule : "使用"
```

**Diagram sources**
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go#L14-L34)
- [sys_auth_rule.go](file://internal/model/sys_auth_rule.go#L7-L10)

**Section sources**
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go#L14-L34)
- [sys_auth_rule.go](file://internal/model/sys_auth_rule.go#L7-L40)

### 权限验证流程
当用户请求访问系统资源时，权限验证流程如下：

```mermaid
sequenceDiagram
participant User as "用户"
participant Middleware as "权限中间件"
participant Casbin as "Casbin引擎"
participant Database as "数据库"
User->>Middleware : 发起请求
Middleware->>Casbin : 获取用户角色
Casbin->>Database : 查询用户角色关联
Database-->>Casbin : 返回角色ID列表
Casbin->>Database : 查询角色权限规则
Database-->>Casbin : 返回权限规则
Casbin->>Middleware : 验证权限
Middleware->>User : 返回访问结果
Note over Middleware,Casbin : 基于Casbin的RBAC权限验证
```

**Diagram sources**
- [auth.go](file://internal/middleware/auth.go#L1-L154)
- [sys_user.go](file://internal/logic/sys_user/sys_user.go#L1-L766)

## TOTP双因素认证

系统集成了TOTP（基于时间的一次性密码）双因素认证机制，增强了账户安全性。TOTP实现基于HOTP（HMAC-based One-time Password）算法，使用SHA-1哈希函数生成一次性密码。

### TOTP实现原理
系统使用`gotp`库实现TOTP功能，生成6位数字的一次性密码，每30秒更新一次。

```mermaid
classDiagram
class Otp {
+Secret string
+QrImage string
+Key string
}
class Mfa {
+GetOtp(userId, username, key, secret) otp, err
+ValidCode(code, secret) bool
}
Mfa --> Otp : "生成"
```

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

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

### TOTP流程
TOTP双因素认证的完整流程包括密钥生成、二维码展示、验证和重置：

```mermaid
sequenceDiagram
participant User as "用户"
participant System as "系统"
participant Mfa as "MFA模块"
User->>System : 请求启用TOTP
System->>Mfa : 生成TOTP密钥
Mfa->>System : 返回密钥和二维码
System->>User : 展示二维码
User->>System : 扫描二维码并输入验证码
System->>Mfa : 验证验证码
Mfa->>System : 返回验证结果
System->>User : 启用/禁用TOTP
Note over System,Mfa : TOTP双因素认证流程
```

**Diagram sources**
- [mfa.go](file://utility/mfa/mfa.go#L1-L52)
- [totp_set.go](file://internal/controller/sysUser/sysUser_v1_totp_set.go#L1-L32)
- [totp_reset.go](file://internal/controller/sysUser/sysUser_v1_totp_reset.go#L1-L26)

## 用户登录与会话管理

系统实现了完整的用户登录、登出和会话管理机制，确保用户会话的安全性和可靠性。

### 登录流程
用户登录流程包括验证码验证、身份认证和Token生成：

```mermaid
sequenceDiagram
participant User as "用户"
participant Controller as "登录控制器"
participant Service as "用户服务"
participant Token as "Token服务"
User->>Controller : 提交登录请求
Controller->>Service : 验证验证码
Service->>Service : 验证用户名密码
Service->>Service : 验证TOTP(如果启用)
Service->>Token : 生成用户Token
Token->>Controller : 返回Token
Controller->>User : 返回登录结果
Note over Controller,Service : 用户登录流程
```

**Diagram sources**
- [sys_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go#L1-L50)
- [sys_user.go](file://internal/logic/sys_user/sys_user.go#L1-L766)

**Section sources**
- [sys_user_login.go](file://internal/controller/sys_user_login/sys_user_login_v1_user_login.go#L1-L50)

### 会话管理
系统使用JWT Token进行会话管理，Token存储在Redis中，支持自动续签和强制失效。

```mermaid
classDiagram
class UserToken {
+UserID string
+ID string
+Username string
+ExpireTime int64
}
class TokenService {
+GenerateUserToken(ctx, username, userId) tokenStr, err
+ParseUserToken(ctx, tokenStr) userToken, err
+RefreshUserToken(ctx, userToken) newToken, err
+GetTokenFromRedis(ctx, userId, tokenId) tokenStr, err
+DeleteTokenFromRedis(ctx, userId) err
}
TokenService --> UserToken : "使用"
```

**Diagram sources**
- [auth.go](file://internal/middleware/auth.go#L1-L154)
- [sys_user.go](file://internal/logic/sys_user/sys_user.go#L1-L766)

**Section sources**
- [auth.go](file://internal/middleware/auth.go#L1-L154)

### 登出流程
用户登出时，系统会从Redis中删除对应的Token，使会话立即失效：

```mermaid
sequenceDiagram
participant User as "用户"
participant Controller as "登出控制器"
participant Token as "Token服务"
User->>Controller : 发起登出请求
Controller->>Token : 解析Token
Token->>Controller : 返回用户信息
Controller->>Token : 删除Redis中的Token
Token->>Controller : 返回删除结果
Controller->>User : 返回登出成功
Note over Controller,Token : 用户登出流程
```

**Diagram sources**
- [user_login_out.go](file://internal/controller/sysUser/sysUser_v1_user_login_out.go#L1-L18)

**Section sources**
- [user_login_out.go](file://internal/controller/sysUser/sysUser_v1_user_login_out.go#L1-L18)

## 权限验证中间件

系统通过中间件机制实现权限验证，支持多种认证方式和白名单机制。

### 中间件架构
权限验证中间件采用分层设计，支持登录认证、iframe认证和白名单认证：

```mermaid
classDiagram
class AuthMiddleware {
+LoginOrIframeAuth(r)
+loginAuth(r) code
+iFrameAuth(r) code
+whiteListAuth(r) code
}
class TokenService {
+GetRequestToken(r) tokenStr
+ParseUserToken(ctx, tokenStr) userToken, err
+RefreshUserToken(ctx, userToken) newToken, err
}
class ConfigService {
+NewConfig(ctx) cfg, err
+GetFrontendSecret() frontendModel, err
}
class VerifyService {
+AesCBCURLDecryptWithBase64(tokenStr, key, iv) tokenByte, err
}
AuthMiddleware --> TokenService : "使用"
AuthMiddleware --> ConfigService : "使用"
AuthMiddleware --> VerifyService : "使用"
```

**Diagram sources**
- [auth.go](file://internal/middleware/auth.go#L1-L154)

**Section sources**
- [auth.go](file://internal/middleware/auth.go#L1-L154)

### 认证流程
权限验证中间件的执行流程如下：

```mermaid
flowchart TD
Start([请求进入]) --> CheckWhiteList["检查白名单"]
CheckWhiteList --> IsWhiteList{"是否在白名单?"}
IsWhiteList --> |是| AllowAccess["允许访问"]
IsWhiteList --> |否| GetTokenFrom["获取Token来源"]
GetTokenFrom --> IsLogin{"来源为login?"}
IsLogin --> |是| LoginAuth["执行登录认证"]
IsLogin --> |否| IsIframe{"来源为iframe?"}
IsIframe --> |是| IFrameAuth["执行Iframe认证"]
IsIframe --> |否| ReturnError["返回来源不明错误"]
LoginAuth --> AuthResult{"认证成功?"}
IFrameAuth --> AuthResult
AuthResult --> |是| AllowAccess
AuthResult --> |否| ReturnAuthError["返回认证错误"]
AllowAccess --> End([继续处理])
ReturnAuthError --> End
ReturnError --> End
```

**Diagram sources**
- [auth.go](file://internal/middleware/auth.go#L1-L154)

## 权限配置最佳实践

### 角色设计原则
1. **最小权限原则**：每个角色只分配完成其职责所需的最小权限
2. **职责分离**：敏感操作应由不同角色共同完成，避免权限过度集中
3. **层级化设计**：建立角色层级结构，便于权限继承和管理

### 权限规则配置
1. **细粒度控制**：将权限细化到具体操作级别（如创建、读取、更新、删除）
2. **命名规范**：使用统一的命名规范，如`资源名/操作类型`
3. **定期审查**：定期审查权限配置，移除不再需要的权限

### 菜单管理
1. **动态加载**：根据用户角色动态加载菜单，避免信息泄露
2. **权限同步**：菜单显示与后端权限验证保持同步
3. **用户体验**：合理组织菜单结构，提升用户体验

## 安全审计建议

### 认证安全
1. **密码策略**：实施强密码策略，包括长度、复杂度和定期更换要求
2. **失败处理**：对连续登录失败实施账户锁定或延迟机制
3. **会话保护**：使用安全的Cookie属性（HttpOnly、Secure）保护会话

### TOTP安全
1. **密钥保护**：确保TOTP密钥在传输和存储过程中的安全性
2. **备份机制**：提供恢复码或备用验证方式，防止用户丢失设备
3. **防暴力破解**：对TOTP验证尝试实施速率限制

### 权限审计
1. **操作日志**：记录所有权限相关的操作，包括角色分配、权限变更等
2. **定期审查**：定期审查用户权限分配，确保符合最小权限原则
3. **异常检测**：监控异常的权限使用模式，及时发现潜在安全威胁

## 结论
kami_backend系统的认证业务逻辑通过RBAC权限控制、TOTP双因素认证和会话管理机制，构建了安全可靠的认证体系。系统采用模块化设计，各组件职责清晰，便于维护和扩展。通过遵循权限配置最佳实践和安全审计建议，可以进一步提升系统的安全性和可靠性。