本文介绍如何通过`agentkit auth admin sso-setup`命令，为企业用户配置AgentKit CLI的统一登录入口。完成配置后，终端用户无需本地配置AK/SK，即可通过浏览器完成登录，并自动获取短期STS凭据。 ## 背景介绍 `agentkit auth admin sso-setup`是AgentKit CLI面向管理员提供的单点登录配置命令。执行该命令后，系统会创建或复用 AgentKit CLI登录所需的身份认证资源，包括： * **用户池（UserPool）** ：用于集中管理可登录用户。 * **CLI 客户端**：用于AgentKit CLI发起登录请求。 * **开放身份连接（OIDC）身份提供方（Provider）** ：用于建立CLI登录与云账号之间的信任关系。 * **安全令牌服务（STS）角色**：用于登录成功后签发短期访问凭据。 * **登录发现文档（Discovery Doc）** ：用于向CLI提供统一登录入口与OIDC元数据。终端用户访问登录地址时，会依赖该文档完成发现流程。配置完成后，企业可以向终端用户分发统一登录地址。终端用户执行 `agentkit login` 后，通过浏览器完成登录，由系统自动换取短期STS凭据。 ## 适用场景 `agentkit auth admin sso-setup`命令适用于以下场景： * 企业管理员需要为内部用户统一配置AgentKit CLI登录入口。 * 不希望在终端用户本机长期保存云账号AK/SK的企业。 * 企业已有单点登录（SSO）体系，需要通过联邦登录接入现有IdP。 * 需要通过自定义域名对外提供品牌化登录入口。如果仅为个人开发者自用，且没有多用户统一登录的需求，建议直接使用AK/SK完成CLI登录，无需执行本文操作。 ## 前提条件 * 已[开通AgentKit服务](https://console.volcengine.com/AgentKit)，且具备**AgentKitSandboxAccess**系统策略。 * 已安装AgentKit CLI。 * 已登录平台控制台[获取AK/SK](https://www.volcengine.com/docs/6291/65568)，进入[API访问密钥](https://console.volcengine.com/iam/keymanage/)页面，创建并获取**Access Key ID**和**Secret Access Key。** > 如使用临时凭据，还需获取 VOLCENGINE_SESSION_TOKEN。 * （可选）若需将登录发现文档发布到TOS，需在终端安装TOS SDK，并[开通对象存储 TOS](https://console.volcengine.com/tos)和创建允许**public\-read**的Bucket。安装命令如下： ```Bash pip install tos ``` * （可选）**接入企业已有SSO**，需获取[用户池UID](https://www.volcengine.com/docs/86681/2549770)、上游IdP类型、client\-id、client\-secret，以及修改IdP应用回调白名单的权限。 * （可选）若上游IdP类型为飞书，请确认飞书应用已具备如下权限。如何配置，请参见[创建飞书机器人并获取配置](https://www.volcengine.com/docs/86681/2222895?lang=zh#XP0gAsPT)。 ```Bash { "scopes": { "tenant": [ "contact:user.base:readonly", "contact:user.email:readonly" ], "user": [] } } ``` * （可选）若使用自定义登录域名，请确认已有可使用的域名，并已配置CNAME和HTTPS证书。

说明

您可以通过执行agentkit auth admin doctor一键核验STS凭据、用户池、IAM、沙箱权限策略及相关数据面组件健康状态。该命令只排查不改动资源，自动输出问题点与修复方案，支持 --no-data-plane 参数跳过数据面检测。

## 步骤一：配置SSO登录以下步骤由企业管理员执行。 ### 1.配置管理员凭据执行以下命令配置管理员凭据。 ```Bash export VOLCENGINE_ACCESS_KEY= export VOLCENGINE_SECRET_KEY= # 临时凭据需额外设置： export VOLCENGINE_SESSION_TOKEN= ``` ### **2.启动配置向导** 执行以下命令启动配置向导。 ```Bash agentkit auth admin sso-setup ``` 命令启动后，系统会自动验证AK/SK是否有效，并确认凭据归属账号。如下所示： > 如果校验失败，请先修复凭据无效或账号不匹配问题，再重新执行配置命令。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_9b5e9ba34bc3b62cadf347375677a3ac.png) ### 3.配置关键参数配置向导会引导您完成以下设置：不接入上游 IdP 联邦登录该场景适用于企业不依赖外部身份体系，由AgentKit自身管理用户登录。配置完成后，需要前往[AgentKit-身份与权限](https://console.volcengine.com/agentkit/region:agentkit+cn-beijing/identity?pageSize=10¤tPage=1)创建可登录用户，详情请参见[创建用户](https://www.volcengine.com/docs/86681/2549772)。 |参数 |说明 | |---|---| |是否复用已有 UserPool |直接按Enter键，不复用UserPool，系统将在最终确认后新建默认名为agentkit\-cli\-pool的UserPool。

说明

您可以登录AgentKit\-身份与权限页面，查看创建的名为agentkit\-cli\-pool的UserPool。

| |是否需要与上游 IdP 做联邦登录 |输入 `n` ，不接入企业SSO。 | |是否定制 SSO 登录地址 |配置终端用户执行`agentkit login`时使用的登录入口地址。

* 如使用默认地址，直接按 Enter 键。

* 如使用自定义域名，输入域名，例如`login.example.com`。域名中不要包含 `https://`。 | 接入上游 IdP 联邦登录该场景适用于企业已有外部身份体系（如飞书），希望终端用户直接通过企业账号登录，无需在AgentKit侧单独维护用户。 |参数 |说明 | |---|---| |是否复用已有 UserPool |选择是否使用已有UserPool。

* 若使用已有UserPool，输入UserPool UID（即用户池ID）。例如38ed3b8c\-\*\*\*\*\-40b2\-99b7\-69fe0288\*\*\*\*。

* 若不复用UserPool，直接按Enter键。系统将在最终确认后新建默认名为agentkit\-cli\-pool的UserPool。

说明

您可以登录AgentKit\-身份与权限页面，获取和查看用户池ID。

| |是否需要与上游 IdP 做联邦登录 |输入 `y`，并填写IdP类型（例如，feishu）、client\-id和client\-secret。

说明

若您已经在智能体身份和权限控制台中为目标用户池创建客户端和添加外部身份提供商，直接按Enter键跳过该步骤，系统将自动复用目标用户池中已有的客户端和外部身份提供商配置。

| |是否定制 SSO 登录地址 |配置终端用户执行`agentkit login`时使用的登录入口地址。

* 如使用默认地址，直接按 Enter 键。

* 如使用自定义域名，输入域名，例如`login.example.com`。域名中不要包含 `https://`。 | ### 4.确认并记录输出信息配置向导完成后，系统会展示将要创建或复用的资源清单，包括身份池、CLI客户端、OIDC Provider、STS角色和登录地址等。 * 确认无误后，按Enter键或输入`y`。 * 如发现配置有误，输入`n` 退出。重新执行[启动配置向导](https://docs.volcengine.com/docs/86681/2558655#llZjkclf)命令，完成配置。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_b1c284c3873395897d10bc849092421a.png) 命令成功后，请记录以下关键信息，用于后续分发和运维。 * 登录地址：用于发送给终端用户，供其执行`agentkit login`时访问。 * 智能体身份和权限控制台链接：用于进入身份池管理页面，创建或管理可登录用户，详情请参见[创建用户](https://www.volcengine.com/docs/86681/2549772)。 * 资源清单：用于记录已创建或复用的各项资源。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_ecb8ee2f23b10bfedb23c9bfa53dc29b.png) ### 5.（可选）配置回调URL 若存在以下任一情况，需在上游IdP应用的允许回调地址白名单中添加回调URL，否则终端用户完成企业账号认证后，无法正常返回目标用户池，登录流程将失败。 * 在[配置关键参数](https://docs.volcengine.com/docs/86681/2558655#wQhNNvra)中选择接入上游IdP联邦登录。 * 已在智能身份和权限控制台中为目标用户池手动创建客户端并添加外部身份提供商。 1. **获取回调URL。** * 场景一：通过`sso-setup`命令新建上游IdP连接器若您在命令行中输入`y`并完成IdP类型、client\-id 和 client\-secret 的填写，命令执行完成后，终端会输出一条警告提示，请直接从中复制回调 URL。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_abb6a0d4833d44c7e7c7ad8a837c97b5.png) * 场景二：已在控制台中手动配置客户端和外部身份提供商若您已在[智能身份和权限控制台](https://console.volcengine.com/agentkit/region:agentkit+cn-beijing/identity)中为目标用户池创建了客户端并添加了外部身份提供商（[配置关键参数](https://docs.volcengine.com/docs/86681/2558655#wQhNNvra)中直接按Enter键跳过），可在客户端详情页面获取回调URL。 1. 进入[智能身份和权限—用户身份管理](https://console.volcengine.com/identity/region:identity+cn-beijing/user-pools)页面。 2. 单击目标用户池ID。 3. 在外部身份提供商回调URL区域，复制目标外部提供商登录回调地址。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c3edf7704b8a5a37e05c97799b001b4a.png) 2. **将回调URL添加到上游IdP应用。** 获取回调URL后，根据上游IdP类型，在对应平台完成配置。本文以上游IdP设置为飞书为例，介绍配置回调URL。 1. 登录[飞书开放平台](https://open.feishu.cn/app)，进入[配置关键参数](https://docs.volcengine.com/docs/86681/2558655#wQhNNvra)中配置的企业自建应用。 2. 在左侧导航栏，选择“开发配置 \> 安全设置”。 3. 在重定向URL配置项中，将回调 URL 完整粘贴后单击“添加”按钮，保存配置。 ## 步骤二：验证终端用户登录以下步骤由终端用户执行，管理员也可参考以下步骤进行验收。 1. 终端用户执行执行以下命令完成 CLI 登录。 ```Bash agentkit login https://<登录地址> ``` 2. 在打开的浏览器中，完成身份验证。 * **未接入上游 IdP 联邦登录**：直接在登录页输入用户名和密码。 > 首次登录，请根据提示信息，重置密码。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d0d9c3f444db37e211025f675895ebad.png) * **已接入上游 IdP 联邦登录：** 单击“使用XX登录”按钮，通过企业账号完成认证。 > 以下展示的图片仅为参考，请以您实际展示的页面为准。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_63b78f3f1b67f61c2aca19e931a421f1.png) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_14c573e26a48de45e0b31a94508863b1.png) 3. 在授权访问页面，确认信息无误后，单击“允许访问”。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_72ba75cd90187aad3582616293fd7727.png) 4. 完成授权后，返回终端页面，系统将返回以下信息，表示登录成功。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d01ce9de220cbbbc6365db24ac947810.png) 5. 执行以下命令查看登录状态。 ```Bash agentkit auth whoami ``` 如果返回以下信息，说明 SSO 链路、OIDC 信任链和 STS 权限均已可用，全流程已跑通。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_e9156742a0db0bb4568509b7ec9bca3a.png) ## 常见问题与解决方案 |**常见报错** |原因 |解决方案 | |---|---|---| |`admin provisioning needs Volcengine credentials.` |终端环境未配置 AK/SK |执行 `export VOLCENGINE_ACCESS_KEY=`和 `export VOLCENGINE_SECRET_KEY=`后重试 | |`refusing to provision: caller account != expected ` |当前 AK/SK 所属账号与 `--account`指定的账号不匹配 |切换为目标账号的凭据，或更正`--account`参数值；不需要校验账号时也可移除该参数 | |`非交互模式下用 --idp 需同时提供 --idp-client-id 与 --idp-secret。` |使用了` --idp` 但未同时提供` --idp-client-id` 与` --idp-secret` |补充完整两个参数后重新执行 | |`idp needs an app client-id and secret` |`client-id`和`secret`参数值为空 |重新执行[启动配置向导](https://docs.volcengine.com/docs/86681/2558655#llZjkclf)命令，完成上游IdP应用的`client-id`与`secret`配置。 | |`OIDC provider '<名>' already exists for a different issuer` |账号中已有同名 OIDC Provider，绑定的 issuer 与本次不一致 |通过 \-\-provider\-name 指定新名称后重试，或删除旧 Provider 后重新执行[启动配置向导](https://docs.volcengine.com/docs/86681/2558655#llZjkclf)命令 | |`AgentKit system policy 'AgentKitSandboxAccess' not found — activate AgentKit on this account first` |账号未开通 AgentKit，缺少系统策略 AgentKitSandboxAccess |开通AgentKit，再重新执行；建议执行前先运行 `agentkit auth admin doctor` | |`publishing needs the 'tos' package` |本地未安装TOS SDK |执行`pip install tos` 后重试 | |`could not create the TOS bucket for the discovery doc` |账号未开通TOS，或桶名已被占用 |开通 TOS，或更换存储桶名称 | |`the discovery doc is not publicly readable (HTTP 403)` |账号或存储桶开启了禁止公网访问限制 |关闭账号级或取消禁止公网访问设置后重新执行 | |`could not verify the published discovery doc at ` |网络或代理异常，或返回内容非有效JSON |检查网络与代理配置后重试 | |`CreateUserPool: Duplicated: A user pool with the same identifier already exists.` |账号下已有同名用户池（默认名 agentkit\-cli\-pool），常见于上次执行中途中断 |登录[智能身份和权限控制台](https://console.volcengine.com/agentkit/region:agentkit+cn-beijing/identity)获取用户池ID后，重新执行[启动配置向导](https://docs.volcengine.com/docs/86681/2558655#llZjkclf)命令配置UserPool时直接输入获取的用户池ID，或通过 `--create-pool `指定新名称 | |`ListUserPoolClients: NotFound: The requested resource was not found: UserPool` |填写的是用户池名称而非 Uid，或Uid不存在于当前账号/地域 |登录[智能身份和权限控制台](https://console.volcengine.com/agentkit/region:agentkit+cn-beijing/identity)获取用户池ID后，重新执行[启动配置向导](https://docs.volcengine.com/docs/86681/2558655#llZjkclf)命令 | |`CreateUserPool returned no uid` |Identity服务返回异常响应，属于服务端暂时性问题 |直接重新执行[启动配置向导](https://docs.volcengine.com/docs/86681/2558655#llZjkclf)命令，多次失败请联系平台技术支持 | |`could not create or find the public CLI client` |客户端创建后服务端未返回客户端ID，属于暂时性异常 |直接重新执行[启动配置向导](https://docs.volcengine.com/docs/86681/2558655#llZjkclf)命令，如多次重试仍失败，请检查Identity服务状态或联系平台技术支持 |