Skybridge 认证体系指南如何为 MCP App 接入 OAuth 并安全验证用户身份【免费下载链接】skybridgeSkybridge is a full-stack TypeScript framework for MCP Apps and ChatGPT Apps. Type-safe. React-powered. Platform-agnostic.项目地址: https://gitcode.com/gh_mirrors/skybr/skybridgeSkybridge 是一个全栈 TypeScript 框架用于构建运行在 ChatGPT 和 Claude 等宿主中的 MCP Apps。它的认证体系基于 OAuth 2.0只需几行配置即可接入 Auth0、Clerk 等身份提供商并让每一个工具调用都携带经过验证的用户身份从而安全地实现个性化体验。为什么 MCP App 必须接入 OAuth默认情况下MCP 工具调用是匿名的——协议本身不会告诉你的服务器是谁在调用。如果你的 App 需要按用户展示收藏、订单或个性化内容就必须先确认调用者身份。好消息是宿主替你做了最难的活。当 ChatGPT 或 Claude 调用你的工具时它会负责发现你的授权服务器通过标准元数据文档RFC 9728引导用户登录并同意授权刷新过期的 token在每个请求上附加 Bearer token你的服务器只需要做好三件事发布发现元数据告诉宿主去哪里登录验证 token确认每个请求携带的 token 真实有效读取用户在处理器中拿到已认证用户的信息完整流程文档见 docs/build/auth.mdx。六选一如何快速接入 OAuth 提供商Skybridge 内置了六个品牌化提供商每个都只需在Skybridge配置里写一行oauth字段。下面以配置最简单的 Clerk 为例其余提供商的完整步骤见 docs/guides/auth-providers.mdximport { Skybridge, clerkProvider } from skybridge/server; export const app new Skybridge({ name: auth-coffee, version: 0.0.1, oauth: clerkProvider({ domain: process.env.CLERK_FRONTEND_API, // 你的 Frontend API 域名 }), handler, // 你的工具注册逻辑 });支持的提供商速查表提供商内置方法需要配置的关键项运行示例Auth0auth0Provider租户域名、API 标识符audience、服务器 URLexamples/auth-auth0/AuthplaneauthplaneProvider授权服务器地址、资源标识examples/auth-authplane/ClerkclerkProvider仅域名无需 audienceexamples/auth-clerk/DescopedescopeProviderMCP Server 的发现 URLexamples/auth-descope/StytchstytchProvider项目域名、Project IDexamples/auth-stytch/WorkOSworkosProviderAuthKit 域名、服务器 URL作为 audienceexamples/auth-workos/其他提供商怎么办只要它支持动态客户端注册DCR、签发 JWT access token并能把 audience 写进 token就可以用customProvider({ issuer, audience })三行接上。每个可运行的示例源码都在 examples/ 目录下Clerk 示例的完整服务端代码见 examples/auth-clerk/src/server.ts。两步安全验证requireBearerAuth 与 optionalBearerAuth接入提供商后Skybridge 自动挂载了验证中间件。手动接线时则有两个中间件可选挂载在/mcp路径上模式一全站强制登录requireBearerAuthrequireBearerAuth把整个服务器锁在登录后面没有 token、token 无效或过期的请求在任何工具运行之前就会被 401 拒绝token 缺少所需 scope 则返回 403。这是个人数据类工具订单、收藏、账户的默认选择。参考文档docs/api-reference/require-bearer-auth.mdx模式二混合公开与私有工具optionalBearerAuth如果一部分工具可以匿名使用比如浏览商品目录另一部分需要登录比如下单结算换用optionalBearerAuth即可请求没带token → 放行处理器里authInfo为空请求带了token → 正常验证无效同样 401然后为每个工具声明securitySchemes来控制可见性声明效果[{ type: oauth2 }]必须登录[{ type: noauth }]匿名可用[{ type: noauth }, { type: oauth2 }]匿名可用登录后功能更多参考文档docs/api-reference/optional-bearer-auth.mdx在提供商路径下oauth配置字段这些规则会进一步简化为工具级声明例如auth: { allowsAnonymous: true }或auth: { scopes: [checkout] }由 Skybridge 在处理器运行前强制执行无需手写守卫。如何在处理器中安全读取已登录用户token 验证通过后认证信息会出现在每个工具处理器的第二个参数里async ({ query }, extra) { const subject extra.http?.authInfo?.extra?.subject; // 用户标识 const scopes extra.http?.authInfo?.scopes; // 已授予的权限 return { structuredContent: { results: search(query, subject) } }; }两条安全准则务必遵守永远不要信任客户端传入的用户 ID——只认extra.http?.authInfo里的内容因为它是你亲手验证过的 token 解析结果。token 只证明他是谁——他能做什么scope 检查和数据归属按用户过滤查询仍要在处理器里处理。需要读取自定义 claims如email、tenant时可以给提供商传入类型参数例如workosProvider{ tenant: string }({ domain, audience })类型会一路安全地流进处理器。验证器契约详见 docs/api-reference/verifier.mdx发现元数据的路由器mcpAuthMetadataRouter见 docs/api-reference/mcp-auth-metadata-router.mdx。如何本地测试 OAuth 流程用隧道一步打通OAuth 流程涉及宿主的真实登录行为localhost无法完成跳转。Skybridge 的隧道功能可以一键把本地服务暴露为公网 URLskybridge dev --tunnel把输出的隧道地址配置到提供商WorkOS 场景下需把它也注册为 Resource Indicator并传入audience: [SERVER_URL, TUNNEL_URL]就能在 ChatGPT / Claude 里走完完整的登录闭环。多 URL 场景的处理方式见 docs/guides/auth-providers.mdx 的 WorkOS 章节。参考资料核心文件清单内容路径认证全流程教程发布元数据、验证 token、混合模式docs/build/auth.mdx六大身份提供商接入指南docs/guides/auth-providers.mdx全站强制登录中间件docs/api-reference/require-bearer-auth.mdx混合公开与私有中间件docs/api-reference/optional-bearer-auth.mdxToken 验证器Verifier契约docs/api-reference/verifier.mdx授权服务器发现元数据路由docs/api-reference/mcp-auth-metadata-router.mdx可运行的 Clerk 认证示例examples/auth-clerk/src/server.ts服务端框架源码认证实现所在目录packages/core/src/server/总结为 MCP App 接入 OAuth 并安全验证用户身份在 Skybridge 中只需三步选一个提供商用一行oauth配置接上Auth0、Clerk、WorkOS 等六选一或customProvider自定义、用requireBearerAuth或optionalBearerAuth声明你的鉴权策略、在处理器里通过extra.http?.authInfo读取可信用户。整个过程中登录、token 刷新等复杂流程都由宿主托管你只需专注业务逻辑即可为 ChatGPT 和 Claude 里的 App 加上既简单又安全的大门。【免费下载链接】skybridgeSkybridge is a full-stack TypeScript framework for MCP Apps and ChatGPT Apps. Type-safe. React-powered. Platform-agnostic.项目地址: https://gitcode.com/gh_mirrors/skybr/skybridge创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
