AgentKit
AgentKit
文档指南
请输入
- 文档首页
AgentKitAgentKit用户指南身份与权限用户指南凭据管理创建 OAuth 连接凭据
复制全文
下载 pdf创建 OAuth 连接凭据
文档反馈
问问助手OAuth 连接凭据用于代表用户或 Agent 向第三方身份提供商发起授权，并获取具有有效期的访问令牌。创建后，Agent 代码可通过凭据名称引用配置，由平台负责凭据存储、授权交互和出站注入，无需在代码中硬编码客户端密钥或访问令牌。
当需要通过 OAuth2 授权访问外部服务的场景，例如代表用户或 Agent 获取短期访问令牌时，需要创建 OAuth 连接凭据。
推荐场景
- 代表最终用户访问第三方服务
- 当 Agent 需要代表用户访问飞书、GitHub、Coze 或其他支持 OAuth2 的服务时，可使用用户委托流程获取访问令牌，并在用户授权范围内调用目标 API。
- 使用机器身份调用下游服务
- 当 Agent 需要以自身或服务身份调用第三方系统，且目标服务支持机器对机器授权时，可使用 M2M 流程获取短期令牌，适用于无需用户交互的后台调用。
- 统一管理 OAuth 客户端配置
- 当业务需要集中维护客户端 ID、客户端密钥、权限范围、回调地址、令牌有效期和其他 OAuth 参数时，可通过 OAuth 连接凭据统一管理，避免配置分散在不同 Agent 或运行环境中。
- 按项目和身份池管理凭据
- 当不同业务、团队或环境需要独立管理 OAuth 连接时，可通过所属项目和智能体身份池进行资源归属与隔离，降低跨业务或跨环境误用凭据的风险。
前提条件
- 准备 OAuth 客户端信息（可选）
- 若需手动创建凭据，请先前往目标身份提供商的开发者平台创建 OAuth 应用或客户端。创建完成后，获取平台生成的客户端 ID 和客户端密钥，并填写到 AgentKit 的 身份提供商配置区域。
注意
若采用动态客户端注册（DCR）模式接入，请提前确认该身份提供商支持 DCR 能力，并提前准备好对应的发现地址、注册接口地址以及所需的身份认证信息，用于发起客户端自动注册。
- 不同提供商的创建方式和凭据名称可能不同，请参考下表：
-
- 准备 KMS 密钥资源（可选）
- 若在创建凭据时选择使用“自定义主密钥”进行加密，请先在 KMS 中创建可用的密钥环和主密钥，并确认当前账号具备使用该主密钥加密和解密凭据的权限。详情请参见 密钥管理快速入门。
说明
若暂无需自主管理密钥，可选择系统默认密钥，由平台托管加密配置，以减少额外准备工作。
- 创建目标 Agent（可选）
- 若希望在创建凭据过程中立即完成绑定，请提前创建需要使用该凭据的 目标 Agent。绑定后，目标 Agent 才能在运行时引用该凭据完成出站调用。
说明
操作步骤
步骤一：选择凭据类型
- 登录 AgentKit 控制台。
- 在左侧导航树，选择“身份与权限 > 凭据管理”。
- 单击“新建凭据”按钮后，在“选类型”页面选择“OAuth 连接”。
-
- 单击“下一步”按钮。
步骤二：配置凭据参数
- 参考下表，配置基础参数。
- 参数说明提供商名称输入提供商名称，例如downstream-service-oauth。建议使用能够区分服务、用途和环境的名称。创建方式选择凭据的创建方式，支持手动创建和动态客户端注册。
- 手动创建
- 适用于已在目标授权平台完成 OAuth 客户端创建，并已取得客户端 ID 和客户端密钥的场景。
- 动态客户端注册
- 适用于身份提供商支持动态注册的场景。系统根据发现文档或手工配置的端点向授权服务申请客户端凭据。
加密方式根据凭据管理要求选择 OAuth 客户端敏感信息的安全存储方式。支持以下选项：- KMS 加密（平台存储）
- 凭据写入时，系统使用所选 KMS 主密钥进行加密，并仅以密文形式存储在平台中。适用于需要通过系统默认密钥或自定义主密钥保护凭据的场景。
- 凭据托管（托管存储）
- 凭据交由凭据托管服务统一存储和管理，适用于需要集中管理凭据及其生命周期的场景。
主密钥来源当加密方式选择为KMS 加密（平台存储）时，需要配置主密钥来源。- 系统默认密钥
- 由平台托管，开箱即用，无需额外配置，适合快速接入和常规使用场景。
- 自定义主密钥
- 使用自有 KMS 主密钥加密凭据。选择后，依次选择“KMS 密钥环”和“KMS 主密钥”。适用于有独立密钥管理、审计或合规要求的场景。
提供商类型选择 OAuth 连接使用的身份提供商。支持飞书、Coze、GitHub、用户池和自定义。说明仅当“创建方式”选择手动创建时显示，且为必填项。- 飞书：适用于访问飞书开放平台能力。
- Coze：适用于通过 Coze OAuth 获取授权。
- GitHub：适用于代表用户访问 GitHub 资源，截图中当前选择该类型。
- 用户池：适用于使用 AgentKit 用户池作为身份提供商。
- 自定义：适用于其他支持 OAuth2/OIDC 的身份提供商。相关客户端信息和端点应以目标提供商的官方文档为准。
- 配置身份提供商参数
- 不同创建方式对应的身份提供商参数不同。请根据前面选择的创建方式，单击手动创建或动态客户端注册（DCR）页签，参考对应参数说明完成配置。
- 当创建方式选择动态客户端注册（DCR）时，系统将根据身份提供商公开的 OAuth 2.0 或 OpenID Connect（OIDC）配置信息，自动注册 OAuth 客户端并获取客户端 ID、客户端密钥等信息。
- 选择配置类型：指定系统获取身份提供商 OAuth/OIDC 端点信息的方式，支持自动发现和手动配置。
- 自动发现
- 填写身份提供商提供的发现 URL。系统将从发现文档中获取注册端点、授权端点、令牌端点及其他相关配置。适用于身份提供商支持标准 OAuth/OIDC 发现机制的场景。
- 手动配置
- 手动填写 Issuer URL、注册端点、授权端点、令牌端点等信息。适用于身份提供商未提供标准发现 URL，或需要使用指定端点的场景。
- 根据选择的配置类型配置对应参数。
- 在自动发现 URL填写身份提供商提供的 OAuth/OIDC 发现文档地址，系统将读取该文档并自动获取相关端点信息。示例：https://example.com/.well-known/openid-configuration
说明请确保该 URL 可正常访问，并返回有效的发现文档，具体地址请参见目标身份提供商的官方开发文档。手动填写身份提供商相关参数，参数取值请以 IDP 的 OIDC 发现文档为准。
当创建方式为手动创建时，请根据选择的提供商类型，配置相关参数。选择飞书、Coze 或 GitHub 作为身份提供商时，需要填写对应 OAuth 应用的客户端 ID 和客户端密钥。系统将使用这组凭据识别并验证应用身份，完成与第三方身份提供商之间的 OAuth 授权和令牌获取。- 输入客户端 ID
- 输入第三方身份提供商为当前 OAuth 应用分配的客户端 ID（Client ID），用于标识发起 OAuth 请求的应用。获取方法请参见 前提条件。
- 客户端密钥
- 输入与客户端 ID 配套生成的客户端密钥（Client Secret），用于在 OAuth 认证过程中验证应用身份。获取方法请参见 前提条件。
注意请确保客户端 ID 与客户端密钥来自同一个 OAuth 应用，否则可能导致身份验证失败。客户端密钥属于敏感信息，请勿在代码仓库、日志、截图或聊天消息中以明文形式保存或传播。选择自定义身份提供商时，需要配置目标用户池及其客户端。用户池用于提供和管理调用方的身份信息，用户池客户端用于标识接入当前 OAuth 流程的具体应用。
- 参考下表，配置 OAuth 连接的高级参数。
说明
具体取值应以目标身份提供商的 OAuth/OIDC 开发文档和实际授权要求为准。
- 参数说明允许回调 URIs必填。配置身份提供商允许返回授权结果的回调地址，可填写多个地址，输入一个地址后按回车确认。建议分别配置开发、测试和生产环境的回调地址。此处填写的地址应同时登记在身份提供商的 OAuth 应用配置中，并确保协议、域名、端口、路径及末尾斜杠完全一致。填写动态注册客户端时，允许使用的 HTTPS 回调地址。输入单个地址后按回车确认保存，支持录入多条互不重复的地址；后续填写的回调 URL，必须是这里录入地址中的其中一条。系统执行动态客户端注册时，会把这里配置的全部允许回调 URI 一并提交给身份提供商，作为客户端注册信息。说明仅创建方式为动态客户端注册（DCR）时显示，且需要配置。回调 URL用于接收身份提供商返回的 OAuth 授权结果。用户完成授权后，身份提供商会将授权结果返回至该地址。请在回调 URL输入框中填写平台生成的回调地址，或应用实际部署的 OAuth 回调接口地址，请勿随意填写。
- 需要填写回调 URL 的场景
- 手动创建
- 当创建方式为“手动创建”时，且选择“飞书”、“Coze”、“GitHub”或“自定义”提供商，并采用用户委托流程时，该字段显示且为必填项。
- 填写的地址必须与身份提供商侧为当前 OAuth 客户端登记的回调地址完全一致。
- 动态客户端注册（DCR）
- DCR 当前仅支持用户委托流程，因此该字段显示且为必填项。填写的回调地址必须已添加至上方的允许回调 URIs 列表。
- 无需填写回调 URL 的场景
- 机器对机器（M2M）流程：该流程无需用户参与授权，不涉及授权回调，因此页面不展示回调 URL，也不展示 PKCE 相关配置。
- 用户池提供商：无需在当前页面手动填写回调 URL。选择目标用户池和客户端即可，具体授权流程由所选客户端类型决定。若所选客户端采用用户委托流程，平台会统一配置回调地址，并自动将其追加到该客户端的允许回调地址列表中。
OAuth2 流程选择 OAuth2 授权流程，用于确定访问令牌的申请方式和身份主体。- 用户委托（USER_FEDERATION）（默认）
- 用于管理由具体用户授权产生的 OAuth 凭据，需用户参与授权。用户完成授权后，平台按提供商返回的令牌访问目标服务。如果身份提供商签发了可用的 Refresh Token，且用户授权仍然有效，平台可以使用该令牌刷新 Access Token，减少用户重复授权。若用户撤销授权、Refresh Token 过期或失效，或者令牌刷新失败，则需要用户重新完成授权。
- 机器对机器 (M2M)
- 无需最终用户参与，由 Agent 或服务使用机器身份获取令牌。智能体直接使用 Client ID/Secret 向下游服务获取 Access Token，适用于服务间的后台调用。
PKCE用于增强授权码流程的安全性，降低授权码被截获后遭到滥用的风险。默认开启，且不支持关闭。强制重新授权默认关闭。当提供商支持相应参数时，可以开启。开启后，系统在发起授权时要求用户重新完成身份提供商授权流程，适用于权限范围发生变化、需要重新确认用户授权，或排查历史授权状态异常的场景。凭据最大有效期（秒）设置 AgentKit 允许 OAuth 凭据持续使用的最长时间，默认值为 3600 秒。实际有效期由该配置与身份提供商签发令牌的有效期共同决定。请结合业务连续性、安全要求及身份提供商的令牌策略合理设置：- 时长设置过短，容易触发频繁的令牌刷新，甚至需要用户重新授权，影响业务使用。
- 时长设置过长，会增加令牌一旦泄露带来的安全风险窗口。
说明若身份提供商签发的令牌有效期更短，则令牌以身份提供商规定的时间为准失效。本配置仅作为使用时长上限控制，无法延长已经签发的 Access Token、Refresh Token 的原始有效期。自定义参数（可选）用于补充身份提供商要求的 OAuth 扩展参数。单击“添加参数”按钮，按键值对填写参数名称和参数值。参数名称及取值请参见目标身份提供商的官方文档，避免添加来源不明或与标准参数冲突的内容。智能体身份池选择 OAuth 连接所属的智能体身份池，用于管理智能体身份并隔离不同业务或环境中的凭据。AgentKit 默认提供default身份池；若无独立隔离要求，可直接使用默认值。客户端名称（可选）若添加，请输入便于用户识别的客户端名称，最多支持 128 个字符。仅在创建方式选择“动态客户端注册（DCR）”时显示。说明该名称将作为客户端注册信息提交给目标身份提供商，提供商可能在授权页面或客户端管理页面中展示，具体展示方式由提供商决定。主页 URL（可选）若填写，请输入客户端应用或业务的主页地址，支持以http://或https://开头的 URL。仅在创建方式选择“动态客户端注册（DCR）”时显示。说明该地址将作为客户端注册信息提交给目标身份提供商，具体展示及跳转方式由提供商决定。Logo URL（可选）若填写，请输入客户端 Logo 图片的 HTTPS 地址，支持png、jpg、jpeg、webp、gif格式。并确保目标身份提供商能够正常访问该地址并获取图片，否则可能导致 Logo 无法展示。仅在创建方式选择“动态客户端注册（DCR）”时显示。说明该地址将作为客户端注册信息提交给目标身份提供商，具体展示方式由提供商决定。权限范围权限范围（Scope）用于限定访问令牌可以访问的资源和能力。请遵循最小权限原则，仅申请业务实际需要的权限。注意- Scope 的名称、含义、组合方式及分隔格式由目标身份提供商定义。配置前，请先查阅目标身份提供商的官方开发文档，确认 OAuth 客户端支持并已启用对应权限。
- openid是一种用于启用 OpenID Connect（OIDC）身份认证的 Scope。配置后，系统可以在授权流程中获取用户身份相关信息，但这不代表已经获得目标业务 API 的访问权限。请确保目标身份提供商支持 OIDC，且对应 OAuth 客户端已启用openid，否则可能导致授权失败或无法获取身份令牌。
不同创建方式对应的配置要求存在差异，如下：- 动态客户端注册（DCR）
- 当选择的创建方式为“动态客户端注册（DCR）”，请在“权限范围”输入框中填写 OAuth 授权需要申请的 Scope，多个 Scope 之间使用空格分隔。
- 配置示例：请在“权限范围”输入框中输入openid profile email，其中，openid用于启用 OIDC 身份认证，profile和email用于申请相应的用户信息访问权限。
说明配置完成后，系统会在动态客户端注册或用户授权请求中，将所填 Scope 提交给身份提供商。- 手动创建
- 当选择的创建方式为“手动创建”时，默认已填写openid，您可以根据目标身份提供商及目标 API 的要求，对权限范围进行以下调整：
- 添加更多 Scope：在“权限范围”中输入目标身份提供商或目标 API 要求的 Scope，并按回车添加；支持添加多个 Scope。
- 保留 openid：目标身份提供商支持 OIDC，并且业务需要获取用户身份信息时，可保留 openid。
- 删除或替换 openid：仅需访问业务 API、不需要 OIDC 身份认证时，应根据目标身份提供商的要求删除 openid ，或替换为对应的业务 Scope。
- 追加业务 Scope：同时需要身份认证和业务 API 访问权限时，可保留 openid ，并追加相应的业务 Scope。
说明不同身份提供商采用的权限体系可能不同，请勿将 openid 作为所有 OAuth 提供商的统一配置。例如：
- 参考下表，配置出口参数和所属项目。
- 参数说明出口配置出口 IP用于说明 AgentKit 凭据托管服务访问身份提供商时使用的网络出口，支持以下选项：说明若无固定出口或 IP 白名单要求，建议使用 平台默认出口；若目标服务仅允许指定来源 IP 访问，请选择 自定义出口，并提前完成网络连通性和白名单配置。
- 平台默认出口（推荐）
- 使用 AgentKit 平台提供的默认出口，无需额外配置。适用于目标服务未限制请求来源 IP 的场景。
- 自定义出口
- 使用业务自行配置的网络出口，适用于目标服务启用了 IP 白名单、固定出口或网络隔离要求的场景。选择后，请填写自定义出口 IP。
配置自定义出口时，请先完成以下准备工作：- 配置实际出站网络出口，并确保出口 IP 固定且可用。
- 配置网络路由和安全策略，确保 AgentKit 能够通过该出口访问身份提供商的授权端点、令牌端点及动态客户端注册端点。
- 将实际出口 IP 加入身份提供商的 IP 白名单。
说明- 该配置不覆盖 Agent 调用下游业务 API 的请求。Agent 业务 API 请求使用的出口由实际发起请求的组件决定，例如智能体运行时、AgentKit 网关或业务服务。若下游业务 API 同样要求固定来源 IP，需要单独为相应执行环境配置固定出口，并将其出口 IP 加入下游服务的白名单。
- 若目标服务设置了 IP 白名单，请确认所选出口对应的 IP 地址已加入允许名单，否则可能导致 OAuth 授权、令牌获取或下游 API 调用失败。
资源管理所属项目该凭据所属项目，系统默认选择default（默认项目）；也可按需切换项目或新建项目。- 一个资源仅可归属于一个项目，如需更改凭据所属项目，可单击所属项目下拉列表并选择目标项目。
-
- 选定项目后，创建的凭据仅支持具有该项目权限的用户访问和使用。
- 如当前项目不符合业务需求，可单击“新建项目”按钮进行创建。创建完成后，返回当前页面并选择新建的项目。
- 确认参数配置无误后，单击“创建并继续”按钮，进入绑定到 Agent 页面。
步骤三：绑定到 Agent（可选）
将凭据绑定到 Agent 后，目标 Agent 才能在运行时引用该凭据完成出站调用。为遵循最小授权原则，建议仅绑定确有调用需求的 Agent，避免扩大凭据的使用范围。
说明
- 在 Agent 列表中选择需要使用该凭据的目标 Agent。
-
- 确认所选 Agent 无误后，单击“下一步”按钮。
如暂不绑定，可不选择任何 Agent，直接单击“下一步”按钮进入后续流程。
步骤四：确认创建结果
页面显示凭据创建成功，表示系统已完成凭据保存。结束创建流程前，请确认页面展示的凭据名称与预期一致，避免因名称填写错误而影响后续查找和使用。
- 确认凭据名称与本次创建的凭据一致。
- 如需核对凭据类型、所属项目、绑定资源或其他配置信息，单击“查看凭据详情”按钮，进入详情页进行检查。
- 确认无误后，单击“完成”按钮，结束创建流程。
最近更新时间：2026.10.23 16:53:59
这个页面对您有帮助吗？
有用
有用
无用
无用