企业身份源与组织通讯录同步

在企业级 AI 网关治理体系中，组织架构与在册员工名单是权限管控（RBAC）、访问策略集（Access Profiles）以及虚拟密钥分配的基础支撑。

OmniCortex 提供原生的企业身份源集成 (IdP) 与 组织通讯录同步 (Directory Sync) 体系，深度适配钉钉、飞书等主流企业办公平台。系统支持免密扫码单点登录（SSO）、外部多级部门与员工名单的自动化对齐，并内置单一身份源防错保护与 Dry-Run 差异预演机制，保障企业人员与组织变动在网关底座中的平稳同步。

---

核心机制与业务场景

1. 单一权威身份源防错保护

在企业生产环境中，组织架构与员工身份必须具备权威唯一的数据源。系统支持接入钉钉、飞书等不同平台，但同一时期仅允许激活唯一的权威身份源：

• 防误操作锁定：一旦选定的身份源执行过通讯录同步，且本地已建立部门关系或导入了员工，系统会自动进入保护锁定状态；
• 防止架构混乱：在锁定状态下，界面禁止随意切换其他身份源，避免管理员误操作导致已有部门架构断层或员工身份孤立；
• 受控解锁：若企业确需更换主身份源，需先在「团队」与「用户管理」中解绑或清理历史依赖数据。

2. 双轨同步与 Dry-Run 差异预演

通讯录同步会影响本地组织的部门树与员工账号状态。为防止外部通讯录的误删改对本地产生意外冲击，系统提供双轨同步机制：

• 差异预演（默认开启）：系统先拉取外部部门与人员数据，与本地组织进行比对，不修改任何本地数据。预演完成后弹出核验界面，清晰展现本次同步预计产生的变动概况（部门新增/更新、员工新增/离职停用）；
• 人工核验与正式同步：管理员审查预演变动无误后，点击确认即可批量落盘生效；
• 异常快速排查：若因部分人员信息格式不规范（如工号重复或缺少关键字段）导致局部同步失败，可通过错误明细抽屉直观查看失败原因并进行针对性修正。

3. 工作台免密扫码登录 (SSO)

开启扫码登录后，员工在控制台登录页可直接通过钉钉或飞书客户端扫码进入：

• 安全准入校验：扫码时网关自动核验该员工是否属于已同步纳管的在职人员；
• 未纳管人员拦截：若员工尚未同步至网关，或账号已被停用，系统会自动拦截登录并给出提示，避免未授权人员访问控制台。

4. 同步与登录流转拓扑

🔄外部组织同步与扫码鉴权流水线

权威单源 · 安全预演

第 1 步 · 平台凭据互通与连通测试

钉钉 / 飞书 应用凭据

配置自建应用的 AppKey / AppSecret，支持在保存前一键测试网络与凭据有效性。

↓ 凭据校验通过

第 2 步 · 差异预演与确认同步

防呆核验

拉取外部通讯录并比对差异，弹窗预览人员与部门的变动指标，确认无误后再落盘。

↓ 数据自动对齐并建立保护锁

第 3 步 · 本地组织自动维护与扫码免密登录

团队与用户体系

自动生成多级团队与员工账号；员工可通过工作台扫码快速进入控制台。

---

控制台配置

管理入口：「系统管理」➔「配置管理」（默认进入「身份源与组织同步」Tab）。

界面采用两个子面板组织各项管理能力：

1. 身份源接入与凭据 (credentials)

负责外部身份源的选择、接入凭据维护与网络连通性探测：

📸 截图替换指引（图 1：身份源接入与凭据配置）

• 需截图内容：登录控制台，进入「系统管理」➔「配置管理」，停留于「身份源接入与凭据」子面板。
• 关键画面要素：
  1. 平台单选卡片网格：展示钉钉（高亮选中）、飞书、企业微信（规划中）、未启用 4 张选择卡片；
  2. 锁定状态横幅（若已锁定）：展示单一源保护提示以及已绑定的部门与用户数量；
  3. 凭据表单区：包含显示名称、CorpID、AppKey、密码输入框（带明暗文切换图标）、扫码登录开关；
  4. 底部操作按钮：「测试连通性」与「保存配置」按钮。
• 推荐保存路径：
  • 中文版：Documentation/docs/public/images/idp/zh/idp-config-credentials.png
  • 英文版：Documentation/docs/public/images/idp/en/idp-config-credentials.png

核心配置说明

• 平台选择：
  • 钉钉 (DingTalk)：就绪支持。填写 AppKey 与 AppSecret，可选配置企业 CorpId；
  • 飞书 (Feishu)：就绪支持。填写自建应用的 App ID 与 App Secret；
  • 企业微信 (WeCom)：功能规划中；
  • 未启用：停用外部身份源；
• 显示名称：用于标识该身份源（如 企业钉钉）；
• AppKey / App ID：开放平台自建应用的唯一标识；
• AppSecret：开放平台应用的访问密钥，网关后台脱敏保存，控制台支持明暗文切换；
• 扫码登录开关：开启后，登录页自动显示对应的扫码登录入口；
• 测试连通性：点击可在保存前即时测试网络和凭据是否正常。

---

2. 组织同步与审计中心 (sync)

负责通讯录同步的触发、差异核验与历史同步记录查看：

📸 截图替换指引（图 2：通讯录同步中心与差异预演弹窗）

• 需截图内容：切换至「组织同步与审计」子面板，点击「开始差异预演」后弹出的预演核验窗口。
• 关键画面要素：
  1. 顶部控制栏：展示当前生效的主身份源、预演安全模式开关以及触发按钮；
  2. 差异预演弹窗：包含扫描到的部门与员工总数，以及四宫格指标（部门新增/更新、员工新增/离职停用）；
  3. 历史同步表格：展示任务流水号、执行模式、同步时间、统计概况及操作列。
• 推荐保存路径：
  • 中文版：Documentation/docs/public/images/idp/zh/idp-sync-dry-run.png
  • 英文版：Documentation/docs/public/images/idp/en/idp-sync-dry-run.png

核心操作流程

1. 差异预演：
   • 系统默认开启预演模式。点击「开始差异预演」，系统扫描外部通讯录并与本地对比，弹出变动概况窗口；
2. 核验变动指标：
   • 弹窗展示预估变动：预计新增部门、预计更新部门、预计新增员工、预计停用离职员工；
3. 确认同步：
   • 确认无误后点击「确认立即正式落盘」，系统执行实际同步；若发现异常，可直接关闭窗口取消操作；
4. 排查失败记录：
   • 若同步存在部分异常数据，在历史列表中点击「查看失败明细」抽屉，可查看具体人员或部门的错误原因。

---

开放平台应用对接与最小权限清单

在网关配置前，需先在第三方开放平台创建自建应用，并严格依据企业安全合规要求开通最小必要权限集 (Least Privilege Scope)：

1. 钉钉开放平台对接

1. 登录 钉钉开放平台，进入「应用开发」➔「企业内部开发」，创建自建应用，获取 AppKey 与 AppSecret；
2. 在「安全与权限」➔「权限管理」中，开通以下通讯录与身份验证所需的最小权限点：

权限分类	权限标识 (Scope / Key)	作用说明
通讯录读取	qyapi_get_department_list	获取企业多级部门架构树与层级关系
	qyapi_get_department_member	获取各部门下的在册成员列表
	qyapi_get_member	读取员工详细档案（姓名、工号、邮箱、状态）
基础与登录	open_app_api_base	开放平台自建应用基础接口调用权限
	Contact.User.Read	获取个人基本信息，用于控制台扫码免密登录身份核验
	Contact.User.mobile	读取用户手机号，用于多系统间的人员唯一身份对齐

3. 在「开发配置」➔「登录与分享」中，配置网关控制台的回调重定向 URL；
4. 发布自建应用，并在「版本管理与发布」中将应用可见范围设置为全员或需纳管的特定部门。

---

2. 飞书开放平台对接

1. 登录 飞书开放平台，进入「开发者后台」创建企业自建应用，获取 App ID 与 App Secret；
2. 在「开发配置」➔「权限管理」中，按以下清单开通最小权限范围：

权限中文名称	权限标识 (Scope ID)	作用说明
单点登录	auth:user_access_token:read	支持用户扫码授权登录并置换网关会话凭据
通讯录架构	contact:contact.base:readonly	获取企业通讯录整体概况与基础元数据
	contact:department.base:readonly	读取部门名称与基础元数据
	contact:department.organize:readonly	读取部门多级父子组织架构信息，还原部门树
员工基本信息	contact:user.base:readonly	获取在册员工的基础身份信息与在职状态
	contact:user.basic_profile:readonly	获取员工姓名、头像等展示档案
	contact:user.email:readonly	获取员工企业邮箱（用于登录账号与通知匹配）
	contact:user.employee_id:readonly	获取员工工号 / 用户唯一 ID 标识
	contact:user.phone:readonly	获取员工手机号码（用于跨系统人员主键对齐）

3. 在「安全设置」中将网关控制台登录重定向地址加入重定向 URL 白名单；
4. 创建应用版本并提交审核，经企业飞书管理员审批通过并发布上线后生效。

---

常见异常排查

现象描述	排查方向	建议操作
测试连通性失败	凭据输入错误、应用未上线发布，或开放平台未开通通讯录权限。	核对 AppKey/AppSecret 是否填写完整，确认开放平台通讯录权限已开通且应用已发布。
无法切换当前身份源（提示已锁定）	当前身份源已同步过本地部门或人员，触发了单一源保护。	需先在「团队」与「用户管理」中清理或解绑旧有数据；如需重置，请联系系统管理员。
同步任务存在部分失败	部分员工数据缺失必要字段（如工号重复或手机号格式错误）。	在同步记录中点击「查看失败明细」，定位异常人员并在钉钉/飞书通讯录中修正后重新同步。
扫码登录提示未纳管或已被禁用	该员工尚未通过通讯录同步至网关，或账号在本地已被停用。	确认员工在开放平台应用可见范围内，并在网关中执行一次通讯录同步后再尝试登录。