登录来源即身份提供商（IdP），是一种存储和验证用户身份的服务。IdP 通常是云托管服务，常常与单点登录（SSO）提供程序搭配来验证用户的身份。配置登录来源后，将允许用户使用其已有的企业账户（例如企业微信、飞书）或社交账户（如 Google）登录您的应用，您也无需在用户池中为这些用户创建和管理密码。 ## 前提条件 * 已创建用户池。相关操作，请参见 [创建用户池](https://docs.volcengine.com/docs/AgentKit/create-user-pool)。 * 已经选定企业正在使用的身份源，例如飞书、钉钉、企业微信、Okta / Azure AD / Keycloak 等 OIDC IdP、ADFS 等 SAML IdP，或者仅用于测试的本地密码账号。如果选企业 SSO（飞书 / 钉钉 / 企微 / OIDC / SAML），请提前约好相关方 IdP / 办公平台管理员协同操作，建议不要业务侧独自尝试。 ## 通用操作步骤 1. 登录 [AgentKit 控制台](https://console.volcengine.com/identity)。 2. 在左侧导航栏，选择“身份与权限 \> 用户管理”。 3. 在目标用户池右侧“操作”列中单击“新建登录来源”。 4. 配置登录来源参数。 1. **选类型**：选择 Agent 的外部身份类型，并设置登录来源名称。 * **类型**：AgentKit 支持的外部身份类型如下表所示。 |**类型** |**本质** |**您需要做什么** |**前置权限 / 限制** |选型推荐 | |---|---|---|---|---| |飞书 |飞书 OAuth 2.0 联合登录

|飞书管理员手机扫码授权，平台自动建应用、自动拿 App ID / Secret，管理员只需回填一条重定向 URL。 |需要飞书管理员扫码权限。应用默认申请用户基本信息 / 邮箱 / user ID 等通讯录只读权限。 |国内企业、已用飞书办公，**首选** | |钉钉 |钉钉 OAuth 2.0 联合登录 |在钉钉开放平台自建应用，将 Client ID 与 Secret 填入向导。 |需要用户在钉钉开放平台有自建应用创建与发布权限。 |已用钉钉办公的企业 | |企业微信 |企业微信 OAuth 联合登录 |填入企业微信自建应用凭据，并在企微后台将 AgentKit 出口 IP 加进可信 IP 白名单。 |**必须使用固定出口 IP**，否则企微服务端会拒绝回调请求，状态报异常。 |已用企业微信办公 / 进行客户联系的企业 | |企业 OIDC |标准 OIDC 2.0，对接任意兼容 IdP |在 IdP 侧建好 OIDC 应用，将 Issuer、Client ID、Client Secret、授权 / Token / UserInfo 地址、Scope 填入向导。 |IdP 需支持 OIDC（Okta、Azure AD / Entra ID、Keycloak、Auth0、企业内部 IdP 等均可）。 |外企、跨国团队、自研 IdP、使用 Okta / Entra ID 的客户 | |SAML 2.0 |SAML 2.0 Web SSO |与用户 IdP 交换 SAML Metadata（或手动填 IdP 元数据 / 签名证书），将 AgentKit 提供的 ACS 回调地址与 Entity ID 配置到 IdP。 |* 需要用户 IdP 管理员协同操作。

* 老 IdP 通常仅支持 SAML。 |金融、政府、大型国企，IdP 为 ADFS / Ping Identity 等传统系统 | |密码用户 |AgentKit 本地账号密码登录，不接外部 IdP |在“用户管理”中手动或批量创建账号，用户使用用户名和密码登录。 |* 没有外部身份源，账号生命周期需自行管理。

* 不建议作为生产 SSO 长期使用。 |POC 演示、内部测试、临时小团队 | * **名称**：自定义设置用户登录时能看懂的名字，例如`公司员工`、`合作伙伴门户`、`测试账号`。该名称会出现在登录页按钮和 Agent 表单里。 2. **授权或填参数**：根据所选的外部身份类型进行授权操作，例如飞书进行扫码操作、钉钉 / 企微 / OIDC / SAML 填写对应凭据与端点。 3. **填写回调地址**：复制向导给出的回调 URL，粘贴到外部 IdP 的“重定向 URL / Redirect URI / ACS”位置，再回到向导单击“我已回填并保存”。 4. **完成并验证登录**：使用一个真实账号，单击“打开登录页验证”，完成一次真实 SSO 登录。拿到授权码后，登录来源状态才会从“待验证”变为“可用”。

说明

登录来源列表里该条记录显示状态为“可用”，且“被哪些 Agent 使用”中能看到您后续绑定的 Agent。

## 各类型身份源详细操作步骤飞书（推荐） ### 前置准备已在飞书开放平台创建了自建应用。更多说明，请参见 [飞书开放平台文档](https://open.larkoffice.com/document/develop-process/self-built-application-development-process)。 ### 操作步骤 2. 在 [AgentKit 控制台](https://console.volcengine.com/identity)，按通用操作步骤说明选“飞书”，填写名称，然后单击“下一步”。 3. 页面出现二维码，用飞书 App 扫码。手机端确认以企业名义创建内部应用，向导会自动申请通讯录只读权限（用户基本信息、邮箱、user ID）。 4. 扫码成功后，向导会自动填入 App ID 和 App Secret。 5. AgentKit 控制台页面提示"管理员已确认，应用凭据已自动填入"后单击“创建”。 6. 复制系统提供的回调地址，并根据控制台指引将其粘贴到飞书开放平台。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_a05d667fcb1227e5653ed651a146745d.png) 7. 在飞书开放平台，找到前提条件中创建的企业自建应用，按照 AgentKit 控制台示意图，将回调地址粘贴进去对应位置并保存。 8. 回到 [AgentKit 控制台](https://console.volcengine.com/identity)，台勾选“我已回填并保存”，然后单击“创建”。 9. 单击“打开登录页验证”，用真实飞书账号完成一次登录授权。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d7f877c1f73a8012b467af908377f948.png) 10. 授权登录后，看到 Identity 测试页正常拿到您的用户信息，即代表飞书 OAuth 链路已打通。向导默认创建的是 **Web 类型客户端**，适配员工浏览器 SSO。CLI、M2M、SPA、移动应用等客户端类型不在此向导里，需要事后到"客户端列表"手动创建。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_04627fe0311c5c5e5808cf7e004df814.png) 钉钉 ### 前提条件 * 在钉钉开放平台创建一个企业内部应用，获取 Client ID 与 Client Secret。更多说明，请参见 [钉钉开发者平台文档](https://open.dingtalk.com/document/development/basic-concepts-beta)。 * 钉钉企业内部应用已开通以下权限，开通方法，请参见 [钉钉开发者平台文档](https://open.dingtalk.com/document/personalapp/add-interface-call-permissions)： * `openid`（基础登录，默认开通该权限） * `Contact.User.Read`（通讯录个人信息读权限） * 如需手机号/邮箱，还需要开通 `Contact.User.mobile` 等 ### 操作步骤 1. 在 [AgentKit 控制台](https://console.volcengine.com/identity)，按通用操作步骤说明选“钉钉”，填写名称，然后单击“下一步”。 2. 把前提条件中获取的 Client ID 和 Client Secret 粘贴到对应输入框，然后单击“创建”。 3. 复制系统提供的回调地址，填到钉钉开放平台目标应用的“开发配置 \> 分享设置”页面的“回调域名”配置项里并保存。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_339597b31d8b544f101dc3e7edd970bc.png) 4. 回到 [AgentKit 控制台](https://console.volcengine.com/identity)，勾选“我已回填并保存”，然后单击“创建”。 5. 单击“打开登录页验证”，用钉钉账号完成一次真实授权。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_049f16c15163cdd00543bdfbf6fc5b08.png) 6. 授权登录后，看到 Identity 测试页正常拿到您的用户信息，即代表钉钉 OAuth 链路已打通。钉钉侧需要在应用权限里开启“登录账号信息”相关 OAuth 权限，并把应用版本发布到 **已上线** 状态，否则登录会报 Scope 缺失。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_04627fe0311c5c5e5808cf7e004df814.png) 若 SSO 联通性测试结果显示失败，可根据系统提示修复问题。常见情况下，因钉钉 OAuth 2.0 版本原因，会报`failed to get user id from userinfo with id attribute: userid`错误，您可以在 AgentKit 控制台找到目标钉钉身份源，编辑身份源信息，将“用户唯一标识属性”的值改为`openId`。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_aa0110d5d85b21ec0b1041da86107e88.png) 企业微信 ### 前提条件 * 在企业微信管理后台创建自建应用，获取企业 ID（CorpID）、AgentId、Secret。更多说明，请参见 [企业微信开发者中心文档](https://developer.work.weixin.qq.com/document/path/90664)。 * 在 AgentKit 出口 IP 管理中为该用户池申请固定出口 IP，并把该 IP 段加入企业微信后台的“可信 IP / 企业 IP 白名单”。未加白名单会直接报回调失败。 ### 操作步骤 1. 在 [AgentKit 控制台](https://console.volcengine.com/identity)，按通用操作步骤说明选“企业微信”，填写名称，然后单击“下一步”。 2. 把前提条件中获取的企业 ID、AgentId 和 Secret 粘贴到对应输入框，然后单击“创建”。 3. 复制系统提供的回调地址，打开企业微信管理后台，进入目标应用后，在应用详情页面单击“网页授权及 JS\-SDK”模块的“设置可信域名”，将回调地址粘贴进去并保存。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_a30b9e43d006abf231a3b349981d2dc4.png) 4. 复制 AgentKit 提供的 IP，将其粘贴到企业微信应用的“企业可信 IP”模块并保存。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_cac570c196ea415acbd1637968ef97fe.png) 5. 回到 [AgentKit 控制台](https://console.volcengine.com/identity)，勾选“我已回填并保存”，然后单击“创建”。 6. 单击“打开登录页验证”，用企业微信完成一次真实授权。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d77c5b5c53a966fa3ffd008765ebe13d.png) 7. 在企业微信客户端授权操作，并根据其配置指引，实现企业微信 OAuth 链路通道。企业 OIDC ### 前提条件在客户 IdP（Okta / Azure AD / Entra ID / Keycloak / Auth0 / 内部 IdP）创建一个 OIDC 应用，获取： * Issuer（签发方地址，例如`https://.example.com`） * Client ID 与 Client Secret * 授权地址、Token 地址、UserInfo 地址（部分 IdP 通过 Issuer 自动发现） * 需要的 Scope（至少包含`openid`、`profile`、`email`） ### 操作步骤 1. 在 [AgentKit 控制台](https://console.volcengine.com/identity)，按通用操作步骤说明选“企业 OIDC”，填写名称，然后单击“下一步”。 2. 把前提条件中获取的企业 OIDC 应用的 Issuer URL、客户端 ID（Client ID）、客户端密钥（Client Secret）粘贴到对应输入框，然后单击“创建”。 3. 复制系统提供的回调地址，将其粘贴到企业 OIDC 应用中 IdP 应用配置 → Redirect URIs 对应位置中并保存。 4. 回到 [AgentKit 控制台](https://console.volcengine.com/identity)，勾选“我已回填并保存”，然后单击“创建”。 5. 单击“打开登录页验证”，用 IdP 真实账号完成一次登录。 SAML 2.0 ### 前提条件 * 与 IdP 管理员约定好 SAML 元数据交换方式：优先用 Metadata URL，其次手动上传 IdP 元数据 / 签名证书。 * 从 IdP 侧导出 SAML 元数据 XML（包含实体 ID、端点、证书等）。 ### 操作步骤 1. 在 [AgentKit 控制台](https://console.volcengine.com/identity)，按通用操作步骤说明选“SAML 2.0”，填写名称，然后单击“下一步”。 2. 把前提条件中获取的 SML 元数据 XML 粘贴到对应输入框，然后单击“创建”。 3. 复制系统提供的回调地址，将其粘贴到 SAML 2.0 中 IdP 的 SP 配置 → Assertion Consumer Service URL 对应位置中并保存。 4. 回到 [AgentKit 控制台](https://console.volcengine.com/identity)，勾选“我已回填并保存”，然后单击“创建”。 5. 单击“打开登录页验证”，用 IdP 真实账号完成一次登录。 6. 在 AgentKit 控制台找到目标 SAML 2.0 身份源，编辑身份源信息，在“用户属性映射”中配置如下映射关系。邮箱 ←email，姓名 ← displayName，部门 ← department ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_0d63da6ddf9996db65edd225184c8760.png) 密码用户 ### 前提条件与客户 IdP 管理员约定好 SAML 元数据交换方式：优先用 Metadata URL，其次手动上传 IdP 元数据 / 签名证书。 ### 操作步骤 1. 在 [AgentKit 控制台](https://console.volcengine.com/identity)，按通用操作步骤说明选“密码用户”，填写名称，然后单击“下一步”。 2. 创建账号，配置相关参数。 * **首批账号**：填写登录账号，格式为`用户名,+86手机号`，每行一个账号，创建后自动生成临时密码并发送短信通知。添加完首批账号后，后续在“用户”模块中创建或 CSV 批量导入更多账号。详细操作，请参见 [创建用户](https://docs.volcengine.com/docs/agentkit/create-user)。 * **自动注册**：开启后用户可在登录页自行注册。 3. 单击“完成”，创建完成密码用户登录源配置。创建成功后，在目标用户池的，客户端页签，显示该密码用户。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_c41e5f550b3c182e6647b2e39e38df0b.png) 4. 用户在应用登录页选择“测试账号”，使用该用户名密码登录。

注意

密码用户没有外部身份源，账号入职 / 离职 / 改密都需要管理员手动处理。

请勿将生产环境相关用户长期放在密码用户里，该登录源方式仅用于 POC、临时协作账号等。

## 身份源管理查看与启停 * "用户管理 \> 登录来源"列表展示所有来源，包括名称、类型、状态（可用 / 待验证 / 异常）、成员数、被哪些 Agent 使用、最近登录时间。 * 每条来源可独立启用 / 停用。停用后登录页不再出现该入口，但已签发的令牌在过期前仍有效。编辑身份源在目标身份池的“身份源”页签，单击对应身份源右侧“操作”列下的“编辑”可更新该身份源配置。详细的参数说明如下所示。

说明

部分参数属于仅在部分提供商类型的编辑页面显示，实际可配置参数，以控制台显示为准。

|**参数** |**说明** | |---|---| |**基础信息** || |提供商名称 |身份源的名称，会在用户登录页内展示，用于用户登录时选择。 | |**出口配置** || |出口方式 |选择该身份源调用上游 IdP 时使用的网络出口。企业微信等要求校验服务端来源 IP 的场景必须绑定固定出口 IP，并把该出口 IP 段加入 IdP 后台的可信 IP 白名单，否则回调被拒、状态报异常。

* **平台默认出口** **（不稳定）** ：使用平台统一出口 IP，不保证稳定性，可能被外部服务风控拦截。

* **自定义出口 IP（推荐）** ：为当前资源绑定固定出口 IP，确保 IdP 白名单验证稳定通过。 | |启用状态 |控制该身份源是否可用。多条登录来源互相独立启停。

* 启用后用户可在登录页看到并选择该入口。

* 停用后登录页不再出现该入口，但已签发的令牌在过期前仍有效。 | |**企业微信登录配置** || |企业 ID |企业微信租户唯一标识（CorpId），在企业微信管理后台获取，用于标识接入的企业微信主体。 | |Agent ID |企业微信自建应用的应用标识（AgentId），在企业微信应用详情中获取，用于标识具体调用的自建应用。 | |Agent Secret |企业微信自建应用的应用密钥（Secret），与 CorpId、AgentId 配合换取访问凭证，属敏感信息，需妥善保管避免泄露。 | |**核心配置（钉钉&飞书）** || |客户端 ID |在 IdP 侧注册应用后获取的客户端唯一标识符：飞书对应 App ID，钉钉对应 AppKey / Client ID，用于标识当前用户池与 IdP 的信任关系。 | |客户端密钥 |与客户端 ID 配套的应用密钥：飞书对应 App Secret，钉钉对应 AppSecret / Client Secret，用于验证用户池作为 OAuth 客户端的合法性，属敏感信息，需妥善保管、避免泄露。 | |授权作用域 |希望从 IdP 获取的用户信息权限范围。按最小权限原则申请。

* 飞书默认为 `contact:user.base:readonly`、`contact:contact.base:readonly`。

* 钉钉需开通 "登录账号信息"、通讯录个人信息读（`Contact.User.Read`）、邮箱（fieldEmail）等权限并发布版本。 | |**SAML 核心配置** || |SAML 元数据 |从 SAML IdP 导出的元数据 XML（包含实体 ID、SSO 端点、签名证书等），支持直接粘贴 XML 内容或上传文件解析，用于与 IdP 建立元数据联邦信任。 | |启用签名验证 |开启后，Agent Identity 将使用 IdP 提供的签名证书对 SAML 请求进行签名，防止 SAML 请求被篡改。 | |启用加密 |开启后，Agent Identity 将使用 IdP 提供的加密证书对 SAML 响应（断言）进行加密。 | |**OIDC 核心配置** || |Issuer URL |外部 OIDC 身份提供商的唯一标识 URL（如 `https://.okta.com`），需与 IdP 配置完全一致，用于 OIDC 发现并验证身份令牌的签发来源合法性。 | |客户端密钥 |在 IdP 注册 OIDC 应用后获取的客户端密钥（Client Secret），与 Client ID 配合用于验证用户池作为 OIDC 客户端的合法性，属敏感信息，需妥善保管避免泄露。 | |授权范围 |希望从 IdP 获取的用户信息范围，至少需包含 `openid`，通常还需包含 `profile` 和 `email`，否则登录后无法获取用户基础信息（表现为用户信息为空或字段不对）。 | |**安全配置** || |启用 PKCE 增强安全性 |推荐开启。为 OAuth 授权码流程增加 PKCE（Proof Key for Code Exchange）校验，防止授权码被拦截置换，增强浏览器登录安全性。IdP 无明确要求时可保持默认。 | |**用户身份联动配置** | | |用户属性映射 |配置 IdP 返回的用户字段如何写入用户池。可将上游属性（如 `emails`、`displayName`、`departmentIds`）映射到标准用户属性（`user.email`、`user.name` 等）、自定义属性（`custom.`）或权威部门归属（`system.department_assignment`）。

注意

字段名必须与 IdP 返回的 claim 名完全一致，源路径不存在时该条映射自动跳过。

| |用户唯一标识属性 |指定用于识别和关联本地用户的唯一属性字段（如 sub、email、NameID、邮箱），需与 IdP 元数据 / 返回属性一致；配置错误会导致同一用户在用户池内重复创建或无法关联已有账号。 | |允许新用户注册 |是否允许新用户在注册页通过该身份源注册账号。

* 开启：允许注册

* 关闭：不允许注册 | |自动创建账号 |用户通过身份源登录时，平台内未发现该用户时是否自动创建账号。

* 开启：自动创建

* 关闭：需用户手动关联 / 注册 | |自动更新用户信息 |是否自动更新用户信息（平台用户属性从第三方 IdP 实时同步）。

* 开启：自动更新

* 关闭：仅首次登录时同步 | |自动链接配置 |已存在用户时，通过指定属性自动关联供应商身份，避免重复创建。 | |**用户信息携带** || |信息携带方式 |控制 IdP 上游用户声明在向下游业务 / Agent 颁发令牌时如何传播携带（对应 `ClaimsPropagationConfig`）。可选模式：

* 不携带（默认）

* 最小必要

* 全量声明透传

* 自定义声明集 | 删除身份源

注意

删除前需先在引用该登录来源的 Agent / 访问规则里解除绑定，否则删除会被拦截。

删除后用户不能再通过该来源登录，但用户目录里的账号记录保留。

1. 在登录来源列表的“操作”列单击“删除”。如该来源仍被 Agent / 访问规则引用，系统会提示先解除绑定。解除所有引用后再次删除，系统会按级联顺序清理身份提供商、登录应用、用户池相关对象。 2. 删除后，用户不能再通过该来源登录，但用户目录里的账号记录保留。