
Logto 微信原生连接器接入实战从微信开放平台申请到 iOS/Android SDK 集成【免费下载链接】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-native为核心完整讲解在原生 AppiOS 与 Android中接入微信登录的全过程先在微信开放平台创建移动应用并获取资质再在 Logto 控制台配置连接器最后分别在 Xcode 与 Android Studio 中完成 SDK 集成与跳转处理。读完本文你将掌握原生场景下微信社交登录从申请资质到真机验证的完整链路并理解连接器底层如何通过wechat://唤起微信、用 code 换取 access_token、拉取用户信息。连接器概览为什么原生应用不能走 Web 登录Logto 的连接器Connector是登录体验中的第三方能力适配层社交类连接器负责与对应平台完成授权码交换与用户信息获取。微信原生连接器是 Logto 官方为**原生应用iOS 与 Android**提供的微信社交登录连接器其元数据在 constant.ts 中定义id为wechat-nativetarget为wechatplatform为ConnectorPlatform.Native。与 Web 端微信登录最大的区别在于原生应用中无法通过网页完成微信登录——必须跳转到微信 App并且必须使用微信官方 SDK 来处理这个跳转。这也正是本文全部配置步骤的出发点。在 Logto 控制台为该连接器填写配置时需要三个字段对应 constant.ts 中的formItems配置项是否必填说明appId是微信开放平台移动应用的 App IDappSecret是微信开放平台移动应用的 App SecretuniversalLinks否iOS Universal Links用于唤起微信后回跳其中universalLinks是可选的它在微信开放平台网站后台叫universalLinks而微信 API 要求的参数名是universal_link连接器源码在拼装授权 URI 时已做了这一转换见 index.ts。配置校验由 types.ts 中的wechatNativeConfigGuard完成appId与appSecret必须为字符串universalLinks可选。第一步在微信开放平台创建移动应用在开始 SDK 集成之前必须先通过微信开放平台的资质审核拿到属于你自己的AppID、AppSecret以及 iOS Universal Links 等凭证。创建帐户打开微信开放平台官网点按右上角的「注册」按钮完成注册流程。如果你已有企业资质建议直接以认证主体注册因为移动应用的审核通常与主体资质相关。创建移动应用用刚创建的帐号登录后进入「移动应用」标签页点按大而绿的「创建移动应用」按钮即进入申请表单基础信息大多数字段都很直观文档给出了两个来自实战的提示如果只是测试微信登录、应用尚未上架 App Store可在「应用已上架」区域选择「否」从而跳过「已上架应用下载链接」的填写「App 运行流程图」看似简单实则关键经验表明准备一张简单的流程图并附上若干应用截图可以明显提升通过审核的概率。填写完毕后点按「下一步」进入平台信息配置。平台信息你可以单独或同时配置 iOS 与 Android 平台以在 Logto 中集成微信登录——也就是说一个移动应用申请可以同时覆盖双端。iOS 应用勾选「iOS 应用」与你的应用目标设备类型iPhone / iPad如果在「应用已上架」中选择了「否」此处可跳过「AppStore 下载地址」的填写。随后填写三项关键信息Bundle ID与 Xcode 工程中的 Bundle Identifier 一致测试版本 Bundle ID可以与 Bundle ID 相同Universal Links实际上只需填写一个有效的 universal link 即可。微信要求原生登录必须配置 universal link用于微信 App 登录完成后跳回你的应用。如果尚未配置或不清楚概念请先完成 Apple 官方 Universal Links 的配置Associated Domains 能力 apple-app-site-association 文件。Android 应用勾选「安卓应用」填写「应用签名」Application Signing Signature与「应用包名」Application Package Name其中「应用签名」来源于你对 APK 的正式签名需使用同一签名证书获取方式为完成签名后在 Android 工程根目录执行 Gradle 的signingReport任务./gradlew your-android-project:signingReport找到对应构建变体报告中的MD5值即为「应用签名」——但需要移除所有冒号并转换为小写。例如1A:2B:3C:4D - 1a2b3c4d等待审核结果完成平台信息后点按「提交审核」。官方反馈审核通常较快一般 12 天内完成。文档也坦诚地提示每次提交的审核者可能是随机分配的标准存在浮动第一次被拒并不罕见——此时应陈述你的现状例如仅用于测试、应用未上架并向审核者询问如何修改而不是放弃。第二步在 Logto 中配置连接器拿到微信开放平台的AppID、AppSecret与 Universal Links 后回到 Logto 控制台在「连接器」-「社交连接器」中找到「微信」即本连接器平台为 Native按前文表格填入AppID、AppSecret如有需要再填入universalLinks保存后在「登录体验」中将该连接器启用并拖入登录方式列表。如果对连接器概念或如何在登录体验中添加社交登录不熟悉可先阅读 Logto 官方的社交登录启用教程。配置保存时Logto 会以wechatNativeConfigGuard校验字段types.tsappId与appSecret缺失或类型错误将无法保存。第三步在 iOS 应用中启用微信原生登录以下步骤假设你的应用已经集成了 Logto iOS SDK接入后甚至不需要阅读微信 SDK 文档——所有微信交互都被封装在 Logto 的社交插件中。1. 配置 Universal Link 与 URL Scheme在 Xcode 工程中打开Signing Capabilities标签页添加Associated Domains能力并加入之前在微信开放平台填写的 universal link切换到Info标签页用微信 App ID添加一个自定义 URL SchemeCustom URL Scheme打开Info.plist在LSApplicationQueriesSchemes数组中添加weixinULAPI与weixin两个条目文档特别说明这些操作看起来并不优雅但这是实测的最小可工作方案。更详细的机制说明可参考微信官方的 iOS 接入指南。2. 添加LogtoSocialPluginWechat到工程将LogtoSocialPluginWechat这个 framework 加入 Xcode 工程并在Build Settings Linking Other Linker Flags中添加-ObjC标志。该插件已内置WeChat Open SDK 1.9.2导入插件后可直接import WechatOpenSDK使用微信 SDK 的 API。3. 将插件注入LogtoClient初始化项let logtoClient LogtoClient( useConfig: config, socialPlugins: [LogtoSocialPluginWechat()] )4. 妥当处理onOpenURL微信登录完成后会通过 universal link 或 URL scheme 回跳应用此时需要把 URL 交给 Logto 处理// SwiftUI YourRootView() .onOpenURL { url in LogtoClient.handle(url: url) } // 或 AppDelegate func application(_ app: UIApplication, open url: URL, options: /*...*/) - Bool { LogtoClient.handle(url: url) }LogtoClient.handle(url:)会统一处理你启用的所有原生连接器只需调用一次即可无需为每个连接器分别分发。从连接器源码可以印证这段回跳链路连接器的授权端点被定义为wechat://见 constant.tsgetAuthorizationUri会拼出形如wechat://?app_idappIdstatestateuniversal_linkuniversalLinks的 URIindex.ts由 Logto iOS SDK 调用系统能力唤起微信 App——这就是跳转至微信、再回跳至应用的底层机制。授权完成后微信通过 universal link / URL scheme 携带code回到应用最终由连接器的getUserInfo接收并换取用户信息详见下文登录流程的源码级原理。第四步在 Android 应用中启用微信原生登录以下步骤假设你的应用已经集成了 Logto Android SDK同样无需通读微信 SDK 文档。1. 添加 Wechat Open SDK 依赖确保 Gradle 仓库中包含mavenCentral()repositories { // ... mavenCentral() }然后在依赖中加入微信 Open SDK按你的构建脚本语法二选一dependencies { // ... api(com.tencent.mm.opensdk:wechat-sdk-android:6.8.0) // kotlin-script // 或 api com.tencent.mm.opensdk:wechat-sdk-android:6.8.0 // groovy-script }2. 引入WXEntryActivity微信 SDK 要求在你的应用根 package 下创建一个wxapi子包并在其中放置WXEntryActivity且该类需继承 Logto Android SDK 提供的WechatSocialResultActivity。以包名com.sample.app为例// WXEntryActivity.kt package com.sample.app.wxapi import io.logto.sdk.android.auth.social.wechat.WechatSocialResultActivity class WXEntryActivity: WechatSocialResultActivity()// WXEntryActivity.java package com.sample.app.wxapi import io.logto.sdk.android.auth.social.wechat.WechatSocialResultActivity public class WXEntryActivity extends WechatSocialResultActivity {}最终WXEntryActivity在工程中的位置应类似于以 Kotlin 为例src/main/kotlin/com/sample/app/wxapi/WXEntryActivity.kt3. 修改AndroidManifest.xml在AndroidManifest.xml中声明该 Activity注意android:exportedtrue是 Android 12 的强制要求?xml version1.0 encodingutf-8? manifest xmlns:androidhttp://schemas.android.com/apk/res/android packagecom.sample.app application !-- 添加的代码 -- activity android:name.wxapi.WXEntryActivity android:exportedtrue/ /application /manifest至此微信 App 的回跳通过WXEntryActivity即可被 Logto Android SDK 捕获并转入连接器的授权回调流程。登录流程的源码级原理连接器的完整实现位于 index.ts它实现了 connector-kit 中SocialConnector接口定义见 social.ts所要求的getAuthorizationUri与getUserInfo两个核心方法类型为ConnectorType.Socialindex.ts。整个原生登录流程分为三段1. 唤起微信getAuthorizationUri使用wechat://scheme 唤起微信 App携带app_id、state以及可选的universal_linkindex.ts。state由 Logto 会话管理用于防 CSRF 与回跳校验。2. code 换取 access_token用户在微信内确认授权后微信通过回跳携带code。连接器随后请求https://api.weixin.qq.com/sns/oauth2/access_token参数为appid、secret、code、grant_typeauthorization_code超时时间为 5 秒index.ts、constant.ts。响应中的access_token与openid缺一不可否则视为无效响应。3. 拉取用户信息getUserInfo携带access_token与openid请求https://api.weixin.qq.com/sns/userinfo从响应中提取unionid、headimgurl头像、nickname昵称最终规范化为 Logto 统一的SocialUserInfo结构index.tsreturn { id: unionid ?? openid, avatar: headimgurl, name: nickname, rawData };这里有一个值得注意的设计用户 ID 优先取unionid取不到时才回退到openid。unionid是微信开放平台下同一用户跨应用的唯一标识用它作为用户 ID 可以避免同一微信用户在不同应用下被识别为不同账号。错误码映射constant.ts 与 index.ts错误码含义连接器处理40029、40163、42003授权 code 无效/已使用/过期抛出SocialAuthCodeInvalid40001、40014access_token 无效抛出SocialAccessTokenInvalid其他errcode微信业务错误抛出General附带errmsg与errcodeHTTP 401凭证失效抛出SocialAccessTokenInvalid测试微信原生连接器完成以上全部配置后别忘了在 Logto 控制台的登录体验中启用本连接器这也是添加连接器的最后一步。启用后构建并运行你的应用即可验证在登录页面点击微信图标应用应唤起微信 App在微信中确认授权后自动回跳至应用并完成登录首次登录会为微信用户创建 Logto 用户档案昵称与头像自动带出。仓库中的测试用例 index.test.ts 对上述链路做了完整的单测覆盖可作为排查问题时的对照例如getAuthorizationUri应生成wechat://?app_id...state...getAccessToken用 code 换取 token并在40029/40163时抛出SocialAuthCodeInvalidgetUserInfo正确返回{ id, avatar, name, rawData }在 openid 缺失、token 失效40001或 HTTP 401 时抛出对应错误。⚠️注意微信并不对未安装微信的设备负责。若设备上未安装微信 AppLogto 会在登录体验中自动隐藏本连接器——这也是微信官方开发指南的推荐做法避免用户点击后无法完成跳转。小结微信原生登录与常规 OAuth 社交登录的差异集中在必须唤起微信 App 并依赖其 SDK这一点上。通过 Logto 的微信原生连接器这一差异被完整封装接入方只需要在微信开放平台完成资质申请在 iOS/Android 工程中各做一次跳转配置剩下的授权码交换、用户信息拉取、错误映射与设备降级无微信时隐藏连接器均由连接器与 Logto SDK 自动完成。如果想深入阅读实现可从 index.ts 的getAuthorizationUri与getUserInfo入手结合 index.test.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),仅供参考