跳到主要内容

Identity 领域能力指南

Identity 模块（src/Services/Identity/FreeKit.Identity）基于 ASP.NET Core Identity + FreeSql 构建，提供一整套用户、角色、权限、租户、组织架构、设备与密钥的建模与运行时能力。本文档面向开发者，聚焦"模块提供什么能力、怎么调用、怎么配置"，不罗列实体字段（实体细节可在源码 FreeKit.Identity/Models/Identity 中查阅）。

如果你要的是某一块的深度用法，请跳到对应文档：

1. 能力总览​

功能域能力主要服务接口
认证密码/邮箱验证码登录、注册、注销、刷新 Token、管理员模拟、邮箱校验与改密IAccountService · ITokenHandler · IRefreshTokenService
用户跨身份基础查询（SSO/选主管/通用查找）、资料、头像、改密、改用户名IUserService · IProfileService · IdentityUserManager
角色角色 CRUD、默认/公开/静态角色、数据范围、角色赋权IRoleService
权限权限树、赋权（用户/角色/岗位）、权限检查、角色/用户权限复制IPermissionService · IPermissionManager
租户租户 CRUD、切换、邀请成员、成员列表ITenantService
组织架构组织单元树、职位、员工（含调岗/锁定/重置密码）IOrgUnitService · IPositionService · IEmployeeService
设备登录设备查询/移除、设备信任、新设备验证IUserLoginDeviceManager · IDeviceService
双因素2FA 启用/确认/禁用、登录验证ITwoStepVerificationService · IAuthenticator
安全AccessKey 管理、在线用户、UserToken 吊销、请求日志IUserAccessKeyService · IOnlineUserService · IUserTokenService
社交登录OAuth2 绑定/解绑/登录、OpenIddict 客户端管理IOAuth2Service · IOAuth2AdminService
个性化用户快捷菜单、表格列设置IUserShortcutService · ITableColumnSettingService

注意：没有独立的"用户 CRUD"控制器。UserController（/api/identity/users）只提供列表与详情查询；创建用户走注册（AccountController.register），资料修改走 ProfileController，员工维度的管理走 EmployeeController。

2. 核心服务接口​

开发者在业务代码里通常注入以下 应用服务（均实现 IApplicationService，来自 FreeKit.Identity.Application.*.Contracts）：

  • IAccountService — 登录/注册/邮箱校验/改密/刷新 Token 的编排入口。
  • IUserService — 跨身份基础查询（SSO 选人、选主管、通用按 Id 查找），不负责写。
  • IProfileService — 当前用户资料、头像、昵称、改密码、改用户名。
  • IRoleService / IPermissionService / ITenantService / IOrgUnitService / IPositionService / IEmployeeService — 各自 CRUD（多数实现 ICrudAppService）。
  • IUserAccessKeyService / IOnlineUserService / IUserTokenService / IUserShortcutService / ITableColumnSettingService — 安全与个性化。
  • IOAuth2Service / IOAuth2AdminService — 社交登录与 OpenIddict 客户端。
  • ITwoStepVerificationService / IRefreshTokenService / IUserLoginService / ILinkUserService / ISerilogService / IRequestLogService。

领域层（来自 FreeKit.Identity.Domain）的 Manager 提供更细粒度的建模能力，框架/内部使用较多：

  • IdentityUserManager（命名空间 FreeKit.Identity.Domain.Identity）— ASP.NET Identity 用户管理扩展。
  • IUserLoginDeviceManager（UserLoginDeviceManager）— 设备指纹信任、新设备处理、信任过期（Device:TrustExpireDays）。
  • IPermissionManager — 权限定义初始化与解析（启动时扫描控制器 [Authorize]/[KitAuthorize] 同步权限树）。
  • IdentityLinkUserManager / TwoStepVerificationService（内部聚合，依赖 IdentityUserManager + ITokenHandler）。

3. HTTP API 速查​

所有路由前缀均为 /api/identity/...（宿主前缀如 https://localhost:7002/kit_api 略去）。以下仅列已核实的路由，按控制器分组。

Account — /api/identity/account​

方法路由说明
POST/send_email_code发送注册邮箱验证码
POST/register用户名/邮箱注册
POST/login密码登录，返回 accessToken + refreshToken
POST/verify-device新设备/2FA 验证码校验（携带登录返回的 verifyToken）
POST/impersonate管理员模拟某用户（需权限）
POST/stop-impersonation停止模拟
POST/send_login_verify_code发送邮箱验证码登录的验证码
POST/login_verify_code邮箱验证码登录
POST/refresh_token用 refreshToken 换新 Token
POST/logout注销（吊销当前 Token）
POST/verify_email · /verify_email_comfirm发送/确认邮箱验证
POST/change_email · /change_email_confirm发起/确认改邮箱
POST/set_password设置密码（首次/找回后）
POST/reset_password_email · /reset_password_link_confirm · /reset_password_code_confirm邮箱找回密码流程
GET/captcha · /captchaimg获取验证码（JSON / 图片）

Users — /api/identity/users（仅查询）​

方法路由说明
GET/用户分页列表（UserQuery）
GET/{id:guid}用户详情

Role — /api/identity/role​

方法路由说明
GET/角色列表
GET/{id:guid}角色详情
POST/创建角色
PUT/{id:guid}更新角色
DELETE/{id:guid}删除角色
PUT/grant_role_permission给角色赋权（{id} 在 body）

Permission — /api/identity/permission​

方法路由说明
GET/tree权限树（按 PermissionTreeQuery 过滤）
GET/权限分页列表
GET/{id:guid}权限详情
POST/新建权限节点
PUT/{id:guid}更新权限节点
DELETE/{id:guid}删除权限节点
GET/get_current_grant_permission当前用户已授予权限 Id 列表
GET/get_grant_permission/{userId:guid}指定用户已授予权限 Id
GET/grant_permission按 providerKey + PermissionGrantType 查授予
GET/get_current_grant_permission_code当前用户权限编码列表
GET/get_grant_permission_code/{userId:guid}指定用户权限编码列表
GET/get_grant_permission_group/{userId:guid}按分组返回授予
GET/get_grant_permissions某权限下的授予记录（permissionId）
DELETE/remove_grant_permissions移除授予（List<RemoveGrantPermissionReq>）
POST/grant_permission授予权限（PermissionGrantReq）
POST/check_permission检查当前用户是否有某权限
POST/check_access_token校验 AccessToken 有效性
POST/copy-role-permissions复制角色权限到另一角色
POST/copy-user-permissions复制用户权限
POST/update-sort更新排序

权限类型（PermissionType）：Folder=1 / Menu=2 / Element=3 / Api=4；授予对象类型（PermissionGrantType）：用户 U=5 / 角色 R=10 / 岗位 P=15。

Tenant — /api/identity/tenant​

方法路由说明
GET/租户列表
GET/{id}租户详情
POST/创建租户
PUT/{id}更新租户
DELETE/{id}删除租户
GET/my-tenants当前用户所属租户
POST/switch-tenant/{tenantId?}切换当前租户（返回新 Token）
POST/invite-user-to-tenant按联系方式邀请用户加入租户
POST/invite-user-to-current-tenant邀请到当前租户
GET/members租户成员列表（TenantMemberQuery）

租户解析优先级：X-Tenant-Id 请求头 > JWT 中的 tenant_id 声明。

OrgUnit — /api/identity/orgunit​

方法路由说明
GET/tree组织单元树（OrgUnitTreeDto）
GET/tree2递归组织树
GET/分页列表
GET/{id:guid}详情
POST/创建
PUT/{id:guid}更新
DELETE/{id:guid}删除

组织编码（Code）按层级自动生成（如 00001.00042.00005），对租户唯一、子节点编码以父节点前缀开头。

Position — /api/identity/position​

方法路由说明
GET/职位列表
GET/{id:guid}详情
POST/创建职位（绑定 OrgUnitId）
PUT/{id:guid}更新
DELETE/{id:guid}删除

Employee — /api/identity/employees​

方法路由说明
GET/me当前用户员工信息
GET/员工分页列表
GET/{id:guid}详情
POST/新建员工
PUT/{id:guid}更新
DELETE/{id:guid}删除
PUT/{id:guid}/job-status调整在职/离职/预入职
PUT/{id:guid}/transfer调岗（组织+职位）
PUT/{id:guid}/lockout锁定/解锁
PUT/{id:guid}/reset-password重置密码

Profile — /api/identity/profile​

方法路由说明
POST/verify校验当前令牌
GET/userinfo当前用户资料（UserInformation）
GET/session会话信息（UserSessionInformation）
PUT/set_avatar设置头像（avatarKey）
PUT/set_username修改用户名
PUT/set_nickname修改昵称
GET/avatar/{userId}取某用户头像 URL
GET/{userId}取公开用户摘要（OpenUserDto）
PUT/change_password修改密码
PUT/update_profile_info更新资料（真实姓名/性别等）

OAuth2 — /api/identity/oauth2​

方法路由说明
GET/external-providers可用外部登录提供商列表
GET/signin发起第三方登录（provider + redirectUrl）
GET/signin-callback · /signin-bind-callback登录/绑定回调
GET/signin-bind绑定到已登录账号
GET/signout退出第三方
POST/exchange-oauth-code用授权码换取 JWT（ExchangeOAuthCodeReq）
GET/OpenId · /GetOpenIdByToken取第三方 OpenId
GET/bindlist当前用户已绑定列表
DELETE/unbind/{id}解绑

设备 / 2FA / 在线 / 密钥（其余控制器）​

控制器前缀已核实路由要点
DeviceController/api/identity/deviceGET /devices、DELETE /devices/{deviceId}、GET /devices/is-trusted、GET /preview/new_device_login
TwoStepVerificationController/api/identity/twostepverificationPOST /enable_2fa、POST /enable_2fa_confirm、POST /disable_2fa、POST /2fa_verification_login、POST /2fa_verification_login_confirm
OnlineUserController/api/identity/onlineuserGET /send-alert、GET /（列表）、DELETE /（批量下线）、DELETE /{id:guid}（强制下线）
UserAccessKeyController/api/identity/useraccesskeyGET /、GET /logs、GET /{id}、POST /、PUT /{id}、DELETE /{id}
UserTokenController/api/identity/usertokenGET /、GET /{id}、DELETE /{id}、DELETE /batch
LogController/api/identity/logSerilog 日志与 RequestLog 查询/删除/清空
OpenIddictAdminController/api/identity/openiddictOpenIddict 应用/作用域/令牌的 CRUD 与吊销
SettingDefinitionController/api/identity/settingdefinition权限定义式设置在 Identity 侧的可见定义查询
TableColumnSettingController/api/identity/table-column-settings用户表格列个性化 GET/PUT/DELETE {tableUid}、POST /batch-get
UserShortcutController/api/identity/usershortcutPOST /（新增快捷）、GET /（列表）

4. 配置​

认证与 Token​

{
  "Authentication": {
    "ExpiresTime": 86400,            // AccessToken 有效期（秒），由 TokenHandler 读取
    "RefreshExpiresIn": 2592000      // RefreshToken 有效期（秒）
  }
}

TokenHandler 还会回退读取 Authentication:0:Schemes:ExpiresTime / Authentication:0:ExpiresIn 等多方案配置键。

设备信任​

  • Device:TrustExpireDays（默认 180 天）：信任设备有效期；到期需重新验证。由 UserLoginDeviceManager 读取。
  • 新设备行为由设置 Device.NewDeviceMode 控制，取值 notify（仅邮件通知）或 verify（要求邮箱验证码）；默认 notify。LoginService 在登录时读取该值决定流程。

密码与锁定策略（IdentityOptions）​

在 IdentityModuleStartup 中通过 AddIdentityCore<IdentityUser> 配置，等价于标准 ASP.NET Identity 选项：

{
  "IdentityOptions": {
    "Password": {
      "RequiredLength": 8,
      "RequireDigit": true,
      "RequireLowercase": true,
      "RequireUppercase": false,
      "RequireNonAlphanumeric": false
    },
    "Lockout": {
      "MaxFailedAccessAttempts": 5,
      "DefaultLockoutTimeSpan": "00:30:00"
    }
  }
}

注册与接入​

// Program.cs —— 框架自动发现并启动 IdentityModuleStartup
builder.Services.AddFreeKitCore();   // 基础能力
// Identity 宿主在启动时自动注册 IdentityModuleStartup（含上述 IdentityOptions、FreeSql、SignalR 等）
dotnet run --project src/Services/Identity/FreeKit.Identity.Host
# Swagger: https://localhost:7002/kit_api/swagger

5. 开发示例​

// 注入应用服务即可调用（示例：给当前用户授予某个权限）
public class MyService(IPermissionService permissionService, IUserService userService)
{
    public async Task GrantAsync(Guid userId, string[] codes)
    {
        await permissionService.GrantPermissionAsync(new PermissionGrantReq
        {
            ProviderKey = userId.ToString(),
            PermissionGrantType = PermissionGrantType.U, // 用户级
            PermissionNames = codes
        });
    }
}
# 密码登录
curl -X POST https://localhost:7002/kit_api/api/identity/account/login \
  -H "Content-Type: application/json" \
  -d '{"userNameOrEmail":"admin","password":"123456"}'

# 取权限树
curl https://localhost:7002/kit_api/api/identity/permission/tree

# 切换租户
curl -X POST https://localhost:7002/kit_api/api/identity/tenant/switch-tenant/{tenantId}

相关文档​