企业统一身份认证中心需求说明
IAM 首先解决一个问题：内部员工使用企业微信统一登录业务系统，管理员能够控制哪些人可以访问哪些应用，并在人员禁用或离职后阻止继续登录和获取新令牌。
版本：1.2 修订稿。更新日期：2026-10-27。本文基于原始需求按业务优先级重写，定义目标与验收条件，不代表当前代码已经全部实现或上线。
1 优先级与交付范围
Section titled “1 优先级与交付范围”| 优先级 | 含义 | 交付原则 |
|---|---|---|
| P0 | 第一阶段必须完成的 IAM 核心功能 | 优先开发与验收，五项均满足后完成第一阶段交付 |
| P1 | 核心功能之后的使用完善 | 不阻塞 P0；已有能力可继续使用，无需为分期而删除 |
| P2 | 后续按实际需要决定的能力 | 暂不确定方案、指标和排期，不作为第一阶段前置条件 |
第一阶段仅服务内部人员。外部访客、外包账号管理不纳入需求。IAM 不承担 OA、CRM 等系统内部的菜单、按钮及业务数据权限管理。
| 编号 | 优先级 | 核心功能 | 业务结果 |
|---|---|---|---|
| IAM-01 | P0 | 统一登录 | 员工通过企业微信登录并进入已接入的业务系统 |
| IAM-02 | P0 | 人员与组织同步 | IAM 能获取企微员工、部门和离职状态，保持身份一致 |
| IAM-03 | P0 | 应用接入管理 | 管理员能够注册应用、配置回调并交付接入凭据 |
| IAM-04 | P0 | 应用访问控制 | 管理员可以按人员或部门决定谁能登录哪个应用 |
| IAM-05 | P0 | 基本账号控制 | 能禁用账号、撤销 IAM 会话，并阻止离职人员继续登录和刷新令牌 |
2 P0 第一阶段必须完成
Section titled “2 P0 第一阶段必须完成”IAM-01 统一登录
Section titled “IAM-01 统一登录”要做什么
- 员工通过企业微信扫码或快速登录 IAM，不开放匿名自行注册。
- 通过标准 OIDC 授权码流程及 PKCE 对接业务应用，首批对接对象为 OA、CRM。
- 员工已有有效 IAM 登录态时，进入另一个有访问权限的应用无需再次扫码；会话过期后重新登录。
- 使用稳定的 IAM 用户 ID 识别员工，不因姓名、邮箱或部门变化创建另一个身份。
- 复用现有资料补全和邮箱验证流程，为需要按邮箱首次绑定的应用提供已验证邮箱。绑定完成后，应用使用稳定的
issuer + sub识别用户。 - 登录失败、身份不符或应用无权限时，给出明确提示。
怎样算完成
- 在职员工能通过企业微信登录 IAM，再分别完成 OA、CRM 的登录联调。
- 同一浏览器已有 IAM 会话时，进入另一个获准应用无需重复扫码。
- 重复登录不会重复建号；修改姓名或邮箱不会串到其他业务账号。
- 取消扫码、回调失效或认证失败时，不创建有效登录态，也不进入业务应用。
IAM-02 人员与组织同步
Section titled “IAM-02 人员与组织同步”要做什么
- 从企业微信同步员工、部门、父子部门关系和员工所属部门，支持成员属于多个部门。
- 支持首次全量同步、企微回调更新，以及手动或定时全量核对。
- 管理员可查看部门树、人员列表、人员状态和同步结果，按部门筛选或姓名搜索。
- 接收到明确的离职或禁用状态后更新 IAM，并联动 IAM-05。
- 企业微信负责人员与组织信息，IAM 管理员负责平台权限和应用准入；同步不得自动提升平台权限或解除本地封禁。
- 同步失败保留错误信息并允许重试，不因上游超时或不完整结果把所有未返回人员认定为离职。
怎样算完成
- 首次同步后，可查询员工及其部门；重复同步不会重复创建人员或部门。
- 员工新增、调部门后，IAM 能通过回调或全量核对更新结果。
- 员工被确认离职后，IAM 展示对应状态并执行账号限制。
- 同步失败可查看原因并重新执行，不错误删除或批量停用正常员工。
精确到秒的同步时效、复杂告警和多级补偿属于 P2，不阻塞上述功能验收。
IAM-03 应用接入管理
Section titled “IAM-03 应用接入管理”要做什么
- 由平台管理员集中管理应用，维护名称、描述、回调地址和启用状态。
- 生成 Client ID，以及机密客户端需要的 Client Secret；支持管理员重置 Secret。
- 提供 issuer、Discovery 地址和基本接入说明，供应用负责人完成对接。
- 严格匹配登记的回调地址；测试和生产环境分别配置凭据及地址。
- 禁用应用后，拒绝该应用的新授权和令牌获取，包括刷新请求。
- Secret 仅在必要的生成或重置流程中安全交付，不出现在普通列表、日志或业务前端代码中。
怎样算完成
- 管理员能创建应用，并使用生成的参数完成 OIDC 登录。
- 未登记或被篡改的回调地址不能通过授权。
- 禁用应用后，不能再获取授权码或令牌。
- 重置 Secret 后，旧 Secret 无法继续认证客户端，新 Secret 可正常使用。
- 普通用户不能通过修改请求参数注册、修改或删除应用配置。
第一阶段采用管理员集中管理。应用创建者和委派管理员的精细权限治理列入 P2，不作为新增应用接入的前置工作；普通用户不得因此获得平台管理权。
IAM-04 应用访问控制
Section titled “IAM-04 应用访问控制”要做什么
- 管理员按用户或部门配置应用访问范围，部门授权可选择是否包含子部门。
- 普通用户通过“我的应用”查看可访问的应用并发起登录。
- 无任何允许规则时默认拒绝；用户被显式拒绝时，不被部门允许规则覆盖。
- 授权规则在服务端执行，不仅隐藏前端入口；直接访问授权地址不能绕过检查。
- 撤销访问范围后，拒绝该用户对该应用的新授权、授权码换令牌和刷新请求。
- 平台管理员也按应用准入规则登录业务系统，不因平台身份自动获得业务访问权。
怎样算完成
- 授权指定用户后，该用户可以登录应用，未授权用户不能登录。
- 部门授权及包含子部门开关对相应成员生效。
- 同时命中用户拒绝和部门允许时，仍拒绝访问。
- 用户直接构造应用授权地址，仍需通过相同的访问检查。
- 撤销用户访问范围后，不能通过新的授权请求、已持有授权码或刷新令牌继续获取该应用的新令牌。
第一阶段只要求明确“能否访问”。业务系统自行管理角色与业务权限，不要求把现有 RBAC 搬到 IAM。已有应用角色配置继续使用时，保留用户直接分配优先于部门分配、部门角色冲突时拒绝登录的规则；复杂角色映射不纳入 P0。
IAM-05 基本账号控制
Section titled “IAM-05 基本账号控制”要做什么
- 平台管理员能够禁用、解禁员工账号，查看并撤销员工的 IAM 会话。
- 账号禁用或确认离职后，撤销 IAM 会话及用户 OAuth 凭据，包括离线刷新令牌。
- 登录、授权码换令牌及刷新入口均检查账号状态；不能通过备用密码登录或旧刷新令牌绕过禁用和离职限制。
- 管理员撤销 IAM 会话后，该会话不能继续通过 IAM 校验。此操作本身不封禁账号，正常员工仍可重新登录。
- 管理端明确区分“禁用账号”和“撤销 IAM 会话”，展示实际处理结果。
怎样算完成
- 管理员禁用员工后，员工不能新建 IAM 会话、继续授权或获取新令牌。
- 使用禁用前取得的授权码、刷新令牌，包括
offline_access刷新令牌，均不能继续换取令牌。 - 同步确认员工离职后，得到与禁用账号一致的访问限制结果。
- 撤销一个或全部 IAM 会话后，对应会话无法继续访问需要 IAM 登录态的页面和接口。
- 解禁仍在职的员工后，可以重新登录；解禁不得覆盖企微已离职状态。
第一阶段不承诺清除所有业务系统已建立的本地会话，也不承诺使所有离线验签的 JWT 即时失效。界面和交付说明必须写清这一范围，不把 IAM 会话撤销显示成未经验证的“所有系统全部下线”。跨系统退出与既有业务会话回收列入 P1。
3 P0 共用的基础要求
Section titled “3 P0 共用的基础要求”以下属于五项功能的基础实现要求，与 P0 一起交付，无需另行设计一套复杂治理方案。
- 平台权限：先采用管理员
admin与普通用户user。管理操作必须在服务端校验，登录和通讯录同步不自动提权。 - 认证安全：使用认证框架原生能力，完成 PKCE、授权事务校验、一次性授权码、Token 验签及 issuer、audience、有效期等适用检查，不仅解析 Token 内容。
- 凭据保护：生产使用 HTTPS 和安全 Cookie；密钥来自服务端环境变量或 Worker Binding，不提交仓库、不记录在普通日志中。
- 基本防护与记录：认证与令牌入口使用跨实例共享的基础限流；登录及同步失败、禁用账号、撤销会话、应用准入变更有可查询的操作或错误记录。精细参数和审计报表后续完善。
- 接入责任：IAM 负责认证及应用准入；OA、CRM 负责正确验证身份、绑定本地账号和执行自身业务权限。两侧共同完成联调。
- 技术方案：沿用当前 Next.js、Hono、Better Auth、PostgreSQL、Drizzle 和 Cloudflare 架构，具体配置见开发文档。第一阶段不增加新的认证框架或基础设施选型。
4 P1 核心业务之后完善
Section titled “4 P1 核心业务之后完善”| 功能 | 后续完善内容 |
|---|---|
| 邮箱密码备用登录 | 完善已有邮箱密码、找回密码和个人资料体验；不要求为本次分期移除现有流程 |
| 跨系统退出与权限回收 | 联调 Back-Channel Logout 及下游会话处理，明确退出成功、失败和失效窗口 |
| 应用账户与访问权限同步 | 按应用需要启用开通、撤权事件与快照，实现下游自动建号和权限更新 |
| 应用角色透传 | 按实际业务约定 app_role 及映射，业务应用继续维护自己的 RBAC |
| 管理与排障体验 | 完善操作记录查询、同步失败提醒、手机号或工号搜索等辅助能力 |
P1 可以在 P0 开发过程中复用已有实现，但不能要求所有应用先接完账户同步、角色映射或统一退出，才能完成基本的 OIDC 登录。
5 P2 后续再决定
Section titled “5 P2 后续再决定”| 事项 | 何时再讨论 |
|---|---|
| 应用委派管理及创建者权限 | 确有分工需求时，再决定谁能委派、能改哪些字段、是否允许继续转授 |
| 多部门复杂角色合并与权限模型扩展 | 简单应用准入及业务系统本地 RBAC 无法满足需求时 |
| 每应用精细令牌策略及敏感操作重新认证 | 有具体应用提出安全或使用要求时 |
| MFA、Passkey 及管理员强化认证 | 按安全要求安排后续阶段 |
| 同步与撤权的精确时效承诺 | 完成基本链路联调后，根据业务影响确定指标 |
| 多级告警、容量与可用性指标 | 根据实际使用规模和运行情况制定 |
| 审计报表、保留期限与恢复演练细则 | 按企业数据管理和运维要求补充，不据此宣称当前已满足相关要求 |
| 多企业租户、外部 IdP、SCIM | 出现明确的新业务需求后单独评估 |
这些事项不阻塞 P0。已有功能存在的权限绕过、凭据泄露或禁用失效问题，仍须按 P0 基础要求处理，不能以“后续再决定”为由放行。
外部人员管理已从本项目需求中移除，不作为待确认事项保留。
6 第一阶段交付与验收
Section titled “6 第一阶段交付与验收”第一阶段以五项 P0 的验收结果为准，不以页面、接口数量或代码中已有功能判断完成。
建议按以下顺序推进：
- 跑通企微身份、人员及部门同步，保证同一员工身份一致。
- 完成管理员应用注册，并打通业务应用的标准 OIDC 登录。
- 接入人员及部门准入校验，验证未授权人员不能进入。
- 验证禁用、离职、撤销 IAM 会话，以及旧授权码和旧刷新令牌的处理。
- 对 OA、CRM 分别记录联调结果及已有业务会话的处理范围，交付通过验收的版本。
至少保留一次完整业务验证记录：员工登录 → 查看获准应用 → 进入业务系统 → 撤销应用准入后不能再获取新令牌 → 禁用或离职后不能重新登录和刷新。另验证未授权访问、管理员接口越权、企微同步失败和凭据错误不会被放行。
刷新准入检查、离线刷新凭据回收等行为，必须按 IAM-04、IAM-05 的验收条件通过集成测试及对应环境验证，不能仅凭需求文档判断已上线。下游退出通知的完整性按 P1 推进。
7 相关文档
Section titled “7 相关文档”- 系统概览：当前能力和产品边界。
- 认证系统：登录、账号、会话和平台角色实现。
- OAuth Provider：协议端点、配置及令牌流程。
- 对接方式总览：业务系统接入方式。
- 账户与访问权限同步协议：P1 账户与访问权限同步的现有接口约定。
- 测试指南与部署指南：开发验证和发布操作。