42 lines
4.8 KiB
Markdown
42 lines
4.8 KiB
Markdown
# App 第三方登录配置
|
||
|
||
代码支持 Android/iOS 的微信、QQ、Google 原生登录，以及 GitHub 系统浏览器授权。后台开关可以随时停用已接入渠道，但不能把 SDK 动态装入已经发布的 App。参数尚未配置、SDK 尚未打包的原生渠道不会显示。
|
||
|
||
## 部署顺序
|
||
|
||
1. 先备份数据库，执行后端新增迁移 `backend/migrations/027_app_oauth_login.sql`，再发布新版后端。该迁移保留已有 H5 绑定，增加 App 登录平台、回调证明及身份应用范围。
|
||
2. 发布新版管理端。在“平台配置 → 第三方登录”分别配置管理端、H5、App 开关。App 开关默认关闭，不会沿用 H5 开关。
|
||
3. 在 HBuilderX 的 `manifest.json → App SDK 配置 → 登录鉴权` 勾选所需 SDK，填写下面的平台信息，然后云打包或制作自定义调试基座。标准基座的示例 AppID 不能用于本项目正式登录。
|
||
4. 在真实 Android/iOS 设备上逐个验证授权成功、取消授权、首次手机号绑定、再次登录，以及后台关闭渠道后拒绝登录。`npm run build:app-plus` 只生成 App 资源，并不生成已签名 APK/IPA。
|
||
|
||
## 各渠道参数
|
||
|
||
| 渠道 | 后台 | HBuilderX / 开放平台 |
|
||
| --- | --- | --- |
|
||
| 微信 | App 微信 AppID、App 微信 AppSecret、App 启用微信登录 | 微信开放平台**移动应用** AppID；登记 Android 包名及签名、iOS Bundle ID 与 Universal Links。AppSecret 只保存在后端，客户端使用 `onlyAuthorize: true` 获取 code。 |
|
||
| QQ | App QQ AppID、App 启用 QQ 登录 | QQ 移动应用 SDK 配置和实际包名、签名、Bundle ID；AppID 与后台一致。服务端验证令牌所属 AppID，忽略客户端自行提交的 OpenID。 |
|
||
| Google | App Google Client ID 白名单、App 启用 Google 登录 | 注册 Android（包名及签名）和 iOS OAuth Client ID；配置 Google 登录模块与 iOS Client ID；将实际签发令牌的 Android/iOS 客户端 ID 加入后台白名单，以英文逗号分隔。设备与服务端须能访问 Google 服务。 |
|
||
| GitHub | 下方共用的 GitHub OAuth 应用参数、App 启用 GitHub 登录、App 回调地址 | GitHub OAuth App 填后端的 **HTTPS** 回调，例如 `https://api.example.com/api/v1/auth/oauth/callback`。不要填 App Scheme。Android/iOS 均已在 manifest 注册 `xingyuim` Scheme。 |
|
||
|
||
GitHub 的 App 返回地址固定为 `xingyuim://oauth/callback`。App 在打开系统浏览器之前保存本次请求 ID 和私有证明；后端回调携带短期一次性登录码，兑换和手机号绑定还必须提交该私有证明。证明不进入浏览器 URL，截获 Scheme 回调的其他 App 无法单独兑换登录态。支持 App 被系统结束后从回调冷启动。
|
||
|
||
微信、QQ 的网站应用与移动应用 OpenID 不一定相同。本次实现按移动 AppID 隔离绑定，首次 App 登录可能需要对**已注册手机号**做一次短信验证；不会只凭昵称、邮箱或未经验证的 OpenID 自动合并账号。Google、GitHub 使用同渠道的稳定身份，可复用已有绑定。
|
||
|
||
## 接口
|
||
|
||
- `GET /api/v1/auth/oauth/providers?platform=app`：仅返回后端已启用、参数完整的 App 渠道。省略 platform 保持旧版 H5 行为。App 再与实际打包 SDK 取交集。
|
||
- `POST /api/v1/auth/oauth/native`：微信提交 `{provider:"wechat", code}`；QQ/Google 提交 `{provider, accessToken}`。后端向官方接口校验后返回 `oauthCode`。所有请求必须使用 HTTPS。
|
||
- `POST /api/v1/auth/oauth/start`：GitHub App 提交 `{provider:"github", platform:"app"}`，返回授权 URL、requestId、appProof 和 callbackUrl。
|
||
- `POST /api/v1/auth/oauth/exchange`：提交 `{code, deviceId, appProof?}`，已绑定时返回登录态，未绑定时返回 `requiresLink`。
|
||
- `POST /api/v1/auth/oauth/link`：提交 `{code, phone, smsCode, deviceId, appProof?}`，验证已注册手机号并绑定。GitHub App 的 `appProof` 必填。
|
||
|
||
渠道在列表、授权发起、授权回调、登录码兑换及绑定处均校验开关。停用渠道阻止新的第三方登录，不会撤销已经签发的账户会话。回到登录页时刷新渠道列表。
|
||
|
||
## 本地检查
|
||
|
||
在 mobile 目录运行 `npm run test:oauth`、`npm run test:native-config`、`npm run type-check`、`npm run build:h5` 和 `npm run build:app-plus`。后端运行 `go test ./...`。
|
||
|
||
这些检查不代替第三方平台审核、真机 SDK 授权和 iOS/Android 回跳测试。不要把 AppSecret、访问令牌、回调证明或登录码粘贴到日志里。
|
||
|
||
官方参考：[uni-app 登录](https://uniapp.dcloud.net.cn/api/plugins/login)、[微信 App 登录](https://uniapp.dcloud.net.cn/tutorial/app-oauth-weixin.html)、[Google App 登录](https://uniapp.dcloud.net.cn/tutorial/app-oauth-google.html)、[Android URL Scheme](https://uniapp.dcloud.io/tutorial/app-android-schemes.html)。
|