跳到主要内容

FreeKit.Identity 模块文档

1. 模块概述​

FreeKit.Identity 是一个功能完整的身份认证与授权模块，提供用户管理、组织管理、权限管理等核心功能，支持多租户架构，适用于企业级应用系统。

1.1 核心功能​

  • 用户管理：用户注册、登录、个人资料管理、密码重置
  • 组织管理：组织机构（部门）管理、岗位管理
  • 权限管理：角色管理、权限分配、授权管理
  • 认证与授权：JWT令牌认证、基于角色的访问控制
  • 在线用户管理：实时在线用户监控
  • 访问密钥管理：API访问密钥的生成与管理
  • 请求日志：用户操作日志记录

1.2 技术架构​

  • 基于 ASP.NET Core 构建
  • 使用 FreeSql 作为 ORM 框架
  • 支持多租户架构
  • 集成 JWT 认证
  • 采用 MediatR 实现命令和查询分离

2. 核心实体​

2.1 用户相关实体​

  • IdentityUser：用户基本信息
  • IdentityRole：角色信息
  • IdentityUserRole：用户与角色关联
  • IdentityUserClaim：用户声明
  • IdentityRoleClaim：角色声明
  • IdentityUserLogin：第三方登录与账号绑定信息，可复用承载 GitHub、Gitee、QQ、微信

2.2 组织相关实体​

  • OrgUnit：组织机构（部门）
  • Position：岗位
  • UserOrgUnit：用户与部门关联
  • UserPosition：用户与岗位关联

2.3 认证相关实体​

  • UserAccessToken：用户访问令牌
  • RefreshToken：刷新令牌
  • UserAccessKey：API访问密钥
  • UserAccessKeyLog：API访问密钥使用日志

2.4 权限相关实体​

  • Permission：权限
  • PermissionGrant：权限授权

2.5 其他实体​

  • OnlineUser：在线用户
  • RequestLog：请求日志
  • UserShortcut：用户快捷方式
  • KitApp：应用

3. 核心功能模块​

3.1 认证模块​

3.1.1 登录流程​

  1. 用户输入用户名/邮箱和密码
  2. 系统验证用户凭据
  3. 验证用户状态（是否激活、是否冻结）
  4. 生成JWT访问令牌和刷新令牌
  5. 返回令牌信息给客户端

3.1.2 注册流程​

  1. 用户提交注册信息
  2. 系统验证信息合法性
  3. 创建用户账号
  4. 生成初始密码
  5. 发送激活邮件（可选）

3.1.3 令牌管理​

  • 访问令牌：用于API认证，有效期较短
  • 刷新令牌：用于刷新访问令牌，有效期较长
  • 令牌撤销：支持手动撤销令牌

3.2 用户管理模块​

3.2.1 用户CRUD操作​

  • 创建用户
  • 查询用户列表
  • 更新用户信息
  • 删除用户

3.2.2 个人资料管理​

  • 更新个人信息
  • 修改密码
  • 上传头像

3.3 组织管理模块​

3.3.1 组织机构管理​

  • 创建部门
  • 编辑部门信息
  • 部门层级管理
  • 部门负责人设置

3.3.2 岗位管理​

  • 创建岗位
  • 编辑岗位信息
  • 岗位编制管理
  • 主管岗位设置

3.4 权限管理模块​

3.4.1 角色管理​

  • 创建角色
  • 编辑角色信息
  • 设置默认角色
  • 角色权限分配

3.4.2 权限管理​

  • 创建权限
  • 权限层级管理
  • 权限分类（目录、菜单、元素、API）

3.4.3 授权管理​

  • 角色授权
  • 用户授权
  • 权限继承

3.5 在线用户管理​

  • 实时在线用户监控
  • 用户会话管理
  • 强制用户下线

3.6 访问密钥管理​

  • 生成访问密钥
  • 密钥状态管理
  • 密钥使用日志

3.7 请求日志管理​

  • 记录用户操作日志
  • 日志查询与分析
  • 异常操作监控

4. API参考​

详细的API接口参考请查看 APIReference 文件。

5. 配置与部署​

5.1 配置项​

  • JWT配置：密钥、过期时间等
  • 密码策略：复杂度要求、过期时间等
  • 多租户配置：是否启用多租户
  • 日志配置：日志级别、存储方式等

5.2 部署方式​

  • 独立部署：作为独立的身份服务
  • 集成部署：与其他模块一起部署
  • Docker部署：容器化部署

6. 使用示例​

6.1 登录示例​

// 登录请求
var loginCommand = new LoginCommand("admin", "Password123!");
var token = await mediator.Send(loginCommand);

// 使用令牌
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token.AccessToken);

6.2 创建用户示例​

// 创建用户请求
var createUserCommand = new CreateUserCommand
{
    UserName = "user1",
    Email = "user1@example.com",
    Password = "Password123!",
    Name = "User One"
};
var user = await mediator.Send(createUserCommand);

6.3 分配角色示例​

// 分配角色请求
var assignRoleCommand = new AssignRoleCommand
{
    UserId = userId,
    RoleIds = new List<Guid> { roleId1, roleId2 }
};
await mediator.Send(assignRoleCommand);

7. 最佳实践​

7.1 安全最佳实践​

  • 使用HTTPS保护API通信
  • 实施密码复杂度要求
  • 定期轮换访问密钥
  • 限制登录尝试次数
  • 启用多因素认证（可选）

7.2 性能最佳实践​

  • 使用缓存减少数据库查询
  • 优化令牌验证过程
  • 合理设置令牌过期时间
  • 批量操作减少API调用

7.3 维护最佳实践​

  • 定期清理过期令牌
  • 监控异常登录行为
  • 备份用户数据
  • 记录关键操作日志

8. 常见问题与解决方案​

8.1 登录失败​

  • 检查用户名和密码是否正确
  • 检查用户状态是否激活
  • 检查账号是否被冻结

8.2 权限不足​

  • 检查用户是否拥有相应权限
  • 检查角色权限配置是否正确
  • 检查权限继承关系

8.3 令牌过期​

  • 使用刷新令牌获取新的访问令牌
  • 检查令牌过期时间配置
  • 实现自动刷新令牌机制

9. 未来规划​

  • 支持更多认证方式（OAuth2、OpenID Connect等）
  • 实现细粒度权限控制
  • 集成第三方身份提供商
  • 增强安全审计功能
  • 提供更多的用户管理功能