跳到主要内容

Identity 功能说明

本文档从"业务能力 + 设计动机"的角度拆解 Identity 模块的每个子域。它不罗列端点——具体 HTTP 接口请看 Swagger，实体字段请看源码；这里只讲"能做什么、为什么这样设计、典型业务场景"。

认证方式​

密码登录​

最基础的登录方式，支持用户名或邮箱。登录流程在 AccountService 中编排：

  1. 校验验证码（若开启）。
  2. 按用户名/邮箱查找用户、校验密码。
  3. 检查设备信任状态（见 设备验证）。
  4. 按设备状态与 2FA 设置决定下一步：
    • 可信设备 + 无 2FA → 直接签发 Token；
    • 不可信设备 + 无 2FA → 按 Device.NewDeviceMode 发通知或要求验证；
    • 启用 2FA → 始终要求验证码。

设计动机：验证与签发分离——ITokenHandler 专职签发/校验 JWT，IRefreshTokenService 管理刷新令牌轮换，AccountService 只做编排，使 Token 策略可独立演进。

邮箱验证码登录​

无需密码，凭邮箱收到的验证码登录（先 send_login_verify_code 取码，再 login_verify_code 校验）。与密码登录共用同一套设备/2FA 决策。

OAuth2 社交登录​

支持 GitHub / Gitee / QQ / 微信 / Google / Microsoft / KitSSO 等提供商。第三方账号通过 IdentityUserLogin 绑定到同一 IdentityUser，保证"多种登录方式 = 同一个身份"。

业务场景：已登录用户可在"账号绑定"页把第三方账号绑到当前用户；未登录用户走第三方首次登录会自动创建/关联 IdentityUser。

管理员模拟​

管理员可临时"变成"某用户操作（需相应权限），AccountService.ImpersonateAsync 会把 impersonator 与原始租户写入 Token Claim，便于审计与回退。

用户与资料​

  • 用户查询：IUserService 提供只读的跨身份查询（SSO 选人、选主管、按 Id 查找），UserController 仅两个 HttpGet。
  • 资料维护：IProfileService 负责当前用户资料、头像、昵称、改密码、改用户名。
  • 生命周期拆分：用户创建走注册、资料走 Profile、员工维度走 Employee——没有"用户 CRUD"控制器。

角色管理​

角色把权限分组后分配给用户。能力包括：角色 CRUD、默认角色（注册自动分配）、公开角色（其他用户可见）、静态角色（内置不可删），以及数据范围 DataScope（控制可触及的数据边界）。赋权走 PermissionGrant(R)。

权限管理​

权限控制"用户能执行什么操作"。权限树用 PermissionType 分层：Folder(目录) / Menu(UI 菜单) / Element(按钮) / Api(后端接口)。

  • 权限树与代码强一致：启动时 PermissionManager 反射扫描所有控制器的 [Authorize(Policy=...)] 与 [KitAuthorize]，把受保护接口同步成权限节点，避免手工维护漂移。
  • 授予对象多态：PermissionGrant 通过 PermissionGrantType 区分 U(用户)/R(角色)/P(岗位)，解析时三来源合并生效；并支持角色/用户权限复制。

租户管理​

多租户用于单一应用内隔离不同租户数据。租户解析优先级为 X-Tenant-Id 请求头 > JWT tenant_id 声明（IdentityTenantResolver）；切换租户会重新签发 Token 并写入新声明。租户还支持邀请成员、成员列表。

组织架构​

  • 组织单元（OrgUnit）：层级部门树（ParentId 自引用），组织编码 Code 按层级自动生成（如 00001.00042.00005），对租户唯一、子节点编码以父节点前缀开头。
  • 职位（Position）：依附于某个 OrgUnit，含编制 HeadCount 与是否主管岗。
  • 员工（EmployeeInfo）：真正承载"某人在某部门任某岗"的档案（UserId + OrgUnitId + PositionId + LeaderUserId），支持调岗（组织+职位）、锁定/解锁、重置密码、在职状态流转。

设计动机：用户身份稳定，而人在组织中的位置会变化。把员工维度独立出来，使调岗/离职不影响登录身份，也避免用户表被组织字段污染。

设备管理​

设备记录与信任逻辑由领域服务 IUserLoginDeviceManager 实现，内嵌于登录流程（无独立 REST 端点）。设备指纹基于 UserAgent 的 SHA256 哈希（IP 变化不影响识别）；受信设备默认 180 天（Device:TrustExpireDays）后过期；新设备按 Device.NewDeviceMode（notify/verify）决策。详见 设备验证。

双因素验证​

2FA 开启时登录一律要求验证码（TwoStepVerificationService 通过邮件发码），并与"未受信设备"共用同一套 VerifyToken 验证通道，逻辑统一。能力包括启用（发确认邮件）、确认、禁用、登录验证。

在线用户与密钥​

  • 在线用户：基于 SignalR 连接跟踪在线状态，支持强制单个/批量下线（会级联吊销其 Token）。
  • AccessKey：给用户/服务一套长期可用的 API 密钥（AccessKeyId/Secret + 状态 + 最近使用时间 + 操作日志），与用户会话 Token 解耦，适合脚本或微服务间调用。

相关文档​