ArkClaw 企业版支持通过 SAML 协议接入企业现有身份提供商（IdP），实现员工单点登录（SSO）。本文以 **Microsoft AD FS（Active Directory Federation Services）** 为例，指导管理员完成 ArkClaw 空间开通、上传 IdP 元数据、配置用户属性映射、在 AD FS 侧添加信赖方信任与 Claim 规则、回填回调地址的全流程，完成后即可把员工登录链接交付使用。

说明

使用其他标准协议可快速开通 ArkClaw 企业版，相关信息用于开通后的配置。

ArkClaw 支持在不同项目下开通独立的 ArkClaw 空间，此功能为白名单功能，仅开通后可用，详细操作及说明请参见开通多个空间。

## 前提条件 * 请确认已完成[账号注册](https://www.volcengine.com/docs/6261/64925)和[实名认证](https://www.volcengine.com/docs/6261/64935)。当前 ArkClaw 企业版服务仅对已通过企业实名认证的用户开放，如有需要建议您进行企业认证，认证成功后方可使用相关功能。 * 企业认证操作，请参见[企业实名认证](https://www.volcengine.com/docs/6261/64937)。 * 个人认证如何变更为企业认证，请参见[个人认证升级为企业认证](https://www.volcengine.com/docs/6261/65159)。 * 您已拥有可用的 AD FS 环境，并具备管理权限。 * 您已通过企业 IT 管理员获取身份提供商属性名。 * 您已通过访问 AD FS 的 IdP 元数据端点地址`https://{AD FS域名}/{FederationMetadata.xml的路径}`，下载 IdP 元数据 FederationMetadata.xml 文件。

说明

FederationMetadata.xml 的具体路径可在 AD FS 的 Endpoints 中查看，以下图为例，具体路径为“FederationMetadata/2007\-06/FederationMetadata.xml”。

## 名词说明 |名词 |说明 | |---|---| |SAML |一种常见的企业单点登录协议。您可以将它理解为企业身份系统向 ArkClaw 安全传递“当前登录用户是谁”的标准方式。 | |IdP（Identity Provider） |身份提供商，也就是负责登录认证的系统。例如本文中的 AD FS。 | |SP（Service Provider） |服务提供商，也就是接收登录结果并提供业务功能的系统。本文场景下，ArkClaw 就是 SP。 | |元数据（Metadata） |用于描述 SAML 对接信息的配置内容，通常包含登录地址、证书和协议能力。导入元数据后，您可以减少手动填写配置项的工作量。 | |SP Metadata |ArkClaw 作为服务提供商输出的一份元数据文件。身份提供商导入这份文件后，可以自动获取 ArkClaw 的必要对接信息。 | |唯一标识符策略 |用于唯一识别员工身份的字段。建议选择稳定、不会轻易变化的字段，例如邮箱或手机号。该字段配置错误，可能导致员工无法匹配已有的登录 ArkClaw 实例的账号。 | |身份提供商属性名 |企业身份系统（如 AD FS）在用户登录后，发送给 ArkClaw 的用户信息字段名称。ArkClaw 通过身份提供商属性名，找到对应的值（如邮箱地址、姓名等），与系统字段进行匹配。 | |Assertion（断言） |用户登录成功后，身份提供商（IdP）生成并签名的一份身份凭据，包含“用户是谁、何时登录”等信息。ArkClaw 收到后会验证这份凭据，确认登录身份可信。 | |响应签名验证 |对 IdP 返回的身份信息进行签名校验，确保内容未被篡改。 | |断言加密 |对 IdP 返回的身份凭据进行加密传输，防止登录信息在途中被读取。 | |Claim / Claim Rule |Claim 是企业身份系统（如 AD FS）为每位用户携带的属性信息，例如邮箱、姓名、工号。Claim Rule 决定将哪些属性发送给 ArkClaw。 | ## 步骤一：服务开通授权

说明

触发条件： 仅首次开通 ArkClaw 服务时执行；后续在同账号下再次开通空间会跳过本步。

授权范围： 一次性向 ArkClaw 授予访问下述云服务的权限：VPC、ECS、私网链接 PrivateLink、对象存储 TOS、机器学习平台（具体清单详见服务条款）。

模型开通： 同时一键开通火山方舟全部非 Coding Plan模型的调用权限，方便后续在 ArkClaw 中直接选择模型。

费用说明： 本步骤本身免费；后续使用已开通的模型、方舟服务、联网搜索时将按量计费并出账单，涉及计费的服务如下：

方舟服务

联网搜索

1. 登录 [ArkClaw 企业版控制台](https://console.volcengine.com/arkclaw/enterprise)，在左侧导航树中，选择“Claw 管理 \> Claw 列表”ArkClaw_groupArkCl管理 \> Claw 列表”。 2. 在弹出的对话框中，请您仔细阅读相关服务条款，确认无误后勾选“我已阅读并同意《ArkClaw 服务专用条款》”。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_78a2f095b3263f06e7ddf17d3705e231.png) 3. 单击“开通并授权”按钮，完成角色授权和模型开通操作。 ## 步骤二：ArkClaw 服务配置 1. 登录 [ArkClaw 企业版控制台](https://console.volcengine.com/arkclaw/enterprise)。 2. 在左侧导航树中，选择“Claw 管理 \> Claw 列表”。 3. 在服务开通页面，参考下表配置相关信息。 |配置项 |说明 | |---|---| |**基本信息** || |空间名称 |设置 ArkClaw 空间名称。平台会自动生成一个名称，管理员可按需修改，空间开通成功后，支持随时修改空间名称，详见[查看空间配置信息](https://www.volcengine.com/docs/87732/2272766?lang=zh#ftsmTKKb)。 | |**员工访问控制** || |认证方式 |配置企业员工访问控制信息，此处选择**其他标准协议**，选择其他标准协议后，无需在开通页面配置认证参数。 | |**网络配置** || |空间网络配置 |ArkClaw 企业版的VPC网段和子网网段。平台将在当前Region下，自动创建用于 ArkClaw 的私有网络（VPC）、子网、安全组等网络资源，搭建 ArkClaw 运行的网络环境。

注意

ArkClaw 企业版空间开通成功后，不支持修改VPC网段和子网网段。

* **随机网段创建**：

* 无需配置网段，平台会使用随机的私网网段为您创建 ArkClaw 的VPC和子网。

* 如果后期需要使用其他私有网络（VPC）访问 ArkClaw 私有网络的资源，请确保访问的私有网络（VPC）地址不属于以下网段，以免网段冲突：`192.18.0.0/15`、`33.0.0.0/8`、`66.0.0.0/8`、`9.0.0.0/8`。

* **指定网段创建**：

* 如果您后期需要通过云企业网（CEN）或中转路由器（TR）连接 ArkClaw 的私有网络，请基于您的网络规划在此指定 ArkClaw 的私有网络（VPC）网段。

* 单击卡片右上角“自定义配置”，输入自定义私有网络（VPC）的目标网段，平台会根据输入的网段创建VPC和子网。自定义网段请避免使用以下网段：`100.64.0.0/10`、`224.0.0.0/4`、`127.0.0.0/8`、`0.0.0.0/8`、`240.0.0.0/4`、`192.18.0.0/15`、`33.0.0.0/8 `、`66.0.0.0/8 `、`9.0.0.0/8`、`169.254.0.0/16`。

注意

指定 ArkClaw 私有网络为邀测功能，仅开通后可用，如有需要请联系客户经理开通。

| 4. 配置完成后单击“立即开通”按钮，完成服务空间配置操作。 ## 步骤三：购买 ArkClaw 企业版坐席 1. 登录 [ArkClaw 企业版控制台](https://console.volcengine.com/arkclaw/enterprise)。 2. 在左侧导航树中，选择“Claw 管理 \> Claw 列表”。 3. 在 ArkClaw 管理页面，单击“立即购买”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_1a55f30af09e49adeb482882b48c5d2c.png) 4. 配置 ArkClaw 席位规格、数量，并在下方选择购买时长。

注意

ArkClaw 席位购买门槛

ArkClaw 企业版席位单次购买数量不少于 5个（含），不足 5 个无法下单。

不同规格的席位适用的场景不同，您可按需组合购买不同数量的席位规格，更多计费介绍请参见计费说明。

Agent Plan Team 购买

购买 ArkClaw 席位时，可同步搭配购买 Agent Plan Team；也可选择仅购买席位，后续再按需补充。

Agent Plan Team 购买后不支持退订。

ArkClaw 席位和 Agent Plan Team 非一一对应关系，员工账号下所有 Claw 实例共享员工分配到的 Agent Plan Team。

Coding Plan Team 购买

当前暂不支持开通空间时购买 Coding Plan Team，如有需要请在空间开通后购买或纳管，具体操作请参见管理方舟Plan。

所有拥有 Coding Plan Team 对应席位等级使用权限的 Claw 实例，共享所有该席位等级的 Coding Plan Team 资源。

购买与变更限制

数量门槛：ArkClaw 席位与 Agent Plan Team 绑定购买时，需确保 ArkClaw 中的 Agent Plan Team 总数量不少于 5 个（包括从 ArkClaw 购买的 Agent Plan Team 和纳管火山方舟的 Agent Plan Team ），单次下单最多购买 1000 个（含）。

专用限制：在 ArkClaw 中下单购买的方舟 Plan，仅建议在 ArkClaw 范围内使用。

ArkClaw 企业版会周期性轮转纳管的方舟 Plan API Key，轮转时旧 API Key 立即失效。若您将该 Key 复用于 ArkClaw 之外的服务，会随轮转一并中断。

如果在多场景共享方舟 Plan，建议在火山方舟直接购买独立的方舟 Plan、获取独立 API Key，并以“自定义模型来源”的方式配置模型，具体操作请参见配置自定义模型池。

自动续费

系统默认勾选“自动续费”，以避免到期欠费导致 ArkClaw 不可用。您也可手动取消该选项，但需注意在席位到期前自行完成手动续费。

“自动续费开关”打开后，后续在空间下的所有新购、变更的订单均会开启自动续费。

|规格 |适用场景 | |---|---| |轻量版 Starter |入门体验与轻量任务专属，支持简单对话，少量工具调用。 | |标准版 Standard |日常生产主力版本，支持中等复杂度的工作流和多轮对话。 | |高级版 Premium |复杂任务支撑，可承载多工具并行调用、中型项目工作流。 | |旗舰版 Ultimate |大型项目与高负载场景专属，支持全链路复杂流程编排。 | ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_dc5fcabc32abb63cd5dc357b84abf8de.png) 5. 配置完成后单击“购买”按钮，根据页面指引支付相关费用，支付成功后单击“去控制台”按钮完成服务开通操作。服务开通大约 3～5 分钟，请您耐心等待。

注意

服务开通失败的常见原因“未完成企业实名认证”、“VPC 网段冲突”或“资源不足”，如均已确认无问题后仍开通失败，请复制页面上的错误信息，单击发起工单按钮处理。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_07c1b742f0c65faeddb25f75c7563f29.png) ## 步骤四：配置 SAML 协议信息 1. 在 [ArkClaw 企业版控制台](https://console.volcengine.com/arkclaw/enterprise)左侧导航树中，选择“组织管理 \> 用户管理”。 2. 在用户管理页面，单击“立即配置”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_abe10953b3007b11ba8318ea5a8d8bef.png) 3. 在“修改员工认证方式”页面，填写配置信息。 |配置项 |说明 | |---|---| |选择协议 |下拉框中选择“SAML”。 | |SAML 元数据 |粘贴从 AD FS 下载的 FederationMetadata.xml 文件内容。 | |用户属性映射 |输入用户属性映射信息。

* 系统字段：

* id_attribute：用户的唯一标识，ArkClaw 可用这个字段来区分不同用户。**必填**，通常映射到企业身份系统中的邮箱或工号。

* name：用户的全名，登录后显示在页面上的姓名。

* email：用户的邮箱地址，用于接收通知。

* phone_number：用户的手机号码。

* 身份提供商属性名：企业身份系统（如 AD FS）在用户登录后，发送给 ArkClaw 的用户信息字段名称。ArkClaw 通过这个名称，找到对应的值（如邮箱地址、姓名等），与左侧系统字段进行匹配。

说明

身份提供商属性名需找企业IT管理员获取。

例如企业用“http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress”这个名称来传递邮箱，就在对应“email”一行的身份提供商属性名处填写该名称，ArkClaw 即可将其识别为用户邮箱。

说明

唯一标识符策略用于判定多次导入的同一员工：当再次导入员工列表时，系统会根据您选的唯一标识符把同人的记录合并为一条。该字段只决定合并依据，不决定登录方式。

可选策略：

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

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

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

| 4. 配置完成后单击“保存”按钮，完成操作。 5. 在“用户管理”页面，选择“登录配置”页签，在“基础配置信息”区域单击“下载数据”按钮，下载 SP Metadata 文件。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_45614c17da6c413eecd121377a6e5177.png) ## 步骤五：配置回调信息 1. 登录 AD FS 管理控制台。 2. 在 AD FS 中添加信赖方信任（Relying Party Trusts）。 1. 在 AD FS 管理控制台左侧选择“Relying Party Trusts”，并单击右侧“Add Relying Party Trust...”。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_9d1d09cbc9dca61b05c47f797c710620.png) 2. 默认选择“Claims aware”，单击“Start”按钮。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_cef31976a90e4cbef31c62c8c130017e.png) 3. 选择通过文件导入配置，并选择从 ArkClaw 下载获取的 SP Metadata 文件。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c2c2afe8bf4c2f190a122afede8ddd74.png) 4. 按需设置应用名称（Display Name）与访问控制策略（Access Control Policy）后，单击“Next”按钮，完成添加操作。

说明

应用名称：为这条信任记录起一个便于识别的名称（例如"ArkClaw"），方便后续在 AD FS 管理控制台中快速找到它。

访问控制策略：决定哪些用户可以通过 AD FS 登录 ArkClaw 。如无特殊要求，保持默认设置（允许所有用户）即可。

3. 配置 AD FS SAML 客户端返回的用户信息。即通过添加新的规则，选择目标用户信息传递给 ArkClaw。

注意

请确保传递给 ArkClaw 的用户信息中，包含了用户唯一标识属性。

1. 单击目标信任记录，并单击“Edit Claim Issuance Policy...”。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_db0eeedb5c8b54d91aa9f7c712c5fd6e.png) 2. 单击“Add Rule”按钮，添加规则。

说明

具体配置规则可参考了解用户信息是如何传递的和如何配置AD FS向应用发送用户信息字段。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_e0253d218d8184e9f5f119f0938bfa50.png) ## 步骤六：发放员工登录地址返回 [ArkClaw 企业版控制台](https://console.volcengine.com/arkclaw/enterprise)，在“空间概览”中复制员工登录链接，并通过企业内部渠道把链接传递给需要使用 ArkClaw 的员工。