本文为您介绍在一个企业下同时存在多种身份体系的场景下，如何实现多 IDP （飞书、钉钉、Lark等）接入 ArkClaw。 ## 场景概述在集团企业、并购整合、跨国多主体等复杂组织中，往往存在多种身份体系并存的情况：国内主体使用飞书、海外主体使用 Lark（国际版飞书）、被并购公司使用钉钉、海外办公室使用 Microsoft Teams / Entra ID、还有部分内部系统挂在本地 Active Directory（微软混合域架构，下文简称 AD）上。这种情况下，如果为每一套体系单独建一套 ArkClaw 空间，会导致账号分散、权限不一致、运维成本高。 ArkClaw 支持通过**多 IDP 组合并存模式**接入多个身份源，在一个统一的身份池下汇总所有用户，实现： * 员工使用各自熟悉的账号登录 ArkClaw（保持原有账号体系）。 * 管理员在统一视图下管理全集团用户，做权限和组织同步。 * 对外服务时，向终端用户呈现统一的登录入口，体验一致。典型适用组合：飞书 + Lark（国内+海外分支机构）、飞书 + 钉钉（并购企业、多事业部并行）、Teams (Entra) + 本地 AD。 ## 方案选型在多 IDP 场景下，有两种典型部署模式，如下表所示： |**方案** |**适用场景** |**核心特点** | |---|---|---| |**方案 A：** 一个空间 + Identity 聚合多 IDP |希望在同一个 ArkClaw 空间内管理全部用户，统一做权限与组织架构 |在 Identity 创建一个用户池，配置多个外部 IDP，ArkClaw 侧使用 OIDC 协议对接，所有用户在一个身份池中。 | |**方案 B：** 多空间隔离 |不同业务主体之间需要完全隔离（如独立数据、独立计费、强合规隔离） |为每套身份源单独创建一个 ArkClaw 空间，每个空间配置一种认证协议，用户分别登录各自空间。 | 在无强隔离诉求情况下，优先选择**方案 A**，可实现以最小的运维成本实现统一身份管理，且后续可平滑扩展更多身份源。下文以**方案 A**（飞书 + 钉钉双 IDP 组合）为例，介绍完整配置流程。其他组合（如飞书 + 钉钉、Microsoft Teams + AD）的操作步骤相同，只需在下文**步骤 2** 中选择对应的外部 IDP 类型即可。

注意

如选择方案 B（多空间隔离），仅需在不同项目下分别开通一个 ArkClaw 空间：

每个空间单独配置一种认证协议（如空间1\-飞书、空间2\-Lark、空间3\-Teams），不要在一个空间中混合使用多种单 IDP 登录方式。

ArkClaw 空间之间相互独立，需要为每个空间单独购买席位、方舟 Plan，添加企业公共知识库、公共 Agent 模板等。

为每个空间单独配置安全策略（密码策略、MFA、登录 IP 白名单），保证强隔离场景下的合规要求。

## 注意事项 * **账号唯一标识与合并策略** * **推荐使用邮箱作为账号唯一标识**：要求所有 IDP 返回的用户必须拥有企业邮箱，Agent Identity （智能体身份和权限）可基于邮箱自动合并同一个自然人来自不同 IDP 的账号，避免出现重复账号。 * **员工 ID 作为强一致标识**：如企业存在正式员工、外包、供应商混用的情况，建议将企业员工 ID（工号）写入各 IDP 的扩展属性，Agent Identity 侧按员工 ID 做账号合并，邮箱仅作为辅助字段。 * **避免用手机号作为唯一标识**：跨国员工可能存在多个国家手机号，容易导致账号合并失败。 * **权限与组织同步** * Agent Identity 侧完成 IDP 接入后，可开启**组织架构自动同步**，将飞书/Lark 等部门、岗位信息同步到 Agent Identity，再由 ArkClaw 基于统一组织架构做空间、项目、知识库的授权。 * 多 IDP 场景下，建议在 ArkClaw 中**按“主体/区域/部门”划分权限**，避免来自不同 IDP 的用户因组织信息结构差异而被错配权限。 * **安全与合规** * **强制 HTTPS：** Agent Identity 的 Discovery URL、回调地址、ArkClaw 访问入口都必须使用 HTTPS，避免 Token 在传输过程中被窃听。 * **定期轮换密钥：** 建议每 **90** 天轮换一次 Identity 客户端密钥及各 IDP 的 App Secret，并同步更新 ArkClaw 配置。 * **多因素认证（MFA）：** 对管理员账号、高权限角色账号，建议在 Agent Identity 侧统一开启 MFA，不要在 ArkClaw 内再做一套独立 MFA，避免策略分散。 * **登录审计：** 开启 Agent Identity 与 ArkClaw 的登录审计日志，定期巡检异常登录（如短时间内跨国登录、失败次数过多等）。 * **离职 / 停用同步：** 确保 Agent Identity 与各 IDP 之间配置了账号停用/离职事件联动，员工离职后立刻在 Identity 中禁用账号，阻止其继续登录 ArkClaw。 ## 前置条件开始配置前，请确认以下条件均已满足： * 已开通火山引擎 ArkClaw 企业版，并拥有**租户管理员**或**身份管理权限，** 当前ArkClaw 企业版服务仅对已通过企业实名认证的用户开放。 * **尚未完成企业认证**：请参见[企业实名认证](https://www.volcengine.com/docs/6261/64937)。 * **已完成个人认证，需要升级为企业认证**：请参见[个人认证升级为企业认证](https://www.volcengine.com/docs/6261/65159)。

说明

如果您使用火山引擎IAM用户进行操作，已由主账号为 IAM 用户授权相关权限。具体操作请参见授权IAM用户使用ArkClaw企业版权限。

* 已开通 Agent Identity 服务，并拥有在 Agent Identity 中**创建用户池（User Pool）、创建客户端、配置外部身份提供商**的权限，相关操作参考[开通智能体身份和权限管理平台并完成授权](https://www.volcengine.com/docs/86848/2123358)。 * 已在各外部身份源（如飞书开放平台、Lark 开放平台、钉钉开放平台、Azure Portal 等）配置好自建应用，并获取到应用的 **App ID / Client ID** 与 **App Secret / Client Secret**。 * [配置飞书应用并获取信息](https://docs.volcengine.com/docs/87732/2356401?lang=zh#tXfPdJrI) * [配置钉钉应用并获取信息](https://docs.volcengine.com/docs/87732/2356402?lang=zh#3mdm2LMH) * 更多外部身份源的应用的配置及信息获取，请通过[快速入门](https://docs.volcengine.com/docs/87732/2374435?lang=zh)前往对应的认证方式文档，查看详细操作步骤。 * 确认所有用户的邮箱或手机号在各自建应用中已正确维护，用于 Agent Identity 侧账号合并/去重（如需要）。 ## 操作步骤整体流程分为三个阶段：在 Identity 创建用户池与客户端 → 在用户池下配置多个外部 IDP → 在 ArkClaw 中完成 OIDC 登录配置。 ### 步骤一：在 Agent Identity 创建用户池和客户端 1. 登录[智能体身份和权限控制台](https://console.volcengine.com/identity/region:identity+cn-beijing/user-pools?projectName=default)。 2. 在左侧导航栏选择 “用户身份管理”，单击“新建用户池”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_60035dc458bac4705765117a94546d9c.png) 3. 参考下表，配置用户池参数。 |参数 |说明 | |---|---| |**用户池名称** |设置用户池唯一的名称，本演示设置为 `my-app-docs`。 | |**用户池登录属性** |选择用户登录时可以使用的身份标识，本演示选择**用户名**、**手机号**、**邮箱。**

注意

此配置创建后不可修改。

| |**用户池注册属性** |选择用户注册时必须提供的身份标识，本演示选择**用户名、手机号。** | |**所属项目** |选择用户池所属的项目，用于资源隔离和管理，此处默认为当前项目，不做修改。 | 4. 配置完成后单击“确定”按钮，然后单击右上角图标关闭新建用户池页面。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_6ca2c72a5fbf8ec4e4b76cc3ff13eb02.png) 5. 在用户池列表中，单击刚创建的用户池名称，在左侧导航栏选择“客户端”，然后单击“创建客户端”按钮 **。** ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_5479481807a41195c1bea62573838c57.png) 6. 参考下表，配置客户端参数。 |参数 |说明 | |---|---| |**客户端名称** |设置应用客户端的名称，本演示设置为 `my-company-portal`。 | |**客户端类型** |根据应用类型选择客户端类型，本演示使用飞书、钉钉应用，所以选择 **Web 应用**。 | |**授权回调 URL** |用户成功登录并授权后，系统会将用户重定向到此地址。**现在先不填写此参数**，待完成后续 ArkClaw 空间开通后，将 ArkClaw 提供的“免登授权码跳转地址”回填至此处。 | 7. 配置完成后单击“确定”按钮，在客户端列表中，单击刚创建的客户端名称，在详情页中获取**客户端 ID** 和**客户端密钥**，后续需要在 ArkClaw 企业版平台配置这两个参数作为客户端的身份标识和密钥。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_5798925bbac3eb7680f1a2668583df02.png) ### 步骤二：在用户池下配置外部身份提供商（飞书、钉钉） 1. 在左侧导航栏用户池`my-app-docs`下选择“外部身份提供商”，单击“新建提供商”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c0a22a1db98153cf95d683bf440f5bb8.png) 2. 参考下表，添加第一个外部身份提供商（飞书），未提及参数保持默认。

说明

本示例仅介绍飞书、钉钉两种身份提供商的配置操作，如需添加其他类型的外部身份提供商，详见添加外部身份提供商。

|参数 |说明 | |---|---| |提供商名称 |输入外部身份提供商的名称，会在用户登录页内展示，用于用户登录时选择，本演示设置为**飞书**。 | |提供商类型 |外部身份提供者使用的认证协议，支持 OAuth 2.0、SAML 2.0、OIDC，本演示使用飞书和钉钉，均属于OAuth 2.0，所以此处选择 **OAuth 2.0 提供商**。 | |提供商 |选择实际的外部身份提供商，Agent Identity 当前预置了飞书、钉钉作为外部身份提供商，此处可以直接使用，所以此处选择**飞书。**

说明

如果是飞书、钉钉之外的外部身份提供商，此处选择“自定义”。

| |出口方式 |选择资源出口的方式，本演示选择**平台默认出口**。 | |客户端ID |飞书应用的 App ID，在[飞书开发者平台](https://open.larkoffice.com/app?lang=zh-CN)，单击进入目标飞书应用名称，在左侧目录树选择“基础信息 \> 凭证与基础信息”，获取 App ID。 | |客户端密钥 |飞书应用的 App Secret。在[飞书开发者平台](https://open.larkoffice.com/app?lang=zh-CN)，单击进入目标飞书应用名称，在左侧目录树选择“基础信息 \> 凭证与基础信息”，获取 App Secret。 | 3. 重复上述两步，添加第二个外部身份提供商（钉钉），配置完成后单击“确定”按钮。 |参数 |说明 | |---|---| |提供商名称 |输入外部身份提供商的名称，会在用户登录页内展示，用于用户登录时选择，本演示设置为**钉钉**。 | |提供商类型 |外部身份提供者使用的认证协议，此处选择 **OAuth 2.0 提供商**。 | |提供商 |选择实际的外部身份提供商，此处选择**钉钉。** | |出口方式 |选择资源出口的方式，本演示选择**平台默认出口**。 | |客户端ID |钉钉应用的 Client ID（原 AppKey 和 SuiteKey），在[钉钉开发者平台](https://open-dev.dingtalk.com/fe/app?hash=%23%2Fcorp%2Fapp#/corp/app)，单击目标应用名称，在左侧导航树选择“基础信息 \> 凭证与基础信息”，获取 Client ID。 | |客户端密钥 |钉钉应用的 Client Secret（原 AppSecret 和 SuiteSecret），在[钉钉开发者平台](https://open-dev.dingtalk.com/fe/app?hash=%23%2Fcorp%2Fapp#/corp/app)，单击目标应用名称，在左侧导航树选择“基础信息 \> 凭证与基础信息”，获取 Client Secret。 | |用户唯一标识属性 |从 OAuth 响应中提取的用户唯一标识属性（如 user_id/email），此处配置为 **unionId**。 |

说明

如还需接入Microsoft Entra ID（Teams）、本地 AD（通过 SAML/OIDC 代理），继续按照同样方式依次添加即可；所有外部身份提供商会在 Agent Identity 的统一登录页呈现为多个登录按钮。

### 步骤三：在 ArkClaw 配置 OIDC 登录协议 1. 开通 ArkClaw 空间。

说明

如果使用已开通的 ArkClaw 空间请跳过此步骤。

1. 登录 [ArkClaw 企业版控制台](https://console.volcengine.com/arkclaw/enterprise)，认证方式使用“**其他标准协议**”快速开通空间。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_7f68330ad1a3c2e87c4bef1f60a27097.png) 2. 按照界面指引单击“立即购买”按钮，购买席位。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_b97cbcb9d887ec17f24c6b0e21076c59.png) 2. 在左侧导航栏选择“用户管理”，配置认证方式。 1. 新创建的空间，单击“立即配置”按钮。已有用户数据的空间，在“登录配置”页签单击“编辑”按钮。 2. 参考下表配置参数，配置完成后单击“保存”按钮。 |配置项 |说明 | |---|---| |选择协议 |选择接入的身份认证协议。对 ArkClaw 来说此时接入的外部身份提供商是 Agent Identity，此处应选择 Agent Identity 的协议类型 **OIDC**。 | |客户端 ID |在 Agent Identity 侧创建的客户端的 ID。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_14bc2b315900eb20fd5fc2c4c237785e.png) | |客户端密钥 |在 Agent Identity 侧创建的客户端的密钥。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2eb883107bece78db55d001e10631fdd.png) | |Issuer URL |OIDC 身份提供商的唯一标识地址，系统将基于该地址自动发现授权端点、令牌端点及用户信息端点信息。

此处为 Agent Identity 侧创建的用户池的“OIDC 发现端点 Discovery URL”中的`https//域名`部分。

例如：

* OIDC 发现端点 Discovery URL 是：`https://userpool-a4894bb0-8665-xxxx-979a-ec87c2999b2c.userpool.auth.id.cn-beijing.volces.com/.well-known/openid-configuration`，

* Issuer URL 为`https://userpool-a4894bb0-8665-xxxx-979a-ec87c2999b2c.userpool.auth.id.cn-beijing.volces.com`

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_1042dcc6882983c0c7aca38c1f6138e4.png) | |唯一标识符策略 |唯一标识符策略用于**判定多次导入的同一员工**：当再次导入员工列表时，系统会根据您选的唯一标识符把同人的记录合并为一条。该字段**只决定合并依据，不决定登录方式**。

* **手机号：** 适合面向外部承包人员或临时账号的场景。

* **邮箱：** 适合企业内员工邮箱已规范统一的场景。

注意

唯一标识符策略一旦选定，建议不要中途切换：切换后已有员工记录可能无法与新导入的员工记录正确匹配，导致重复账号。

| ### 步骤四：配置 Agent Identity 客户端回调信息 1. 在用户管理页面“登录配置”页签下，复制“标准协议 OIDC 免登授权码跳转地址”信息。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_e38e9aebb6036c8904ee3260b9d72aa3.png) 2. 返回[火山引擎智能体身份和权限管理平台](https://console.volcengine.com/identity)，在左侧导航栏选择“用户身份管理 ”，在用户池列表中单击上文**步骤一**创建的用户池`my-app-docs`。 3. 在左侧导航树选择用户池`my-app-docs`下的“客户端”，然后在上文**步骤一**创建的客户端`my-company-portal`中单击“操作”列的“编辑”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_23e5a07e4a652aa20085f0a3bbd784a7.png) 4. 将复制的 ArkClaw 免登授权码跳转地址粘贴至“允许回调 URIs”，单击“确定”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_ca6993db51480d6a8cde91b66a016336.png) ### 步骤五：配置飞书应用/钉钉应用回调信息 1. 在[火山引擎智能体身份和权限管理平台](https://console.volcengine.com/identity)左侧导航栏选择“用户身份管理 ”，在用户池列表中单击上文**步骤一**创建的用户池`my-app-docs`。 2. 在用户池信息页面，复制“OAuth 注册回调地址”。

说明

因为飞书应用/钉钉应用是 OAuth 类型所以复制 OAuth 注册回调地址，如果配置的外部应用是其他类型（OIDC/SMAL），请复制对应类型的注册回调地址。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_5626f815e1f9a495cdd4c88831d46cee.png) 3. 配置飞书应用回调信息。 1. 前往[飞书开发者平台](https://open.larkoffice.com/app?lang=zh-CN)，单击在 Agent Identity 的外部身份提供商中配置的飞书应用名称。 2. 在“安全配置”页面，把复制的 OAuth 注册回调地址粘贴至**重定向 URL**（Redirect URL）中，单击“添加”按钮，添加后立即生效。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_af519caf4ae199c4eaaaf866dec4d3cf.png) 4. 配置钉钉应用回调信息。 1. 前往[钉钉开发者平台](https://open-dev.dingtalk.com/fe/app?hash=%23%2Fcorp%2Fapp#/corp/app)，单击在 Agent Identity 的外部身份提供商中配置的钉钉应用名称。 2. “安全配置”页面，把复制的 OAuth 注册回调地址粘贴至**重定向URL**（Redirect URL）中，单击“保存”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_58238445aa9bfe2362cfff308e7afd47.png) 3. 在左侧导航树，选择“应用发布 \> 版本管理与发布”，然后单击“创建新版本”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_47893b207acd733c1449dcd4db79941f.png) 4. 设置版本号、版本描述，**应用可用范围**沿用上次发布时配置的范围，无需再次配置。至此已完成全部配置。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_63b90b2829eb805f811b7da5758f4d43.png) ### 步骤六：功能验证 1. 在 [ArkClaw 企业版控制台](https://console.volcengine.com/arkclaw/enterprise)的“空间概览”中，复制员工登录链接。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_624a868ecd56074f9829f68d2099a14c.png) 2. 在浏览器中打开链接，进入登录界面，使用飞书或者钉钉登录，可以正常跳转到对应平台完成授权，首次登录时会自动在 ArkClaw 中创建账号，可在**用户管理 \> 用户列表**中看到新用户。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c5a81419b378fa3474d5066a76b2acff.png) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_850cb325de172cfeab26b01d464f29cc.png) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_72ee42701f06d715dda11de2b0d2ecf3.png)