# 连接器与集成

组织管理员在「我的组织」里把企业微信、Webhook 与服务账号、微信公众号、公司 OIDC/OAuth 登录接到本组织：成员可扫码或用企业账号登录，消息可推到企业微信，客户与审批可回流，外部系统可用密钥调接口或收事件。

## 谁能用

页面权限由角色决定。系统支持「管理员」「审计员」「分析员」「成员」四种角色：

| 页面 | 导航名称 | 所属分组 | 侧栏可见性 | 页面读取权限 | 页面写入权限 |
|---|---|---|---|---|---|
| `/connectors` | 「协作平台」 | 「应用」 | 仅管理员 | 管理员；审计员通过链接直开可查看 | 仅管理员 |
| `/integrations` | 「服务账号与 Webhook」 | 「应用」 | 仅管理员 | 管理员；审计员通过链接直开可查看 | 仅管理员 |
| `/wechat` | 「微信公众号」 | 「应用」 | 仅管理员 | 仅管理员（需写权限方可进入） | 仅管理员 |
| `/identity-providers` | 「企业登录」 | 「安全」 | 仅管理员 | 管理员；审计员通过链接直开可查看 | 仅管理员 |

权限控制说明：
- 分析员或普通成员直接访问上述页面时，界面展示空状态提示「没有权限」与「你的账号角色不允许查看这个页面。请联系租户管理员。」。
- 缺少写权限时（如审计员只读查看），创建、编辑、断开、同步、重试等操作按钮均不显示；只读用户仍能查看已保存内容，但所有密钥明文永不回显。
- 微信公众号页面的读取与写入均仅限管理员，助手代办或直接调用写接口均会被系统拒绝。
- 「运行方式」（同页运行同意）不在本组导航中，位于[应用管理](/admin/apps)中已安装应用的详情页内。
- 部门与成员的通讯录同步在「组织结构」→「通讯录同步」中进行；在协作平台已连接企业微信后，界面会显示链接引导「部门与成员的同步在」「组织结构 → 通讯录同步」。

## 怎么打开

1. 进入[工作台](/guide/workspace)。
2. 在工作台打开「行政」→「我的组织」。
3. 在左侧导航分组中进入对应页面：
   - 「应用」分组：点击「协作平台」「微信公众号」或「服务账号与 Webhook」。
   - 「安全」分组：点击「企业登录」。

从助手或已发出的链接进入时，可直达「协作平台」「微信公众号」「服务账号与 Webhook」或「企业登录」。

> **提示**
>
> 这些页面必须从工作台打开；若直接在浏览器地址栏独立访问组织应用域名，页面会提示「请从工作台打开」。从单条实体链接进入时，页面不一定自动滚动到对应卡片。

## 界面一览

### 1. 协作平台（`/connectors`）

页头显示「协作平台」，页面不设页签，按部署注册的提供方展示卡片（当前仅支持「企业微信」）。
- **部署状态异常**：未开启连接时提示「不可用」「未开启协作平台连接，请联系部署方。」；提供方列表为空时提示「暂无可连接的协作平台」「请联系部署方启用。」。
- **未连接状态**：面板标题显示「企业微信」，提示「先按下面的步骤在企业微信里设置，再点「连接」。」，提供「连接企业微信」按钮与四步准备说明；配置了回调域时展示「授权回调域」与可复制的代码块。
- **已连接状态**：展示名称、提供方徽标、状态徽章（「已启用」「未启用」或「登录方式缺失」）、企业微信参数（「企业 ID」「应用 AgentId」，空值显示「—」）、「通讯录同步 Secret」（「已设置」/「未设置（不能同步通讯录）」）、「客户联系 Secret」（「已设置」/「未设置（不能导入外部联系人、做渠道活码）」）、自动建号与邮箱关联摘要；操作区包含「停用登录」或「启用登录」（登录方式缺失时禁用）、「编辑」、「断开」。
- **客户联系同步面板**：顶部带有警告提示「尚未对真实企业微信验证」「目前只在模拟器上验证过。」。未填 Secret 时提示「现在不能同步」「还没有填写客户联系 Secret，不能导入外部联系人。点「填写 Secret」补上后再回来。」并提供按钮「填写 Secret」；已填时提供「立即同步」（运行中显示「同步中…」）按钮；统计卡片展示「外部联系人」「待关联」「已关联」「已离开」；提供「自动同步」开关与「同步间隔」选择器；附带「导入的规则」说明及最近 20 次「同步记录」。
- **事件回调与收到的事件面板**：
  - 「事件回调」：带有警告提示「尚未对真实企业微信验证」「目前只在模拟器上验证过。」；提供「生成 Token 和密钥」或「重新生成」按钮；展示配置状态（「未配置」「待验证」「已验证」）、统计指标（「验证通过」「最近收到事件」「已处理」「失败」）、可复制的「回调 URL」以及企业微信后台配置步骤。生成后提示「只显示这一次，现在就复制」，提供按钮「我已复制保存」；已保存后提示「Token 和 EncodingAESKey 已保存，不能再看到；忘了就重新生成。」。
  - 「收到的事件」：展示最近 100 条回调事件，可通过筛选器「显示」按「全部」「失败」「已处理」「处理中」过滤；列表展示时间、事件种类、状态、处理次数；针对失败事件提供「重试」按钮。
- **审批模板映射面板**：说明「只有「通过」的审批按映射在经营里记账，同一张只入账一次；没有映射的模板只记录。」；提供「添加映射」按钮；列表展示模板名称（未命名显示「（未命名）」）、模板 ID、入账摘要、启用开关、「编辑」与「删除」。
- **通知面板**：描述「消息中心的消息同时推送到成员的企业微信。」；带有警告提示「尚未对真实企业微信验证」「目前只在模拟器上验证过；消息字段、限流等以企业微信的规则为准。」；提供「发一条测试消息给我」测试按钮；统计卡片展示「已关联企业微信」「没有关联」「今天已推送」「推送失败」；提供「推送哪些消息」开关列表、「每人每天最多推送」条数限制与「免打扰时间」设置；底部列出最近 100 条「推送失败」记录与重试按钮。

![「协作平台」：未连接企业微信](/shots/admin-connectors.webp)

图：「协作平台」：未连接企业微信

1. 页头「协作平台」
2. 提供方「企业微信」
3. 「连接企业微信」：先按步骤在企业微信里建自建应用

### 2. 服务账号与 Webhook（`/integrations`）

页头显示「服务账号与 Webhook」，包含「服务账号」与 Webhook 两个页签。

![「服务账号与 Webhook」：服务账号](/shots/admin-integrations.webp)

图：「服务账号与 Webhook」：服务账号

1. 页头「服务账号与 Webhook」
2. 「创建服务账号」：密钥只显示一次
3. 页签「服务账号」：给集成和 Agent 用，不占席位
4. 页签「Webhook」

| 页签 | 区域 / 元素 | 说明 |
|---|---|---|
| 「服务账号」 | 不可用提示 | 未连接身份服务时展示「服务账号不可用」「这个部署没有连接身份服务。」 |
| | 账号列表 | 展示「名称」「权限」（角色徽标，仅有基础权限时显示「成员」）、操作菜单（「轮换密钥」「删除」）；页脚显示账号总数；空态提示「还没有服务账号」 |
| | 操作按钮 | 拥有写权限时显示「创建服务账号」 |
| Webhook | 列表与状态 | 展示接收地址、「已启用」/「已停用」徽标、备注、订阅事件与创建时间；空态提示「还没有 Webhook」 |
| | 操作按钮与菜单 | 顶部显示「添加 Webhook」；每行提供「投递记录」、「发送测试」以及操作菜单（「编辑」「停用」/「启用」「轮换签名密钥」「删除」） |
| | 验签与记录 | 提供「验证签名」说明与代码示例；「投递记录」弹窗每 5 秒刷新，展示时间、事件、状态、尝试次数、响应及「重发」按钮 |

### 3. 微信公众号（`/wechat`）

页头显示「微信公众号」。
- **未绑定卡片**：标题「第一步：绑定公众号」，描述提示「填入公众平台「设置与开发 → 基本配置」里的 AppID 和 AppSecret。可选，不绑定不影响其他功能。」，表单包含「AppID」「公众号名称」「AppSecret」「已在公众号后台配置的域名」，底部提供「绑定」按钮。
- **已绑定卡片**：标题「公众号账号」，状态徽标展示「未绑定」「已绑定 · 未验证」「已绑定 · 已验证」或「出错」；表单回显配置，操作按钮包含「解除绑定」「测试连接」（有未保存修改时禁用）与「保存」。测试结果展示连接时间与状态。
- **配置清单卡片**：标题「在微信公众平台需要完成的三项配置」，列出「JS接口安全域名」「网页授权域名」「IP 白名单」；若站点未绑定独立域名，提示前往[站点](/apps/site)应用绑定；底栏提示前往「站点」上传微信校验文件。

### 4. 企业登录（`/identity-providers`）

页头显示「企业登录」。
- **环境状态**：未连接身份服务时提示「不可用」「这个部署没有连接身份服务，企业登录由部署方配置。」。
- **重定向说明**：顶部提示「在你们的提供方里登记这个重定向地址」，描述「填进提供方应用的“重定向 URI”。」，提供两条可复制的重定向 URL。
- **提供方列表**：标题「已接入的提供方」，描述显示接入数量与上限（最多 10 个）；每行显示名称、协议（「OpenID Connect」或「OAuth 2.0」）、状态（「已在登录页提供」或「未启用」）、发行者地址或授权端点、首次登录规则；行开关「登录页提供」；企业微信托管源提示去「协作平台」修改；其他提供方支持「编辑」与「删除」。
- **操作按钮**：未满额且有写权限时显示「接入提供方」。

![「企业登录」](/shots/admin-idp.webp)

图：「企业登录」

1. 页头「企业登录」
2. 「接入提供方」：OIDC / OAuth；企业微信不走这里
3. 先把重定向 URI 填进提供方应用
4. 企微 / 钉钉 / 飞书不是标准 OIDC，请走「协作平台」或桥接

## 常用操作

### 连接企业微信

![「连接企业微信」对话框（示例值，不保存）](/shots/admin-connectors-wecom.webp)

图：「连接企业微信」对话框（示例值，不保存）

1. 「企业 ID」：我的企业页底部的 corpid（示例值）
2. 「应用 AgentId」：自建应用的 AgentId（示例值）
3. 「Secret」：保存后不再显示；此处用明显示例值，不要填真实密钥
4. 通讯录同步 / 客户联系 Secret：可选，同样只写不读

1. 在企业微信管理后台建好自建应用，设好授权回调域和企业可信 IP。怎么做见[接入企业微信](/connect/wecom#create-app)。
2. 在左侧导航点击「应用」分组下的「协作平台」。
3. 在企业微信面板点击「连接企业微信」。
4. 填写连接参数：
   | 字段 | 必填 | 说明 |
   |---|---|---|
   | 「名称」 | 是 | 填写连接名称，最多 60 个字符，显示在登录页面的登录按钮上。 |
   | 「企业 ID」 | 是 | 企业微信的企业 ID（corpid），要求 6–64 位字母、数字、下划线或连字符。 |
   | 「应用 AgentId」 | 是 | 填写自建应用的 AgentId，要求 1–12 位数字。 |
   | 「Secret」 | 是 | 填写自建应用的 Secret，长度 8–200 个字符。保存后系统不再回显。 |
   | 「通讯录同步 Secret」 | 否 | 选填，通讯录同步的专用 Secret，长度 8–200 个字符。不设置则不能同步通讯录。去哪里取见[接入指南](/connect/wecom#contacts-secret)。 |
   | 「客户联系 Secret」 | 否 | 选填，客户联系的专用 Secret，长度 8–200 个字符。不设置则不能导入外部联系人。去哪里取见[接入指南](/connect/wecom#customer-secret)。 |
   | 「首次登录自动创建账号」 | 否 | 开启时成员在企业微信中必须登记有邮箱；关闭后仅已邀请的成员可登录。 |
   | 「按邮箱关联已有账号」 | 否 | 仅当企业微信中的邮箱由管理员统一维护、成员无法自改时打开，避免被冒充。 |
   | 「连接后立即在登录页提供扫码登录」 | 否 | 仅新建时可选，默认开启。开启后连接成功将立即在登录页展示企业微信扫码登录。 |
5. 点击「测试连接」。测试通过提示「连接正常」与「已取到凭证。」；未通过提示「连不上或设置不对」及具体原因。
6. 点击「连接」。连接成功后系统提示「已连接」（并附带提供方标签「企业微信」）。

> **提示**
>
> 每个组织对每种协作平台只能连接一次。若已经连接，无法重复创建，须直接修改已有连接。

### 维护与断开企业微信连接

- **启用或停用扫码登录**：在已连接卡片点击「停用登录」或「启用登录」，成功后分别提示「已停用扫码登录」或「已启用扫码登录」。若底层身份源缺失，状态显示「登录方式缺失」，开关被禁用。
- **编辑连接参数**：点击卡片右上角「编辑」，修改参数后点击「保存」。若不修改 Secret，密码框留空即可；若需要移除通讯录或客户联系凭证，可勾选「清除已保存的 Secret」。
- **断开连接**：
  1. 点击卡片右上角「断开」。
  2. 在确认弹窗中确认提示：「成员将不能再用企业微信扫码登录。已经关联的成员账号和数据不受影响，他们仍可以用密码登录。」。
  3. 点击「断开」。断开成功后提示「已断开」。

### 同步企业微信客户联系

1. 确保已在企业微信连接中填写「客户联系 Secret」。若未填写，在面板点击「填写 Secret」补全。
2. 配置同步策略：
   - 在「同步间隔」下拉框中选择自动同步周期（提供 15、30、60、120、360 分钟及 1440 分钟/每天可选，接口支持 5–1440 分钟）。保存后提示「已保存同步间隔」。
   - 打开「自动同步」开关，开启后提示「已开启自动同步」；关闭提示「已关闭自动同步」。
3. 手动同步：点击「立即同步」，按钮变为「同步中…」。同步完成后提示「同步完成」；若已有任务正在执行，提示已有同步正在进行。
4. 查看记录：在「同步记录」中查看最近 20 次执行结果。若有跳过的联系人，可展开「需要留意……位联系人」查看详情。

> **注意**
>
> 外部联系人单向导入以企业微信为准，单次导入上限为 20000 人。若同步失败，整次操作回滚，不会改动已有的客户与标签。

### 配置事件回调与审批模板记账

- **配置与验证事件回调**：
  1. 在「协作平台」下方找到「事件回调」面板，点击「生成 Token 和密钥」（已生成时为「重新生成」）。
  2. 弹窗提示「只显示这一次，现在就复制」，复制展示的「回调 URL」、Token 与 EncodingAESKey，确认后点击「我已复制保存」。
  3. 在企业微信后台填入地址与密钥并订阅事件，见[接入企业微信](/connect/wecom#events)。
  4. 企业微信保存并验证通过后，面板状态转为「已验证」。
> **注意**
>
>   重新生成 Token 和 EncodingAESKey 会导致旧密钥立即失效。企业微信发送的事件将被拒绝，直到在企业微信后台更新并重新验证。
- **查看与重试事件**：在「收到的事件」列表中筛选事件状态（最多展示 100 条）。对处理失败的事件点击「重试」，成功提示「已处理」，仍失败提示「仍然失败，原因见该事件」。
- **添加审批模板记账映射**：
  1. 在「审批模板映射」面板点击「添加映射」。
  2. 填写映射字段：
     | 字段 | 必填 | 说明 |
     |---|---|---|
     | 「模板 ID」 | 是 | 填写企业微信审批模板的 TemplateId，长度 1–64 位。保存后不可修改。 |
     | 「名称」 | 是 | 填写映射规则名称（如「费用报销」），最多 40 个字符。 |
     | 「入账方式」 | 是 | 选择「应付（先挂账，之后付款）」或「支出（已经付过，直接记一笔）」。 |
     | 「金额控件 ID」 | 是 | 填写审批模板中金额控件的 ID，形如 `Money-1500000000000`。 |
     | 「往来方控件 ID（可选）」 | 否 | 选填，留空时往来方默认为单据申请人。 |
     | 「分类（可选）」 | 否 | 选填，[经营](/apps/biz)应用中的费用分类，最多 40 个字符。不存在时会自动新建。 |
     | 「付款期限（天，可选）」 | 否 | 仅入账方式为应付时可选，设置 0–365 天付款期限；留空不设期限。 |
     | 「启用」 | 否 | 默认开启。开启后该模板通过的单据方可自动入账。 |
  3. 点击「保存」，成功提示「已保存」。
> **提示**
>
>   每个组织最多添加 200 个审批模板映射。只有审批状态为「通过」的单据才会入账，同一单号只入账一次；未建立映射的审批模板事件仅作记录，不执行入账。

### 配置企业微信消息推送

1. 在「协作平台」下方找到「通知」面板。
2. 在「推送哪些消息」中配置需要推送到成员企业微信的类别：
   - 「审批待办」（审批组，默认推送）：轮到你审批、抄送给你、被退回、超时提醒、审批异常。
   - 「审批结果」（审批组，默认推送）：发起的审批通过、被拒绝、被撤回或终止。
   - 「系统告警」（系统组，默认推送）：发给管理员的系统警告（如收款异常）及带「警告」「严重」标记的消息。
   - 「被提到」（协作组，默认推送）：有人在文档里提到了你。
   - 「应用通知」（应用组，默认关闭）：订单到账、预约取消、绩效与人事提醒等日常通知。
   - 「管理员通知」（系统组，默认关闭）：组织管理员在消息中心发送的全员通知。
3. 设定推送配额与免打扰时间：
   - 「每人每天最多推送」：输入 1–1000 之间的整数（默认 50 条）。超额消息只留在消息中心。
   - 「免打扰时间」：设置起止时刻（格式为 `时:分`，例如 22:00 到 08:00，北京时间；起止不能相同）。免打扰期间不推送，结束后补发，「重要」消息照常推送；若不需要免打扰可清空为「没有免打扰时间」。
4. 点击「保存」，保存成功提示「已保存」。
5. 测试推送：点击「发一条测试消息给我」，向当前管理员的企业微信发送测试消息并查看结果。
6. 重试失败消息：若有推送失败，在底部「推送失败」记录（最多 100 条）中点击「重试」重新发送。

### 创建与管理服务账号

- **创建服务账号**：
  1. 在左侧导航进入「应用」分组下的「服务账号与 Webhook」。
  2. 处于「服务账号」页签，点击右上角「创建服务账号」。
  3. 填写账号参数：
     | 字段 | 必填 | 说明 |
     |---|---|---|
     | 「名称」 | 是 | 填写账号标识，要求 2–63 位字符，以小写字母开头，仅允许小写字母、数字、`-` 或 `_`（示例 `erp-sync`）。组织内不可重名。 |
     | 「附加权限」 | 否 | 服务账号始终包含「成员」角色。可选勾选附加「分析员」或「审计员」角色；不可勾选管理员角色。 |
  4. 点击「创建」。
  5. 弹窗展示「Client ID」与「Client Secret」，并提供获取令牌的 curl 命令。
> **危险**
>
>   Client Secret 只显示这一次，关闭窗口后无法再次查看。请立即复制保存，确认后点击「我已保存」。若遗失只能轮换密钥。
- **轮换密钥**：在服务账号右侧操作菜单点击「轮换密钥」，确认提示「旧密钥立即失效。」后点击「轮换」，并在弹出的窗口中复制新密钥。
- **删除服务账号**：在操作菜单点击「删除」，确认提示「使用它的系统立即失去访问，不能撤销。」后点击「删除」，成功提示「已删除」。

### 添加与管理 Webhook

- **添加 Webhook**：
  1. 在「服务账号与 Webhook」页面切换到 Webhook 页签。
  2. 点击右上角「添加 Webhook」。
  3. 填写 Webhook 配置：
     | 字段 | 必填 | 说明 |
     |---|---|---|
     | 「接收地址」 | 是 | 必填公网 https 地址。不得包含用户名密码，不得为本机或内网地址。 |
     | 「备注」 | 否 | 选填，最多 200 个字（例如「同步到 ERP」）。 |
     | 「订阅的事件」 | 否 | 可勾选 `*`「所有事件」，或具体事件：`draft.*`（[草稿：审阅与应用](/agent/drafts)）、`admin.*`（管理操作）、`admin.member.*`（成员变动）、`admin.app.*`（应用变动）、`audit.*`（审计操作）。 |
     | 「其他事件」 | 否 | 选填，逗号分隔，可用 `*` 结尾的前缀（如 `admin.llm.*`）。勾选「所有事件」时此项禁用。 |
     | 「启用」 | 否 | 默认开启。 |
  4. 点击「添加」。
  5. 弹窗提示「Webhook 已创建」，展示「签名密钥」，请立即复制保存。
> **提示**
>
>   每个组织最多添加 20 个 Webhook。外部系统收到回调时，应按页面「验证签名」说明校验请求头 `X-Kwork-Signature`，并拒绝时间戳过旧的请求。
- **测试与投递记录**：
  1. 在 Webhook 列表中点击对应行的「发送测试」，系统提示「已发送测试事件」并打开「投递记录」弹窗。
  2. 弹窗每 5 秒刷新一次，展示时间、事件、状态（「等待重试」「已送达」「失败」）、次数与响应。
  3. 针对未送达的事件可点击「重发」，提示「已重新排队」。
- **维护与删除**：
  - 在行操作菜单可点击「编辑」、「停用」或「启用」。
  - 轮换密钥：点击「轮换签名密钥」，确认「旧密钥立即失效。」后点击「轮换」。
  - 删除：点击「删除」，确认提示「同时删除投递记录，不能撤销。」后点击「删除」，成功提示「已删除」。

### 绑定与管理微信公众号

- **绑定公众号**：
  1. 在左侧导航点击「应用」分组下的「微信公众号」。
  2. 在「第一步：绑定公众号」卡片中填写参数：
     | 字段 | 必填 | 说明 |
     |---|---|---|
     | 「AppID」 | 是 | 微信公众平台的基本配置 AppID，格式为 `wx` 开头的 18 位字符（后接 16 位小写十六进制字符）。 |
     | 「公众号名称」 | 否 | 选填，设置备注名称，最长 40 个字。 |
     | 「AppSecret」 | 是 | 微信公众平台的 AppSecret。初次绑定必填，保存后不回显明文。 |
     | 「已在公众号后台配置的域名」 | 否 | 选填，一行一个，记录微信后台已配置好的域名，便于下方清单核对。 |
  3. 点击「绑定」，成功提示「已绑定公众号，接下来点「测试连接」」。
  4. 对照页面「在微信公众平台需要完成的三项配置」清单，在微信公众平台完成设置，见[接入微信公众号与小程序](/connect/wechat#checklist)。
  5. 返回页面点击「测试连接」。若成功，显示「已连接，成功取得 access_token」；若失败，显示「没有连上」及原因或微信错误码。
- **修改与解除绑定**：
  - 修改配置：修改 AppID 或名称后点击「保存」；若修改 AppSecret，填入新值后保存并重新测试连接。
  - 解除绑定：点击卡片右上角「解除绑定」，确认提示「AppSecret 和已缓存的令牌会被清除；用微信登录、分享签名的站点在重新绑定前不可用。」后点击「解除绑定」，成功提示「已解除绑定，AppSecret 和缓存的令牌已清除」。

### 接入企业登录提供方

1. 在左侧导航进入「安全」分组下的「企业登录」。
2. 复制页面顶部展示的重定向地址，在你的身份提供方里登记，见[接入企业登录](/connect/sso#redirect)。
3. 点击右上角「接入提供方」。
4. 选择「提供方类型」（各提供方那边怎么建应用，见[接入企业登录](/connect/sso)）：
   - 「其他 OpenID Connect」：标准 OIDC 提供方，需填写 Issuer 地址。
   - 「Microsoft Entra ID（Azure AD）」：Azure 目录应用，将 Issuer 中的租户 ID 替换为实际目录 ID。
   - 「Google Workspace」：Google Cloud OAuth 客户端。
   - 「Okta」：Okta OIDC Web 应用，使用默认授权服务器 Issuer。
   - 「Keycloak」：Keycloak realm 下的保密 OIDC 客户端。
   - 「Authing」：用于将企业微信、钉钉、飞书等桥接为标准 OIDC 接入。
   - 「其他 OAuth 2.0」：提供授权、令牌、用户信息接口的 OAuth 2.0 提供方。
5. 填写接入配置：
   | 字段 | 必填 | 说明 |
   |---|---|---|
   | 「名称」 | 是 | 填写提供方名称，最多 60 个字符，显示在登录页面的登录按钮上。 |
   | 「Issuer」 | 条件必填 | OIDC 类型必填，提供方的发行者地址。填好后可点击「测试连接」测试发现文档。 |
   | 「授权地址」「令牌地址」「用户信息地址」 | 条件必填 | 仅「其他 OAuth 2.0」类型必填。 |
   | 「用户标识字段」 | 条件必填 | 仅「其他 OAuth 2.0」类型出现，标识用户的字段，默认 `sub`。 |
   | 「Client ID」 | 是 | 填写客户端 ID。 |
   | 「Client Secret」 | 是 | 填写客户端密钥，新建必填。保存后不回显明文，编辑时留空表示不改。 |
   | 「Scope」 | 否 | 授权范围，空格分隔，默认 `openid profile email`。 |
   | 「自动创建账号」 | 否 | 成员第一次用公司账号登录时是否自动建号，默认开启；关闭后仅已邀请的成员可登录。 |
   | 「按已验证邮箱并入已有账号」 | 否 | 默认关闭。仅在提供方保证邮箱真实不可自改时打开，否则可能存在冒充风险。 |
6. 点击「接入」，成功提示「已接入，记得在列表里打开“登录页提供”」。
7. 在提供方列表对应行打开「登录页提供」开关，开启后提示「已在登录页提供」。

> **提示**
>
> 每个组织最多接入 10 个企业登录提供方。由企业微信连接生成的登录方式属于托管身份源，在列表提示由「企业微信」连接管理，并提供链接引导「去「协作平台」修改」，不支持在此直接编辑或删除。

## 状态说明

各模块在界面中的状态定义如下：

| 模块 | 状态标签 | 说明 |
|---|---|---|
| 协作平台连接 | 「已启用」 | 连接已建立且扫码登录处于启用状态。 |
| | 「未启用」 | 连接已建立，但管理员手动停用了扫码登录。 |
| | 「登录方式缺失」 | 底层身份源丢失，停用与启用登录按钮被禁用。 |
| 事件回调 | 「未配置」 | 尚未生成回调 Token 和 EncodingAESKey。 |
| | 「待验证」 | 已生成回调地址与密钥，等待在企业微信后台配置并通过验证请求。 |
| | 「已验证」 | 企业微信验证请求已通过，事件正常接收处理。 |
| 微信公众号 | 「未绑定」 | 尚未配置 AppID 与 AppSecret。 |
| | 「已绑定 · 未验证」 | 已保存凭证，但尚未通过连接测试。 |
| | 「已绑定 · 已验证」 | 测试连接通过，成功取得 access_token。 |
| | 「出错」 | 连接测试失败或通信异常。 |
| Webhook 投递 | 「等待重试」 | 本次投递未成功，正在等待下一次重试。 |
| | 「已送达」 | 目标服务器成功返回响应，事件送达。 |
| | 「失败」 | 超过重试限制仍未送达，投递失败。 |
| 企业登录 | 「已在登录页提供」 | 该提供方已在组织登录页展示登录按钮。 |
| | 「未启用」 | 已接入该提供方，但尚未在登录页展示（新建默认未启用）。 |

## 让助手帮你做

你可以让助手协助执行配置草稿生成与查询操作：

> 帮我连上企业微信，企业 ID 是 ww1234567890abcdef。
> 打开企业微信消息推送，每天最多 30 条，免打扰 22 点到 8 点。
> 给费用报销模板加一条应付映射。
> 创建一个叫 erp-sync 的服务账号。
> 加一个 Webhook，地址是 https://api.example.com/webhook。
> 绑定公众号，AppID 是 wx1234567890abcdef。
> 接入我们公司的 Google Workspace 登录。

> **提示**
>
> 需要你确认的事项与限制：
> - **高风险操作确认与验身**：连接、修改或断开企业微信，绑定或解绑微信公众号，添加、修改或删除企业登录，创建或删除服务账号，创建或删除 Webhook 等写操作均属于高风险操作。助手生成草稿后必须经过你的确认，关键操作还需要通过管理员身份验证。
> - **密钥安全机制**：企业微信 Secret、公众号 AppSecret、企业登录 Client Secret 等密钥明文**助手无法替你填写，生成结果中也不会包含密钥明文**。在审阅草稿时，必须由你在确认界面亲自录入。
> - **服务账号与 Webhook 密钥**：助手创建服务账号或 Webhook 时，生成结果中**不包含** Client Secret 或签名密钥明文，必须由你在页面中查看或执行密钥轮换。
> - **测试操作限制**：助手无法替你点击「测试连接」「发一条测试消息给我」或「发送测试」。
> - **通讯录同步设置**：助手无法在本页面修改通讯录同步的间隔设置（需在「组织结构」→「通讯录同步」中设置）。

## 设置

本组功能不设单独的全局设置页面，相关参数直接在对应卡片与弹窗中配置：

- **企业微信通知设置**：包含推送消息种类勾选、每日每人推送上限（1–1000 条，默认 50 条）以及免打扰时间区间（默认 22:00 到 08:00，北京时间）。
- **客户联系同步设置**：包含自动同步开关以及同步间隔周期（15–1440 分钟，接口支持 5–1440 分钟）。
- **审批模板映射设置**：包含启用开关、入账方式（应付或支出）以及付款期限（0–365 天）。
- **Webhook 设置**：包含启用开关以及事件订阅过滤规则。
- **企业登录设置**：包含「登录页提供」开关、自动创建账号开关以及按已验证邮箱关联已有账号开关。

部署环境关联说明：
- 若部署环境未开启协作平台连接或未连接身份服务，对应页面会展示「不可用」提示。
- 平台出口 IP 由部署环境决定。配置微信公众号与企业微信可信 IP 时，需确保包含平台的所有出口 IP。

## 注意事项

- **不可撤销与高风险操作**：
  - 轮换服务账号 Client Secret、轮换 Webhook 签名密钥或重新生成企业微信回调 Token 与 EncodingAESKey，旧密钥**立即失效**，不可撤销。
  - 删除服务账号会导致调用该账号的外部系统立即失去访问权限，不可撤销。
  - 删除 Webhook 会同时删除其所有的历史投递记录，不可恢复。
  - 解除绑定微信公众号会清除 AppSecret 及已缓存的 access_token，依赖微信登录和分享签名的站点将不可用。
  - 断开企业微信连接后，成员将无法再通过企业微信扫码登录，但已经关联的成员账号和业务数据不受影响，他们仍可通过密码登录。
- **密钥安全与只写不读**：
  - 企业微信自建应用 Secret、通讯录 Secret、客户联系 Secret、微信公众号 AppSecret、服务账号 Client Secret、Webhook 签名密钥以及回调 Token 和 EncodingAESKey 均采用单向加密存储。
  - 界面**永不回显明文密钥**，关闭弹窗后无法再次查看，遗失只能重新生成或轮换。
- **配额与上限约束**：
  - 协作平台连接：每个组织每种协作平台只能连接 1 个。
  - 企业登录：每个组织最多接入 10 个提供方。
  - Webhook：每个组织最多添加 20 个。
  - 审批模板映射：每个组织最多添加 200 个。
  - 微信公众号：每个组织只能绑定 1 个公众号，AppID 在平台全局唯一，已被其他组织绑定的无法再次绑定。
  - 客户联系同步：外部联系人最多导入 20000 人；部门上限 500 个、层级深度最多 8 级（超限整次同步失败并回滚）。
  - 日志与记录上限：事件回调日志最多展示最近 100 条（无分页）；客户联系同步记录最多展示最近 20 次；消息推送失败记录最多展示最近 100 条。
- **跨系统协同与规则**：
  - 钉钉与飞书不是标准 OpenID Connect 协议，不能直接在企业登录中接入，需通过 Authing、Keycloak 等桥接后接入。
  - 企业微信消息推送的免打扰时间固定以北京时间计算。
  - 企业微信内置浏览器不支持静默免密登录，成员首次点击通知卡片仍需在登录页扫码登录一次。
  - 审批模板映射仅在审批结论为「通过」时入账，同一单号只入账一次；单据撤回或冲回不会自动逆向记账。

## 目前不支持

- 尚未对真实企业微信与真实微信公众号完成实机验证（目前主要在模拟器环境验证，界面带有相应提示）。
- 企业微信内置浏览器静默登录以及在消息卡片内直接审批。
- 直接连接钉钉或飞书协作平台，以及向钉钉、飞书推送消息。
- 自选免打扰时区（目前固定为北京时间）。
- 助手在对话中出示或回显任何密钥明文。
- 在本页面内直接创建渠道活码（需前往[客户](/apps/customer)应用）。
- 审批单撤回后的自动冲账与收入方向审批入账。

## 常见问题

#### 为什么保存过 Secret 之后，再次打开编辑却看不到明文？
系统对所有集成凭证（包括企业微信 Secret、公众号 AppSecret、服务账号 Client Secret、Webhook 签名密钥）实行单向安全存储。凭证保存后界面不会再次回显明文，编辑时留空表示保留原设置不修改。若遗失密钥，请使用「轮换密钥」或「重新生成」功能重新生成。

#### 为什么编辑企业微信连接或企业登录时，让助手代办却提示需要管理员亲自输入 Secret？
所有身份源与协作平台的写入操作均属于高风险操作。为了防止敏感凭证在传输或对话上下文中泄露，系统规定助手生成的草稿中一律不包含明文密钥，且系统强制要求由管理员本人在审阅确认界面亲自录入 Secret 并通过身份验证。

#### 为什么界面提示「尚未对真实企业微信验证」？
系统的企业微信消息推送、客户联系同步和事件回调功能目前主要在模拟器环境下进行了功能验证，因此界面上显示「尚未对真实企业微信验证」「目前只在模拟器上验证过」的提示。在实际生产环境中，消息推送频次与字段格式均以企业微信官方规则为准。

#### 钉钉和飞书可以在这里直接接入吗？
目前「协作平台」仅支持连接企业微信。由于钉钉和飞书不支持标准 OpenID Connect 协议，无法直接在「企业登录」中作为标准提供方接入。若需要使用钉钉或飞书账号登录，可以通过 Authing 或 Keycloak 等身份认证系统将其桥接转换为标准 OIDC 协议后再行接入。

#### 为什么在「企业登录」列表中无法直接编辑或删除企业微信登录？
该条企业登录是由「协作平台」连接企业微信时自动登记的托管身份源。它的生命周期由企业微信连接集中管理，列表中提示由「企业微信」连接管理，并显示链接引导「去「协作平台」修改」。如需修改参数、停用或移除该登录方式，请前往「协作平台」页面进行操作。