Logto 微信网页登录连接器接入指南从微信开放平台注册到社交登录上线的完整实战【免费下载链接】logto‍ Authentication and authorization infrastructure for SaaS and AI apps, built on OIDC and OAuth 2.1 with multi-tenancy, SSO, and RBAC.项目地址: https://gitcode.com/GitHub_Trending/lo/logto本指南以 Logto 官方微信网页连接器connector-wechat-web为主体完整讲解如何在微信开放平台创建网页应用、获取 App ID 与 App Secret、配置连接器的scope授权范围并最终在 Logto 登录体验中启用微信扫码登录。读完本文你将掌握微信网页版 OAuth 登录从平台申请、连接器配置到源码级原理解析的全链路实战能力。连接器定位与适用范围connector-wechat-web是 Logto 官方为网页应用提供的微信社交登录连接器实现的是微信开放平台「网站应用 / 微信扫码登录」能力即 OAuth 2.0 授权码模式。它通过logto/connector-kit的SocialConnector接口暴露给 Logto 核心声明为ConnectorPlatform.Web元数据中的target为wechat见 constant.ts。需要特别注意适用范围本连接器只适用于 Web 应用走的是网页端扫码授权流程如果你需要移动端原生 App 的微信登录应改用微信原生连接器connector-wechat-native两者授权协议与端点完全不同。在正式接入前建议先了解 Logto 的连接器Connector概念与社交登录启用流程可参考仓库根目录的 README.md 及连接器目录下的官方文档 connector-wechat-web/README.md 中「开始上手」一节的指引。第一步在微信开放平台创建网页应用如果你已经在微信开放平台完成过网页应用注册可以跳过本节的相应步骤。1.1 创建账号打开微信开放平台open.weixin.qq.com点击右上角「注册」按钮按引导完成账号注册流程。企业或个人均可注册但网站应用审核要求应用具备已备案且可访问的域名请提前准备好。1.2 创建网页应用使用刚注册的账号登录开放平台在「网页应用」标签页点击「创建网页应用」按钮进入申请表单申请表单包含三步填写基础信息 → 填写网站信息 → 提交审核。以下分别说明。基础信息表单中的大多数字段比较直白如实填写应用名称、简介、应用图标等信息即可。完成第一页表单后点击「下一步」继续。网站信息在「授权回调域」一栏填写你的 Logto 服务域名如logto.io。该域名必须与连接器实际使用的回调地址所在域名一致否则授权时会因回调域不匹配而失败。若 Logto 部署在子路径或使用自定义域名请以实际可公网访问的域名为准。等待审核结果完成网站信息后点击「提交审核」。微信网页应用的审核通常较快一般 1–2 天内出结果。需要说明的是审核标准可能存在波动首次提交被驳回的情况并不少见——如果被驳回应主动说明当前应用状态并向审核方询问具体的修改要求按反馈调整后重新提交即可。1.3 获取 Client ID 与 Client Secret审核通过后进入该网页应用的详情页即可看到Client IDApp ID / AppID应用的公开标识Client SecretApp Secret / AppSecret用于后端换取 access_token 的密钥请妥善保管切勿泄露到前端代码中。这两个值将用于下一步配置 Logto 连接器。第二步配置微信网页连接器在 Logto 管理控制台的连接器列表中启用并配置wechat-web连接器需要填写三个字段。其表单定义来自源码 constant.ts 中的formItems配置项的运行时校验则由 types.ts 中的wechatConfigGuard基于 zod完成配置字段是否必填说明校验规则appId必填微信开放平台网页应用详情页中的 App ID非空字符串appSecret必填同一应用详情页中的 App Secret非空字符串scope可选授权范围填snsapi_userinfo或snsapi_base可选字符串不填则使用默认值2.1 关于 scope 的取值说明scope决定微信授权时向用户申请的信息范围官方文档给出的两个可选值含义不同snsapi_userinfo静默授权 用户信息可获取用户昵称、头像等资料需要在开放平台通过相应接口权限审核snsapi_base仅静默授权只能拿到用户的 openid不返回用户资料。按 README 说明scope字段可以留空留空时默认使用snsapi_userinfo。而进一步查看源码实现见下文「授权 URL 构造」小节可以发现实际取值优先级为登录请求动态传入的自定义 scope 连接器配置的scope 源码常量兜底值snsapi_login。也就是说配置留空且登录请求未显式传 scope 时最终会落到常量 constant.ts 中定义的defaultScope snsapi_login网页扫码登录的标准 scope。这一点在排查授权 URL 时值得留意。第三步测试连接器并启用微信登录配置完成后即可进行验证在 Logto 管理控制台的「登录体验」Sign-in experience中将微信网页连接器添加到已启用的社交登录方式列表回到你的应用触发登录流程选择微信登录确认能够正常跳转到微信扫码授权页使用微信扫码并授权后确认能正确回跳并完成登录。注意连接器启用并配置完成后你需要在登录体验中将该社交连接器显式启用它才会出现在登录页上。深入原理连接器源码级解析理解底层实现有助于排查授权失败、用户信息缺失等问题。下面按登录流程的调用链逐段解读 index.ts 的实现。3.1 授权 URL 构造getAuthorizationUri连接器暴露的getAuthorizationUri方法负责拼接微信授权页面地址authorizationEndpoint https://open.weixin.qq.com/connect/qrconnect构造的查询参数包括appid连接器配置的appIdredirect_uri回跳地址需要 URL 编码必须与开放平台填写的授权回调域匹配response_typecode使用授权码模式scope按「自定义 scope → 配置 scope → 默认snsapi_login」的优先级取值state由 Logto 生成的随机状态值用于防 CSRF 与回调校验。测试用例 index.test.ts 中验证了生成的 URL 形态例如未传自定义 scope 时结果为https://open.weixin.qq.com/connect/qrconnect?appid%3Capp-id%3Eredirect_uri...response_typecodescopesnsapi_loginstatesome_state传入scope: custom_scope时URL 中的 scope 会被替换为custom_scope印证了取值的优先级逻辑。3.2 code 换 access_tokengetAccessToken用户扫码授权后微信会带着code重定向回 Logto。连接器随后调用微信接口accessTokenEndpoint https://api.weixin.qq.com/sns/oauth2/access_token请求参数为appid、secret、code、grant_typeauthorization_code所有请求设有 5 秒超时defaultTimeout。响应体通过 zod 的accessTokenResponseGuard校验成功时返回{ accessToken, openid }若响应中携带errcode则进入错误处理逻辑见 3.4。3.3 用户信息获取与归一化getUserInfo拿到 access_token 后连接器调用用户信息接口userInfoEndpoint https://api.weixin.qq.com/sns/userinfo请求参数为access_token与openid。响应经过userInfoResponseGuard校验后被归一化为 Logto 标准的SocialUserInfo结构定义见 social.tsreturn { id: unionid ?? openid, avatar: headimgurl, name: nickname, rawData };这里有一个关键细节用户唯一标识优先取unionid取不到时回退为openid。unionid是同一微信开放平台账号下跨应用网页、小程序、公众号、移动应用统一的用户标识优先使用它可以让同一个微信用户在不同应用中对应到同一个 Logto 用户而openid是应用维度的标识未绑定开放平台或未通过相应接口权限审核时才会出现缺失。原始响应会一并存入rawData字段便于后续扩展使用。3.4 错误码与异常处理微信接口的错误通过errcode/errmsg返回连接器针对常见错误做了专门映射错误码清单见 constant.ts场景errcode连接器错误类型授权码无效换取 access_token 阶段40029、40163、42003SocialAuthCodeInvalidaccess_token 无效获取用户信息阶段40001、40014SocialAccessTokenInvalid其余微信侧错误其他General附带errmsg与errcode此外若用户信息接口返回 HTTP 401也会被统一映射为SocialAccessTokenInvalid。这些错误会透传给 Logto 核心最终以可读的形式呈现给上层调用方。上述分支均有对应的单元测试覆盖见 index.test.ts例如用 nock 模拟微信返回errcode: 40029时断言抛出SocialAuthCodeInvalid模拟40001时断言抛出SocialAccessTokenInvalid。总结connector-wechat-web是 Logto 接入微信网页登录的官方通道接入路径清晰微信开放平台注册网页应用审核→ 在 Logto 中填写appId/appSecret/scope→ 在登录体验中启用。底层实现完整覆盖了授权 URL 构造、授权码换 token、用户信息归一化与错误映射四个环节并优先使用unionid作为跨应用用户标识。建议在接入时重点核对「授权回调域」与 Logto 实际回调地址的一致性并根据是否需要用户资料谨慎选择scope取值。若需进一步阅读源码可重点关注连接器实现index.ts端点与错误码常量constant.ts配置与响应校验zod schematypes.ts单元测试含 nock 模拟的完整登录链路index.test.ts社交连接器接口约定social.ts【免费下载链接】logto‍ Authentication and authorization infrastructure for SaaS and AI apps, built on OIDC and OAuth 2.1 with multi-tenancy, SSO, and RBAC.项目地址: https://gitcode.com/GitHub_Trending/lo/logto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考