kami_backend/.qoder/repowiki/zh/content/业务逻辑层架构/系统认证逻辑/系统认证逻辑.md

系统认证逻辑

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

目录

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

引言

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

RBAC权限控制系统

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

RBAC模型配置

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

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

Section sources

• rbac_model.conf

用户角色管理

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

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

Section sources

• sys_role.go
• sys_role.go

权限规则与菜单管理

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

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
• sys_auth_rule.go

Section sources

• sys_auth_rule.go
• sys_auth_rule.go

权限验证流程

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

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
• sys_user.go

TOTP双因素认证

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

TOTP实现原理

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

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

Section sources

• mfa.go

TOTP流程

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

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
• totp_set.go
• totp_reset.go

用户登录与会话管理

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

登录流程

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

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
• sys_user.go

Section sources

• sys_user_login.go

会话管理

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

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
• sys_user.go

Section sources

• auth.go

登出流程

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

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

Section sources

• user_login_out.go

权限验证中间件

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

中间件架构

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

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

Section sources

• auth.go

认证流程

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

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

权限配置最佳实践

角色设计原则

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双因素认证和会话管理机制，构建了安全可靠的认证体系。系统采用模块化设计，各组件职责清晰，便于维护和扩展。通过遵循权限配置最佳实践和安全审计建议，可以进一步提升系统的安全性和可靠性。