Appearance
配置服务鉴权与用户授权
插件需要分别处理“AIOS 如何访问上游服务”和“最终使用者是否需要为自己的账号授权”。前者在创建或编辑插件时配置服务鉴权；后者在插件详情页配置用户授权。两套机制用途不同，不能互相替代。
服务鉴权方式
| 当前方式 | 适用场景 | 关键配置 |
|---|---|---|
| 不需要授权 | 公共接口，或由专用网络、网关完成鉴权 | 无 |
| Service token / API key | 所有调用共用一个固定 Token 或 API Key | 注入位置、Parameter name、Token/API Key |
| OAuth 2.0 & OIDC | 平台通过 Token Exchange 或 Client Credentials 获取服务令牌 | grant_type、endpoint_url、audience、scope、client_id |
| OAuth standard | 最终用户跳转到第三方页面，同意后由 AIOS 使用授权码换取令牌 | client_id、client_secret、client_url、scope、authorization_url、authorization_content_type |
Service token / API key
| 配置 | 是否必填 | 说明与示例 |
|---|---|---|
| 注入位置 | 是 | Header 或 Query。应严格按照上游服务要求选择。 |
| Parameter name | 是 | 上游接收凭据的参数名，例如 Authorization、X-API-Key 或 api_key。 |
| Token / API Key | 是 | 实际凭据，只填写在受保护的密钥字段中。编辑时如需更新鉴权配置，应重新输入。 |
如果上游要求 Authorization: Bearer <token>，先确认当前表单要求填写完整的 Bearer <token>，还是只填写令牌本身。不要把同一密钥重复写进普通 Header、工具输入参数、工具说明或运行示例。
OAuth 2.0 & OIDC
这类配置用于服务间换取访问令牌，不会打开最终用户的浏览器授权页。
| 配置 | 是否必填 | 说明 |
|---|---|---|
grant_type | 是 | 当前可选 TOKEN_EXCHANGE 和 CLIENT_CREDENTIAL。 |
endpoint_url | 是 | OAuth/OIDC 提供方接收换令牌请求的 HTTPS 地址。它是令牌端点，不是普通业务 API 地址。 |
audience | 否 | 令牌的目标服务或资源标识；仅在提供方要求时填写。 |
scope | 否 | 申请的权限范围，多个值的分隔方式以提供方文档为准；OIDC 身份场景通常包含 openid。 |
client_id | 是 | 在 OAuth/OIDC 提供方创建应用后获得的客户端标识。当前 AIOS 对两种 Grant Type 都要求填写。 |
Grant Type 选择
| Grant Type | 使用条件 | 请求主体 |
|---|---|---|
| Token Exchange | 已持有用户令牌或主体令牌，需要换成可访问目标服务的新令牌 | 被交换的主体令牌、client_id，以及可选的 audience、scope |
| Client Credentials | 插件代表自身访问服务，不需要最终用户参与 | client_id，以及提供方要求的客户端认证信息 |
旧文档的部分 Token Exchange 示例写成“不需要
client_id”。当前版本表单和服务端校验均要求client_id，应以当前实现为准。
当前 OAuth 2.0 & OIDC 表单没有单独的
client_secret输入项。若第三方的 Client Credentials 流程强制要求 Client Secret、私钥或其他客户端认证方式，先确认现有接入能力是否支持，不要把 Secret 填进scope、audience或工具参数中。
OAuth standard
OAuth standard 对应授权码流程：用户在第三方授权页面同意授权，第三方把授权码返回 AIOS，AIOS 再使用授权码换取 access_token。
先区分三个地址
| 地址 | 用途 | 是否属于鉴权参数 |
|---|---|---|
| 插件 URL / Server URL | AIOS 实际调用的 HTTP API 或 MCP Server 地址 | 否，在插件基础信息中配置 |
client_url | 用户浏览器打开的第三方授权端点（Authorization Endpoint） | 是 |
authorization_url | AIOS 使用授权码换取令牌的端点（Token Endpoint） | 是 |
这里沿用旧文档与现有字段名：client_url 表示“用户授权地址”，authorization_url 表示“令牌地址”。两个名称并不直观，配置时要按用途判断，不能只看字段英文名称。当前服务端只校验它们是否为有效 HTTP(S) URL，无法自动识别两个地址是否填反。
参数说明
| 配置 | 是否必填 | 说明与填写要求 |
|---|---|---|
client_id | 是 | OAuth 应用在授权服务器中的唯一标识。示例：your-client-id。 |
client_secret | 是 | 与 client_id 配套的客户端密钥，用于证明应用身份。只在受保护字段中填写，文档和截图必须脱敏；编辑鉴权配置时需要重新输入。 |
client_url | 是 | 第三方的用户授权端点。AIOS 会在此基础上携带 response_type=code、client_id、scope、state 和 redirect_uri 等参数，引导用户登录并同意授权。示例：https://auth.example.com/oauth/authorize。 |
scope | 否 | 希望获得的权限范围。仅申请插件实际需要的最小权限，格式和分隔符以提供方文档为准。 |
authorization_url | 是 | 第三方的 Token Endpoint。授权成功后，AIOS 向该地址提交授权码等参数以获取 access_token。示例：https://auth.example.com/oauth/token。 |
authorization_content_type | 是 | 向 Token Endpoint 发送数据时使用的内容类型。旧文档支持 application/json（默认）和 application/x-www-form-urlencoded；应按第三方文档选择。 |
图 1：
client_url负责用户授权，authorization_url负责授权码换令牌；state用于关联并校验本次授权请求。
配置步骤
- 在第三方开发者平台创建 OAuth 应用，取得
client_id和client_secret。 - 从第三方官方文档确认 Authorization Endpoint、Token Endpoint、Scope 格式和 Token 请求内容类型。
- 在 AIOS 中将 Authorization Endpoint 填入
client_url，将 Token Endpoint 填入authorization_url。 - 从当前 AIOS 页面或当前部署环境取得回调地址，并登记到第三方 OAuth 应用。不要沿用旧文档中的历史域名或
/api/plugin_oauth/{plugin_id}/authorization_code示例。 - 保存后使用测试账号完成一次完整授权，检查用户拒绝、
state不匹配、授权码过期、令牌过期和权限不足等失败场景。
用户授权
插件详情页的“用户授权”用于收集每个最终调用者自己的凭据，适合邮箱、个人网盘和按用户隔离的 SaaS 账号。
当前可以选择：
- 无需用户授权。
- 用户填写凭证，并配置授权标题、Schema 版本、说明、帮助 URL 和验证工具。
授权字段可以使用文本、密码、Token、URL、邮箱和下拉选择等组件，并设置必填、占位提示、帮助信息、长度、正则校验和下拉选项。字段 Key 发布后要保持稳定。
图 2：插件详情顶部的“用户授权”区域用于维护最终用户授权 Schema；它不是服务鉴权入口。
如何选择
| 问题 | 选择 |
|---|---|
| 所有调用者共用同一个固定服务凭据 | Service token / API key |
| 平台使用自身身份换取服务令牌 | OAuth 2.0 & OIDC |
| 用户必须跳转到第三方页面同意授权 | OAuth standard |
| 每个用户手工填写自己的 Token、账号字段或其他凭据 | 用户授权 Schema |
| 上游接口完全公开，或鉴权已由专用网络完成 | 不需要授权 |
常见配置错误
| 现象 | 优先检查 |
|---|---|
| 点击授权后打开 404 或普通业务页面 | client_url 是否误填为插件 API 地址或 Token Endpoint |
| 用户同意后换取令牌失败 | authorization_url、client_secret、回调地址和 authorization_content_type 是否匹配提供方要求 |
| 提示 redirect URI 不一致 | 第三方 OAuth 应用中登记的地址是否与当前 AIOS 环境提供的回调地址完全一致 |
| 返回 invalid_scope | Scope 名称、分隔符、应用授权范围是否正确 |
| 返回 invalid_client | client_id、client_secret 是否来自同一个 OAuth 应用，Secret 是否已过期或轮换 |
| 固定 API Key 未生效 | 注入位置和 Parameter name 是否与上游服务要求一致 |
安全与发布检查
- 测试和生产使用不同凭据，并按最小权限和有效期管理。
- 日志、运行示例和截图隐藏 Token、Cookie、Authorization、Client Secret 和用户数据。
- OAuth 回调使用 HTTPS，校验
state，并处理用户拒绝、撤销、授权码过期、令牌过期和刷新失败。 - 鉴权失败返回明确错误，不无限重试，也不降级为匿名调用。
- 复制插件到其他空间后重新配置凭据，不假定 Secret 会随资源复制。
- 发布前分别验证成功授权、取消授权、错误 Scope、错误 Secret 和令牌失效场景。
完成配置后进入工具试运行，用真实但可脱敏的测试账号验证。