Medusa Auth 模块 Github OAuth 登录提供方auth-github完整指南从配置、OAuth 流程到源码级原理【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusaMedusa 将认证能力抽象为独立的 Auth 模块而medusajs/auth-github是官方提供的基于 Github OAuth 的认证提供方让用户可以通过 Github 账号完成登录。本文以 auth-github 的 README 为核心骨架结合其 服务实现、集成测试 与 Auth 模块基础类源码系统讲解该提供方的工作原理、配置方式、手动联调步骤以及各 API 端点的底层实现帮助你在自己的 Medusa 项目中快速接入并排障 Github 登录。一、提供方概览与包结构medusajs/auth-github是 Medusa 官方提供的 Github OAuth 认证提供方其包名为medusajs/auth-github版本与medusajs/framework同步当前仓库中为 2.20.1见 package.json并声明node 20的运行环境要求。该提供方的核心实现位于以下三个文件src/index.ts通过ModuleProvider(Modules.AUTH, { services })将GithubAuthService注册为 Auth 模块下的一个提供方src/services/github.ts提供方的全部业务逻辑包括配置校验、发起 OAuth 授权、处理回调、换取 token、创建/更新 auth identityintegration-tests/tests/services.spec.ts基于mswMock Service Worker对 Github 接口进行网络层 mock 的集成测试覆盖了提供方的完整行为。在GithubAuthService中定义了两个关键的静态属性static identifier github static DISPLAY_NAME Github Authentication其中identifier是提供方的唯一标识。根据 AbstractAuthModuleProvider 的说明每个 Auth 提供方都必须声明identifier它在数据库中以au_{identifier}_{id}的形式被存储同时用于配置时在providers数组中区分不同提供方DISPLAY_NAME则用于前端展示提供方的名称。二、必填配置项与启动期校验该提供方的配置类型定义在 packages/core/types/src/auth/providers/github.tsexport interface GithubAuthProviderOptions { clientId: string clientSecret: string callbackUrl: string }三个配置项均为必填配置项类型含义clientIdstring在 Github App 设置中获取的 Client IDclientSecretstring为 Github App 生成的 Client SecretcallbackUrlstringOAuth 回调地址Github 完成授权后会把用户重定向回该地址服务启动时框架会调用静态方法validateOptions见 github.ts逐一校验这三个配置项任何一项缺失都会抛出对应错误例如Github clientId is required Github clientSecret is required Github callbackUrl is required这一点在集成测试中有直接验证services.spec.ts当只传入clientId与clientSecret时validateOptions抛出的错误信息为Github callbackUrl is required。因此接入时务必先在 Github 侧完成 App 注册并补齐三项配置。三、在 medusa-config 中启用提供方要在项目中使用该提供方需在medusa-config.ts的modules配置中为 Auth 模块声明提供方写法与同目录下的其他认证提供方如auth-emailpass一致。参考 integration-tests/http/medusa-config.js 中 Auth 模块提供方的声明方式一个典型的配置如下module.exports defineConfig({ // ... modules: [ { resolve: medusajs/medusa/auth, options: { providers: [ { resolve: medusajs/auth-github, id: github, options: { clientId: process.env.GITHUB_CLIENT_ID, clientSecret: process.env.GITHUB_CLIENT_SECRET, callbackUrl: process.env.GITHUB_CALLBACK_URL, }, }, ], }, }, ], })配置说明resolve指向提供方包名medusajs/auth-githubid为提供方在项目中的实例标识会与identifier一起用于生成 auth identity 的 provider idoptions中的三个字段与GithubAuthProviderOptions一一对应强烈建议通过环境变量注入避免把clientSecret提交到代码仓库callbackUrl必须与 Github App 设置中登记的 callback URL 保持一致否则回调阶段 Github 会拒绝请求。需要注意的是register方法在该提供方中不被支持。在 github.ts 中register直接抛出MedusaError类型为NOT_ALLOWED错误信息明确提示Github does not support registration. Use methodauthenticateinstead.也就是说Github 登录走的是纯 OAuth 认证流程不支持通过注册接口创建身份这与其他支持用户名/密码注册的提供方如 emailpass形成对比。四、OAuth 认证流程与三个核心方法Medusa 的 Auth 模块定义了一套标准的提供方接口见 AbstractAuthModuleProvider其中authenticate、validateCallback、register是核心方法。Github 提供方实现了 OAuth 2.0 Authorization Code 流程浏览器 -- Medusa /auth/github (authenticate) -- 302 跳转 Github 授权页 浏览器 -- Github 授权 -- 302 跳回 callbackUrl?codexxxstateyyy 浏览器/前端 -- Medusa 回调接口 (validateCallback) -- 换取 access_token -- 拉取用户信息 -- upsert auth identity4.1 authenticate发起授权跳转authenticate方法github.ts负责生成并返回 Github 授权页地址错误透传如果请求 query 中携带error字段例如用户在 Github 侧点击拒绝授权直接返回失败响应并把error_description与error_uri拼进错误信息生成随机 state使用crypto.randomBytes(32).toString(hex)生成 64 位十六进制随机串作为stateKey这是防 CSRF 的标准做法保存 statestate 中记录回调地址callback_url优先取请求 body 中的callback_url否则回退到配置中的callbackUrl通过authIdentityService.setState(stateKey, state)暂存供后续回调校验拼接授权 URL由私有方法getRedirectgithub.ts生成https://github.com/login/oauth/authorize并依次设置redirect_uri、client_id、response_typecode、state四个参数。最终返回结构为{ success: true, location: 授权页URL }。集成测试对这一点有精确断言services.spec.ts期望的 location 形如https://github.com/login/oauth/authorize?redirect_uriencodeURIComponent(callback)client_idtestresponse_typecodestate随机state同时测试还验证了自定义回调地址场景services.spec.ts当请求 body 携带callback_url: https://someotherurl.com时生成的授权 URL 中的redirect_uri会替换为自定义值且被 URL 编码。4.2 validateCallback校验回调并换取令牌当用户在 Github 授权后Github 会带着code与state重定向到 callbackUrl前端拿到这些参数后调用 Medusa 的回调接口进而触发validateCallbackgithub.ts。该方法的处理链路如下错误透传同样先检查 query/body 中的errorcode 校验从query.code或body.code取授权码缺失时返回No code providedstate 校验通过authIdentityService.getState(query.state)读取之前暂存的 state取不到时返回No state provided, or session expired。这里正是 4.1 中随机 state 发挥作用的地方——只有携带合法 state 的回调才会被继续处理从而防止攻击者伪造回调换取 access_token向https://github.com/login/oauth/access_token发起 POST 请求query 参数包含client_id、client_secret、code、redirect_uri取自 state 中的callback_url并声明Accept: application/json。如果响应非 2xx抛出MedusaError类型INVALID_DATA错误信息为Could not exchange token, {status}, {statusText}组装 providerMetadata把响应的access_token、refresh_token以及按秒计算的expires_in、refresh_token_expires_in转换为Date并序列化为 ISO 字符串得到access_token_expires_at与refresh_token_expires_at调用 upsert_ 持久化身份详见下节。集成测试覆盖了上述各失败分支与成功分支services.spec.ts包括空 code、缺失 state、state 过期/非法、非法 code 换 token 返回 401对应错误Could not exchange token, 401, Unauthorized以及合法 code 对新用户和已存在用户两种 upsert 路径的成功返回。注意测试中的 token 交换与用户信息接口均由msw在网络层 mock并不真正请求 Github。4.3 upsert_拉取用户信息并持久化 auth identityupsert_方法github.ts负责把 Github 用户映射为 Medusa 的 auth identity校验 tokenproviderMetadata.access_token缺失时返回No access token found拉取用户信息携带Authorization: Bearer access_token请求https://api.github.com/user构造 entity_id以 Github 用户数字id作为身份主键user.id.toString()构造 userMetadata从 Github 用户对象中提取profile_url、avatar、email、name、company、two_factor_authentication缺省视为false等资料字段更新或创建先尝试authIdentityService.update(entity_id, { provider_metadata, user_metadata })更新已存在身份若抛出NOT_FOUND类型错误说明是新用户则回退调用authIdentityService.create(...)创建新身份其他异常则返回{ success: false, error: error.message }。从这里可以看出该提供方对provider_metadata与user_metadata的职责划分前者保存 token 及过期时间等提供方运行所需数据后者保存用户画像资料这一约定与 AbstractAuthModuleProvider 中对两个字段的文档说明完全一致。五、手动联调完整步骤README 实操指南auth-github/README.md 提供了一套不依赖前端、直接在测试中手动跑通 OAuth 流程的联调步骤下面结合源码逐条展开说明其原理注册一个 Github App。进入 Github 的 App 注册页面创建应用配置好 Homepage URL并设置与callbackUrl一致的 Authorization callback URL。获取凭据。进入已创建的 App记录Client ID并为 App 生成一个新的Client Secret。把凭据替换到测试中。在 services.spec.ts 的beforeAll中将GithubAuthService实例的配置替换为真实的clientId、clientSecret与callbackUrlgithubService new GithubAuthService( { logger: console as any }, { clientId: 你的Client ID, clientSecret: 你的Client Secret, callbackUrl: https://someurl.com/auth/github/callback, } )移除server.listen()调用。测试中的mswserver 会把 Github 接口替换为本地 mock见 services.spec.ts只有注释掉beforeAll里的server.listen()请求才会真正打到 Github从而实现真实联调。运行测试并取 location。先运行authenticate相关的测试用例从返回结果中取出location字段即https://github.com/login/oauth/authorize?...在浏览器中打开该地址。复制 code 参数。在 Github 完成授权后浏览器会被重定向到回调地址URL 中会带code与state参数把code的值填入某个callback成功测试用例的 query 中替换掉valid-code同时确保state已按测试中的写法预置在 mock 的 state 存储中。运行测试验证结果。执行回调测试后若一切正常返回结果中会包含success: true与authIdentity内含access_token、refresh_token及过期时间等 provider_metadata 信息说明完整的 OAuth 换取 token、拉取用户、持久化身份链路已打通。这套流程的可行性建立在前面分析的源码之上authenticate返回的location携带了state而validateCallback会先校验 state 再换 token手动联调时只要保证测试中预置的 state 与浏览器回调带回的 state 一致就能走通全链路。包内脚本可直接运行测试见 package.json 的scripts# 单元测试 yarn test # 集成测试 yarn test:integration其中test:integration使用--forceExit并匹配integration-tests/__tests__/.*\.spec\.ts下的用例且设置了jest.setTimeout(100000)100 秒超时为真实网络联调预留了充足的等待时间。六、安全与实现要点小结CSRF 防护每次authenticate都会生成 32 字节随机 state 并写入setState回调时必须通过getState取回且一一对应否则直接拒绝No state provided, or session expired。state 读取失败可能意味着会话过期这是设计上的预期行为。Token 存储access_token、refresh_token及双方过期时间均存入 auth identity 的provider_metadata过期时间由 Github 返回的秒数换算成 ISO 字符串便于后续刷新与审计。身份映射Github 用户数字 ID 作为entity_id与邮箱解耦避免了用户修改邮箱导致身份漂移的问题用户资料写入user_metadata供上层业务直接消费。异常兜底换 token 失败非 2xx、无 token、无 code、无 state 等所有异常路径都返回结构化的{ success: false, error }响应便于上层 API 层统一处理相关行为均有集成测试固化。七、进一步探索如需深入理解该提供方在框架层的行为建议继续阅读以下仓库文件AbstractAuthModuleProvider 基类authenticate/validateCallback/register的接口契约与各方法语义的完整文档GithubAuthProviderOptions 类型定义提供方配置项的类型约束github 服务实现 与 集成测试实现细节与行为规格的一一对应integration-tests/http/medusa-config.js查看 Auth 模块及其提供方在真实测试环境中的配置方式作为自己项目配置的参考模板。【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考