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 连接时，可通过所属项目和智能体身份池进行资源归属与隔离，降低跨业务或跨环境误用凭据的风险。
前提条件
- 获取有效的 API Key
- 已从目标服务提供方获取可用的 API Key，并确认该密钥具备 Agent 调用目标服务所需的权限。建议同时确认密钥的适用环境、有效期、调用额度、访问范围及是否存在 IP 白名单等限制，避免创建完成后因密钥权限不足或环境不匹配导致调用失败。
- 获取客户端 ID和客户端密钥（可选）
- 若需手动创建凭据，请先前往目标身份提供商的开发者平台创建 OAuth 应用或客户端。创建完成后，获取平台生成的客户端 ID 和客户端密钥，并填写到 AgentKit 的 身份提供商配置区域。
- 不同提供商的创建方式和凭据名称可能不同，请参考下表：
-
- 准备 KMS 密钥资源（可选）
- 若在创建凭据时选择使用“自定义主密钥”进行加密，请先在 KMS 中创建可用的密钥环和主密钥，并确认当前账号具备使用该主密钥加密和解密凭据的权限。详情请参见 密钥管理快速入门。
说明
若暂无需自主管理密钥，可选择系统默认密钥，由平台托管加密配置，以减少额外准备工作。
- 创建目标 Agent（可选）
- 若希望在创建凭据过程中立即完成绑定，请提前创建需要使用该凭据的 目标 Agent。绑定后，目标 Agent 才能在运行时引用该凭据完成出站调用。
说明
步骤一：选择凭据类型
- 登录AgentKit控制台。
- 在左侧导航树，选择“身份与权限 > 凭据管理”。
- 单击“新建凭据”按钮后，在“选类型”页面选择“OAuth 连接”。
-
- 单击“下一步”按钮。
步骤二：配置凭据参数
- 参考下表，配置基础参数。
- 参数说明提供商名称输入“提供商名称”，例如 downstream-service-oauth。建议使用能够区分服务、用途和环境的名称。创建方式选择凭据的创建方式，支持手动创建和动态客户端注册。
- 手动创建
- 适用于已在目标授权平台完成 OAuth 客户端创建，并已取得客户端 ID 和客户端密钥的场景。
- 动态客户端注册
- 适用于身份提供商支持动态注册的场景。系统根据发现文档或手工配置的端点向授权服务申请客户端凭据。
加密方式根据凭据管理要求选择指定 API Key 的安全存储方式。支持以下选项：- KMS 加密（平台存储）
- 凭据写入时，系统使用所选 KMS 主密钥进行加密，并仅以密文形式存储在平台中。适用于需要通过系统默认密钥或自定义主密钥保护凭据的场景。
- 凭据托管（托管存储）
- 凭据交由凭据托管服务统一存储和管理，适用于需要集中管理凭据及其生命周期的场景。
主密钥来源当加密方式选择为KMS 加密（平台存储）时，需要配置主密钥来源。- 系统默认密钥
- 由平台托管，开箱即用，无需额外配置，适合快速接入和常规使用场景。
- 自定义主密钥
- 使用自有 KMS 主密钥加密凭据。选择后，依次选择“KMS 密钥环”和“KMS 主密钥”。适用于有独立密钥管理、审计或合规要求的场景。
提供商类型选择 OAuth 连接使用的身份提供商。支持飞书、Coze、GitHub、用户池和自定义。说明仅当“创建方式”选择手动创建时显示，且为必填项。- 飞书：适用于访问飞书开放平台能力。
- Coze：适用于通过 Coze OAuth 获取授权。
- GitHub：适用于代表用户访问 GitHub 资源，截图中当前选择该类型。
- 用户池：适用于使用 AgentKit 用户池作为身份提供商。
- 自定义：适用于其他支持 OAuth2/OIDC 的身份提供商。相关客户端信息和端点应以目标提供商的官方文档为准。
- 配置身份提供商参数
- 不同创建方式对应的身份提供商参数不同。请根据前面选择的创建方式，单击手动创建或动态客户端注册（DCR）页签，参考对应参数说明完成配置。
- 当创建方式为手动创建时，参考下表配置相关参数。参数说明客户端 ID / 客户端密钥配置类型指定系统获取身份提供商 OAuth/OIDC 端点信息的方式。支持以下选项：说明仅提供商类型为自定义时显示，且为必填项。
- 自动发现（推荐）
- 通过身份提供商提供的发现文档，自动获取 Issuer、授权端点、令牌端点和注册端点等信息。适用于身份提供商支持标准发现机制的场景，可减少手动配置工作。
- 手动配置
- 手动填写 Issuer URL、授权端点、令牌端点、响应类型和注册端点。适用于身份提供商未提供发现文档，或需要使用自定义端点的场景。
自动发现 URL填写身份提供商提供的 OAuth/OIDC 发现文档地址，系统将读取该文档并自动获取相关端点信息。示例：https://example.com/.well-known/openid-configuration说明- 仅“配置类型”为自动发现时显示，且为必填项。
- 请确保该 URL 可正常访问，并返回有效的发现文档，具体地址请参见目标身份提供商的官方开发文档。
Issuer URL填写身份提供商的签发者地址，用于唯一标识签发身份令牌的授权服务。该值必须与身份提供商签发的 ID Token 中的 iss字段保持一致。示例：https://idp.example.com。说明- 仅当“配置类型”选择手动配置时显示，且为必填项。
- Issuer URL 获取方式：查看身份提供商官方文档，或复制发现文档中的 issuer 字段；也可向身份提供商管理员获取。
授权端点填写用户发起登录和授权时访问的完整 URL。AgentKit 会将用户引导至该地址完成授权。示例： https://idp.example.com/oauth2/authorize。说明- 仅当“配置类型”选择手动配置时显示，且为必填项。
- 授权端点获取方式：复制发现文档中的authorization_endpoint字段，或查阅身份提供商的 OAuth2 授权码流程文档。
令牌端点填写系统使用授权码等信息换取访问令牌的端点地址。示例：https://idp.example.com/oauth2/token说明- 仅当“配置类型”选择手动配置时显示，且为必填项。
- 令牌端点获取方式：复制发现文档中的token_endpoint字段，或查阅身份提供商的访问令牌接口文档。
响应类型指定授权端点返回的结果类型，默认值为 code，表示使用授权码流程。除非身份提供商明确要求其他类型，否则建议保持 code。说明仅当“配置类型”选择手动配置时显示。当创建方式为动态客户端注册（DCR）时，参考下表配置相关参数。参数说明配置类型指定系统获取身份提供商 OAuth/OIDC 端点信息的方式。支持以下选项：- 自动发现（推荐）
- 通过身份提供商提供的发现文档，自动获取 Issuer、授权端点、令牌端点和注册端点等信息。适用于身份提供商支持标准发现机制的场景，可减少手动配置工作。
- 手动配置
- 手动填写 Issuer URL、授权端点、令牌端点、响应类型和注册端点。适用于身份提供商未提供发现文档，或需要使用自定义端点的场景。
自动发现 URL填写身份提供商提供的 OAuth/OIDC 发现文档地址，系统将读取该文档并自动获取相关端点信息。示例：https://example.com/.well-known/openid-configuration说明- 仅“配置类型”为自动发现时显示，且为必填项。
- 请确保该 URL 可正常访问，并返回有效的发现文档，具体地址请参见目标身份提供商的官方开发文档。
Issuer URL填写身份提供商的签发者地址，用于唯一标识签发身份令牌的授权服务。该值必须与身份提供商签发的 ID Token 中的 iss字段保持一致。示例：https://idp.example.com。说明- 仅当“配置类型”选择手动配置时显示，且为必填项。
- Issuer URL 获取方式：查看身份提供商官方文档，或复制发现文档中的 issuer 字段；也可向身份提供商管理员获取。
授权端点填写用户发起登录和授权时访问的完整 URL。AgentKit 会将用户引导至该地址完成授权。示例： https://idp.example.com/oauth2/authorize。说明- 仅当“配置类型”选择手动配置时显示，且为必填项。
- 授权端点获取方式：复制发现文档中的authorization_endpoint字段，或查阅身份提供商的 OAuth2 授权码流程文档。
令牌端点填写系统使用授权码等信息换取访问令牌的端点地址。示例：https://idp.example.com/oauth2/token说明- 仅当“配置类型”选择手动配置时显示，且为必填项。
- 令牌端点获取方式：复制发现文档中的token_endpoint字段，或查阅身份提供商的访问令牌接口文档。
响应类型指定授权端点返回的结果类型，默认值为 code，表示使用授权码流程。除非身份提供商明确要求其他类型，否则建议保持 code。说明仅当“配置类型”选择手动配置时显示。注册端点填写动态客户端注册（DCR）接口的完整 URL。AgentKit 将通过该端点自动申请客户端 ID 和客户端密钥。示例：https://idp.example.com/connect/register。说明仅当“配置类型”选择手动配置时显示，且为必填项。客户端 ID / 客户端密钥说明仅当“配置类型”选择手动配置时显示，且为必填项。
- 参考下表，配置 OAuth 连接的高级参数。
说明
具体取值应以目标身份提供商的 OAuth/OIDC 开发文档和实际授权要求为准。
- 参数说明允许回调 URIs必填。配置身份提供商允许返回授权结果的回调地址，可填写多个地址，输入一个地址后按回车确认。建议分别配置开发、测试和生产环境的回调地址。此处填写的地址应同时登记在身份提供商的 OAuth 应用配置中，并确保协议、域名、端口、路径及末尾斜杠完全一致。说明仅创建方式为动态客户端注册（DCR）时显示，且需要配置。回调 URL必填。配置本次 OAuth 登录流程实际使用的回调地址。该地址必须包含在“允许回调 URIs”列表中，并与身份提供商侧登记的回调地址保持一致，否则可能出现回调地址不匹配或授权失败。OAuth2 流程选择 OAuth2 授权流程，用于决定了授权如何发生。
- 用户委托（USER_FEDERATION）（默认）：需要真实用户介入授权。首次调用时，用户会被重定向到下游服务的授权页面进行登录和同意。授权成功后，Agent Identity 会安全地托管获取到的 Refresh Token，用于后续代表用户静默刷新 Access Token，实现“一次授权，长期访问”。
- 机器对机器 (M2M)：由 Agent 或服务使用机器身份获取令牌，无需最终用户参与。智能体直接使用 Client ID/Secret 向下游服务获取 Access Token，适用于服务间的后台调用。
PKCE用于增强授权码流程的安全性，降低授权码被截获后遭到滥用的风险。默认开启，且不支持关闭。强制重新授权默认关闭。当提供商支持相应参数时，可以开启。开启后，系统在发起授权时要求用户重新完成身份提供商授权流程，适用于权限范围发生变化、需要重新确认用户授权，或排查历史授权状态异常的场景。凭据最大有效期（秒）设置 OAuth 凭据允许使用的最大时长，默认值为 3600 秒。请根据业务安全要求和身份提供商的令牌有效期进行设置，避免配置时间超过身份提供商允许的有效期。自定义参数（可选）用于补充身份提供商要求的 OAuth 扩展参数。单击“添加参数”按钮，按键值对填写参数名称和参数值。参数名称及取值请参见目标身份提供商的官方文档，避免添加来源不明或与标准参数冲突的内容。智能体身份池选择 OAuth 连接所属的智能体身份池，用于管理智能体身份并隔离不同业务或环境中的凭据。AgentKit 默认提供 default身份池；若无独立隔离要求，可直接使用默认值。客户端名称 / 主页 URL / Logo URL（可选）用于设置 OAuth 客户端在身份提供商授权页面中的展示信息。说明该配置项仅当创建方式选择动态客户端注册（DCR）时才会显示，且属于必填配置项。- 客户端名称：填写便于用户识别的应用或 Agent 名称。
- 客户端主页 URL：填写应用或业务的主页地址。
- 客户端 Logo URL：填写可公开访问的 Logo 图片地址。
权限范围用于限定访问令牌可以访问的资源和能力。请遵循最小权限原则，仅申请业务实际需要的权限。不同创建方式的配置要求如下：- 动态客户端注册（DCR）：当选择的创建方式为“动态客户端注册（DCR）”，根据业务需求填写 OAuth 授权需要申请的 Scope。
Scope 名称、组合方式及分隔格式由目标身份提供商定义，请参见其官方开发文档。配置完成后，相关权限范围将随客户端注册或用户授权请求提交给身份提供商。- 手动创建：当选择的创建方式为“手动创建”时，单击权限范围下拉列表选择“openid”。
当前仅支持“openid” ，用于申请 OpenID Connect 身份认证能力。请确保目标身份提供商及已创建的 OAuth 客户端已启用该权限范围。
- 参考下表，配置出口参数和所属。
- 参数说明出口配置出口 IP指定 AgentKit 向身份提供商或下游服务发起出站请求时使用的网络出口。支持以下选项：说明若无固定出口或 IP 白名单要求，建议使用 平台默认出口；若目标服务仅允许指定来源 IP 访问，请选择 自定义出口，并提前完成网络连通性和白名单配置。
- 平台默认出口（推荐）
- 使用 AgentKit 平台提供的默认出口，无需额外配置。适用于目标服务未限制请求来源 IP 的场景。
- 自定义出口
- 使用业务自行配置的网络出口，适用于目标服务启用了 IP 白名单、固定出口或网络隔离要求的场景。选择后，请填写自定义出口 IP。
说明若目标服务设置了 IP 白名单，请确认所选出口对应的 IP 地址已加入允许名单，否则可能导致 OAuth 授权、令牌获取或下游 API 调用失败。资源管理所属项目该凭据所属项目，系统默认选择default（默认项目）；也可按需切换项目或新建项目。- 一个资源仅可归属于一个项目，如需更改凭据所属项目，可单击所属项目下拉列表并选择目标项目。
-
- 选定项目后，创建的凭据仅支持具有该项目权限的用户访问和使用。
- 如当前项目不符合业务需求，可单击“新建项目”按钮进行创建。创建完成后，返回当前页面并选择新建的项目。
- 确认参数配置无误后，单击“创建并继续”按钮，进入绑定到 Agent 页面。
步骤三：绑定到 Agent（可选）
将凭据绑定到 Agent 后，目标 Agent 才能在运行时引用该凭据完成出站调用。为遵循最小授权原则，建议仅绑定确有调用需求的 Agent，避免扩大凭据的使用范围。
说明
- 在 Agent 列表中选择需要使用该凭据的目标 Agent。
-
- 确认所选 Agent 无误后，单击“下一步”按钮。
如暂不绑定，可不选择任何 Agent，直接单击“下一步”按钮进入后续流程。
步骤四：确认创建结果
页面显示凭据创建成功，表示系统已完成凭据保存。结束创建流程前，请确认页面展示的凭据名称与预期一致，避免因名称填写错误而影响后续查找和使用。
- 确认凭据名称与本次创建的凭据一致。
- 如需核对凭据类型、所属项目、绑定资源或其他配置信息，单击“查看凭据详情”按钮，进入详情页进行检查。
- 确认无误后，单击“完成”按钮，结束创建流程。
最近更新时间：2026.10.12 17:24:50
这个页面对您有帮助吗？
有用
有用
无用
无用