文档中心

ArkClaw 企业版

最佳实践

多 IDP 组合接入 ArkClaw 最佳实践

本文为您介绍在一个企业下同时存在多种身份体系的场景下，如何实现多 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 企业版服务仅对已通过企业实名认证的用户开放。

尚未完成企业认证：请参见企业实名认证。

已完成个人认证，需要升级为企业认证：请参见个人认证升级为企业认证。

说明

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

已开通 Agent Identity 服务，并拥有在 Agent Identity 中创建用户池（User Pool）、创建客户端、配置外部身份提供商的权限，相关操作参考开通智能体身份和权限管理平台并完成授权。

已在各外部身份源（如飞书开放平台、Lark 开放平台、钉钉开放平台、Azure Portal 等）配置好自建应用，并获取到应用的 App ID / Client ID 与 App Secret / Client Secret。

配置飞书应用并获取信息

配置钉钉应用并获取信息

更多外部身份源的应用的配置及信息获取，请通过快速入门前往对应的认证方式文档，查看详细操作步骤。

确认所有用户的邮箱或手机号在各自建应用中已正确维护，用于 Agent Identity 侧账号合并/去重（如需要）。

操作步骤

整体流程分为三个阶段：在 Identity 创建用户池与客户端 → 在用户池下配置多个外部 IDP → 在 ArkClaw 中完成 OIDC 登录配置。

步骤一：在 Agent Identity 创建用户池和客户端

登录智能体身份和权限控制台。

在左侧导航栏选择 “用户身份管理”，单击“新建用户池”按钮。

参考下表，配置用户池参数。

参数	说明
用户池名称	设置用户池唯一的名称，本演示设置为 my-app-docs。
用户池登录属性	选择用户登录时可以使用的身份标识，本演示选择用户名、手机号、邮箱。注意此配置创建后不可修改。
用户池注册属性	选择用户注册时必须提供的身份标识，本演示选择用户名、手机号。
所属项目	选择用户池所属的项目，用于资源隔离和管理，此处默认为当前项目，不做修改。

配置完成后单击“确定”按钮，然后单击右上角图标关闭新建用户池页面。

在用户池列表中，单击刚创建的用户池名称，在左侧导航栏选择“客户端”，然后单击“创建客户端”按钮。

参考下表，配置客户端参数。

参数	说明
客户端名称	设置应用客户端的名称，本演示设置为 my-company-portal。
客户端类型	根据应用类型选择客户端类型，本演示使用飞书、钉钉应用，所以选择 Web 应用。
授权回调 URL	用户成功登录并授权后，系统会将用户重定向到此地址。现在先不填写此参数，待完成后续 ArkClaw 空间开通后，将 ArkClaw 提供的“免登授权码跳转地址”回填至此处。

配置完成后单击“确定”按钮，在客户端列表中，单击刚创建的客户端名称，在详情页中获取客户端 ID 和客户端密钥，后续需要在 ArkClaw 企业版平台配置这两个参数作为客户端的身份标识和密钥。

步骤二：在用户池下配置外部身份提供商（飞书、钉钉）

在左侧导航栏用户池my-app-docs下选择“外部身份提供商”，单击“新建提供商”按钮。

参考下表，添加第一个外部身份提供商（飞书），未提及参数保持默认。

说明

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

参数	说明
提供商名称	输入外部身份提供商的名称，会在用户登录页内展示，用于用户登录时选择，本演示设置为飞书。
提供商类型	外部身份提供者使用的认证协议，支持 OAuth 2.0、SAML 2.0、OIDC，本演示使用飞书和钉钉，均属于OAuth 2.0，所以此处选择 OAuth 2.0 提供商。
提供商	选择实际的外部身份提供商，Agent Identity 当前预置了飞书、钉钉作为外部身份提供商，此处可以直接使用，所以此处选择飞书。说明如果是飞书、钉钉之外的外部身份提供商，此处选择“自定义”。
出口方式	选择资源出口的方式，本演示选择平台默认出口。
客户端ID	飞书应用的 App ID，在飞书开发者平台，单击进入目标飞书应用名称，在左侧目录树选择“基础信息 > 凭证与基础信息”，获取 App ID。
客户端密钥	飞书应用的 App Secret。在飞书开发者平台，单击进入目标飞书应用名称，在左侧目录树选择“基础信息 > 凭证与基础信息”，获取 App Secret。

重复上述两步，添加第二个外部身份提供商（钉钉），配置完成后单击“确定”按钮。

参数	说明
提供商名称	输入外部身份提供商的名称，会在用户登录页内展示，用于用户登录时选择，本演示设置为钉钉。
提供商类型	外部身份提供者使用的认证协议，此处选择 OAuth 2.0 提供商。
提供商	选择实际的外部身份提供商，此处选择钉钉。
出口方式	选择资源出口的方式，本演示选择平台默认出口。
客户端ID	钉钉应用的 Client ID（原 AppKey 和 SuiteKey），在钉钉开发者平台，单击目标应用名称，在左侧导航树选择“基础信息 > 凭证与基础信息”，获取 Client ID。
客户端密钥	钉钉应用的 Client Secret（原 AppSecret 和 SuiteSecret），在钉钉开发者平台，单击目标应用名称，在左侧导航树选择“基础信息 > 凭证与基础信息”，获取 Client Secret。
用户唯一标识属性	从 OAuth 响应中提取的用户唯一标识属性（如 user_id/email），此处配置为 unionId。

说明

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

步骤三：在 ArkClaw 配置 OIDC 登录协议

开通 ArkClaw 空间。

说明

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

按照界面指引单击“立即购买”按钮，购买席位。

在左侧导航栏选择“用户管理”，配置认证方式。

新创建的空间，单击“立即配置”按钮。已有用户数据的空间，在“登录配置”页签单击“编辑”按钮。

参考下表配置参数，配置完成后单击“保存”按钮。

配置项	说明
选择协议	选择接入的身份认证协议。对 ArkClaw 来说此时接入的外部身份提供商是 Agent Identity，此处应选择 Agent Identity 的协议类型 OIDC。
客户端 ID	在 Agent Identity 侧创建的客户端的 ID。
客户端密钥	在 Agent Identity 侧创建的客户端的密钥。
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
唯一标识符策略	唯一标识符策略用于判定多次导入的同一员工：当再次导入员工列表时，系统会根据您选的唯一标识符把同人的记录合并为一条。该字段只决定合并依据，不决定登录方式。手机号：适合面向外部承包人员或临时账号的场景。邮箱：适合企业内员工邮箱已规范统一的场景。注意唯一标识符策略一旦选定，建议不要中途切换：切换后已有员工记录可能无法与新导入的员工记录正确匹配，导致重复账号。