Logto QQ 社交登录连接器接入指南：从 QQ 互联平台配置到 OAuth 授权码流程源码解析

Logto QQ 社交登录连接器接入指南从 QQ 互联平台配置到 OAuth 授权码流程源码解析【免费下载链接】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 官方 QQ 社交连接器README.md为核心完整讲解如何在 QQ 互联平台创建应用、配置回调地址与权限并将APP ID/APP Key填入 Logto 管理控制台启用 QQ 登录同时结合连接器源码src/index.ts逐层剖析授权码换取 Access Token、OpenID/UnionID 获取、用户信息拉取这一完整 OAuth 2.0 流程帮助开发者理解底层原理并快速完成生产环境接入与排障。连接器概览Logto 的 QQ 社交登录能力QQ 是腾讯旗下拥有超过 6 亿用户的社交平台。Logto 通过logto/connector-qq连接器让终端用户可以使用 QQ 账号直接登录你的应用免去单独注册账号的流程。该连接器属于 Logto 社交连接器ConnectorType.Social体系其包信息定义于 package.json当前仓库版本1.1.6核心特点包括基于 QQ 互联平台的OAuth 2.0 授权码模式Authorization Code实现使用UnionID 作为用户唯一标识可跨应用识别同一 QQ 用户提供中英双语官方文档README.md 与 README.zh-CN.md在管理控制台中提供clientId、clientSecret、scope三个可视化配置项。连接器的默认元信息定义在 constant.ts 中id为qq-universaltarget为qqplatform为Universal全平台通用可用于 Web 端等多端登录场景。开始上手QQ 互联平台账号与应用准备在接入之前需要先在 QQ 互联平台完成开发者账号与应用的基础准备步骤与原文档一致在 QQ 互联平台 注册并创建开发者账号个人或企业主体按平台要求完成实名认证与审核访问平台的「应用管理」页面connect.qq.com/manage.html创建一个新应用如果还没有的话。应用创建后需等待 QQ 互联平台审核通过才能获得正式的APP ID与APP Key。说明QQ 互联对个人开发者与企业开发者的应用类型、可用权限存在差异正式接入前请以 QQ 互联平台当前审核规则为准。配置 QQ Connect 应用回调域与回调地址应用创建完成后需要在 QQ 互联平台侧完成 OAuth 配置这是连接器能否收到授权回调的关键步骤进入「应用管理」页面connect.qq.com/manage.html打开你要用于登录的应用点击「应用信息」添加「网站回调域」填写你的logto_endpoint即 Logto 服务对外暴露的域名/地址例如https://your-logto.example.com添加「网站回调 URL」填写${logto_endpoint}/callback/${connector_id}。其中connector_id是你在 Logto 中创建的该社交连接器实例 ID注意与连接器工厂 IDqq-universal区分——实例 ID 是连接器被启用后由 Logto 分配的具体标识。Logto 核心服务正是通过packages/core/src/routes/callback.test.ts中验证的/callback/:connector_id路由接收第三方授权回调随后将用户引导回应用。填写凭据到 Logto 管理控制台从 QQ 互联平台的应用信息页获取APP ID与APP Key在 Logto 管理控制台找到 QQ 社交连接器将这两个值分别填入配置表单的clientId与clientSecret字段可选如需调整授权范围可填写scope字段多个 scope 之间用逗号分隔例如get_user_info,get_unionId不填时连接器默认使用get_user_info。三个配置项的完整定义可在 constant.ts 的表单项描述中确认配置校验规则schema则在 types.ts 中配置项是否必填类型说明clientId必填文本QQ 互联应用的APP IDclientSecret必填文本QQ 互联应用的APP Keyscope可选多行文本逗号分隔的授权范围缺省时按get_user_info处理redirectUri可选内部字符串存储于连接器会话中的回调地址由源码内部使用权限要求UnionID 与默认 scope使用 QQ 连接器必须满足以下权限要求否则用户信息获取会失败UnionID 权限必须申请连接器依赖 UnionID 作为用户唯一标识。若未申请 UnionID 接口调用权限源码会在getOpenIdAndUnionId阶段直接抛出错误详见下文「错误处理」小节提示你确认已申请 UnionID 权限。请通过 QQ 互联平台 申请该权限默认 scopeget_user_info用于获取用户的基本信息昵称、头像等。当授权请求未携带自定义 scope 参数时系统默认使用该权限源码中scope: customScope ?? scope ?? get_user_info。源码级解析QQ OAuth 2.0 授权码完整流程连接器的核心逻辑集中在 index.ts整个登录流程由三个关键阶段组成各阶段端点定义于 constant.ts阶段端点授权Authorizationhttps://graph.qq.com/oauth2.0/authorize令牌Tokenhttps://graph.qq.com/oauth2.0/token用户标识OpenID/UnionIDhttps://graph.qq.com/oauth2.0/me用户信息User Infohttps://graph.qq.com/user/get_user_info阶段一构造授权 URLgetAuthorizationUrigetAuthorizationUri根据连接器配置与当前请求参数拼接授权链接将用户重定向到 QQ 登录页https://graph.qq.com/oauth2.0/authorize?response_typecodeclient_idAPP IDredirect_uri回调地址statestatescopeget_user_info关键行为对应 index.ts使用response_typecode申请授权码redirect_uri会被写入连接器会话setSession({ redirectUri })供后续令牌交换阶段复用CHANGELOG 中 1.1.5 版本引入的「stored redirect URI」能力scope的取值优先级为请求自定义 scope → 配置中的scope→ 默认值get_user_info1.1.0 版本起支持自定义 scope 透传见 CHANGELOG.md。阶段二授权码换取 Access TokengetAccessToken用户授权后QQ 将携带code回调 Logto。连接器随即以授权码向令牌端点发起请求GET https://graph.qq.com/oauth2.0/token?grant_typeauthorization_codeclient_idAPP IDclient_secretAPP Keycodecoderedirect_uri回调地址fmtjson实现要点index.ts显式追加fmtjson要求 QQ 以 JSON 而非原生字符串格式返回令牌响应经accessTokenResponseGuardtypes.ts校验必须包含access_token与expires_in字段若响应缺失access_token如授权码失效抛出SocialAuthCodeInvalid错误HTTP 层异常则包装为带statusCode与响应体的General错误。阶段三获取 OpenID/UnionID 与用户信息getOpenIdAndUnionId getUserInfo拿到 Access Token 后连接器需要两个步骤才能得到标准化的用户资料① 获取 OpenID 与 UnionIDindex.tsGET https://graph.qq.com/oauth2.0/me?access_tokentokenfmtjsonunionid1一个值得注意的实现细节QQ 的/oauth2.0/me接口默认返回JSONP 格式形如callback({...});源码通过正则body.replace(/^callback\((.*)\);$/, $1)剥掉回调函数外壳后再解析 JSON。解析结果必须包含openid与unionid其中unionid用于跨应用唯一标识用户。② 拉取用户资料index.tsGET https://graph.qq.com/user/get_user_info?access_tokentokenoauth_consumer_keyAPP IDopenidopenid注意该接口必须同时携带oauth_consumer_key即应用的clientId与上一步拿到的openid。响应中ret字段为0表示成功非 0 则抛出包含ret/msg的错误测试用例覆盖了ret 100013access token 无效或过期与ret 100016access token 校验失败两种典型失败场景见 index.test.ts。最终连接器按 Logto 社交用户规范SocialUserInfo定义于 connector-kit 的 social.ts输出标准化结果{ id: unionid, // 用户唯一标识 name: nickname, // QQ 昵称 avatar: figureurl_qq_2 ?? figureurl_qq_1, // 优先取更高清的 QQ 头像 rawData: QQ 返回的完整原始用户数据 }测试连接器与正式启用配置完成后无需额外联调脚本即可在 Logto 中验证确认 Logto 管理控制台已保存正确的clientId与clientSecret前往「登录体验」Sign-in Experience的社交登录配置页管理控制台路径/console/connectors/social启用QQ 连接器在应用的登录页面发起一次 QQ 登录验证授权跳转、回调、用户资料落库的完整链路。连接器的单元测试index.test.ts覆盖了授权 URL 构造、令牌交换、用户信息获取与各类错误分支可作为理解行为边界的参考测试使用的模拟数据见 mock.ts。常见问题与排障提示结合源码可以给出以下典型的失败定位线索现象可能原因排查方向授权回调报UnionID not found未申请 UnionID 接口权限到 QQ 互联平台申请 UnionID 权限index.ts令牌交换报SocialAuthCodeInvalid授权码失效、重复使用或回调地址不一致核对授权时的redirect_uri与配置的回调 URL 是否完全一致用户信息接口返回ret 100013/100016Access Token 无效或已过期重新发起登录流程获取新令牌回调 404connector_id填写错误或回调域未配置核对「网站回调域」为logto_endpoint回调 URL 中实例 ID 正确接入完成后QQ 登录将与其他 Logto 社交连接器一样自动融入现有的多租户、RBAC 与统一登录体验体系用户可在同一套身份基础设施中获得一致的登录与账号管理体验。【免费下载链接】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），仅供参考