微信

RootAuth 支持将已认证的微信服务号配置为第三方登录/注册方式。开启后，用户可以在 PC 端登录或注册页面使用微信 APP 扫码，并在关注服务号后自动完成注册或登录。

路径：登录 RootAuth 控制台 → 进入目标应用 → 点击顶部导航栏的「配置」→「认证配置」→ 选择「提供方」

 

1. 开始前准备

配置微信登录前，请先完成以下准备：

1. 拥有一个已完成微信认证的微信服务号。订阅号不支持此登录方式。
2. 在微信公众平台获取服务号的开发者 ID（AppID）和开发者密钥（AppSecret）。
3. 确认可以在微信公众平台配置消息推送、网页授权域名和 IP 白名单。
4. 确认微信服务号年审时间仍在有效期内。

同一套 AppID 和 AppSecret 对应的 access_token 在全局唯一。多台服务器同时获取时可能互相覆盖，请仅使用一台中控服务器获取和刷新，其他业务服务器通过该服务调用。

 

2. 在 RootAuth 后台开启微信

2.1 开启微信提供方

在「提供方」列表中找到「微信」，点击右侧「启用」。

打开配置弹窗后，开启顶部的微信开关。开关开启后，配置字段和「保存」按钮可用。

 

2.2 选择二维码生成方式

RootAuth 支持两种二维码生成方式：

生成方式	说明
事件二维码	通过微信接口生成带场景值的二维码。用户扫码后进入服务号，关注或扫码事件回调至 RootAuth，支持未关注用户在关注后自动完成登录。默认选择此方式。
网页 URL 二维码	二维码内容为微信网页授权地址。用户扫码后在微信内打开网页，通过网页授权获取 OpenID，不处理关注事件。

 

2.3 配置事件二维码

选择「事件二维码」后，填写以下信息：

配置项	是否必填	说明
开发者 ID	是	微信公众平台提供的 AppID。
开发者密钥	是	微信公众平台提供的 AppSecret。
Token	是	3-32 位英文字母或数字，必须与微信公众平台的消息推送配置保持一致。
回调地址	系统生成	RootAuth 根据当前应用生成，支持复制。请将该地址配置为微信公众平台的消息推送 URL。
二维码有效期	是	二维码有效时间，单位为秒，默认 600 秒。二维码过期后，将自动刷新获取新二维码。
IP 白名单	系统生成	RootAuth 提供的服务器 IP，支持复制。请添加到微信公众平台的 APP IP 白名单。
EncodingAESKey	是	43 位消息加解密密钥，必须与微信公众平台配置保持一致。
服务号年审时间	是	选择微信服务号的年审日期，服务号过期可能导致接口权限失效，影响用户登录。
消息加密方式	固定	固定为「安全模式（推荐）」。微信公众平台必须选择相同模式。
登录模式	固定	固定为「可用于登录注册」，不支持取消。

请先在 RootAuth 保存与微信公众平台一致的 Token、EncodingAESKey 和回调地址，再前往微信公众平台保存消息推送配置。否则微信侧校验可能失败。

 

2.4 配置网页 URL 二维码

选择「网页 URL 二维码」后，填写或确认以下信息：

配置项	是否必填	说明
开发者 ID	是	微信公众平台提供的 AppID。
开发者密钥	是	微信公众平台提供的 AppSecret。
域名	系统生成	RootAuth 提供的网页授权域名，支持复制。请配置到微信服务号的网页授权域名中。
IP 白名单	系统生成	RootAuth 提供的服务器 IP，支持复制。请添加到微信公众平台的 APP IP 白名单。
服务号年审时间	是	选择微信服务号的年审日期，不能选择当天之前的日期。
登录模式	固定	固定为「可用于登录注册」，不支持取消。

 

2.5 保存配置

填写完成后，点击「保存」。保存成功后：

1. 微信提供方显示「已启用」和「微信服务号关注」标识。
2. 右侧按钮变为「管理」。
3. 点击「管理」可以查看或修改已保存配置。

3. 配置微信公众平台

保存 RootAuth 配置后，还需要在微信公众平台完成相应设置。

3.1 事件二维码

步骤	配置项	操作
1	服务器 URL	复制 RootAuth 提供的回调地址，配置到微信公众平台的消息推送 URL。
2	Token	填写与 RootAuth 后台一致的 Token。
3	EncodingAESKey	在微信公众平台生成或填写密钥，并确保与 RootAuth 后台一致。
4	消息加解密方式	选择「安全模式」，与 RootAuth 后台保持一致。
5	IP 白名单	将 RootAuth 提供的服务器 IP 添加到微信公众平台的 APP IP 白名单。

 

3.2 网页 URL 二维码

步骤	配置项	操作
1	网页授权域名	复制 RootAuth 提供的域名，配置到微信服务号后台「账号设置」→「功能设置」→「网页授权域名」。
2	IP 白名单	将 RootAuth 提供的服务器 IP 添加到微信公众平台的 APP IP 白名单。

 

4. 用户如何使用微信登录

4.1 Hosted 接入

使用 RootAuth 托管的登录/注册页面时，开启微信后，第三方登录区域会显示微信入口。用户点击后，页面会弹出微信二维码。

如果同时启用 Google、Facebook、微信等多个第三方提供方，登录入口会按页面配置顺序显示。当页面将部分提供方收起时，微信入口可能显示在「更多登录」或「更多注册」中。

 

4.2 扫码登录或注册

1. 用户在登录或注册页面点击微信入口。
2. 页面弹出二维码，用户使用微信 APP 扫码。
3. 使用事件二维码时，尚未关注服务号的用户需要先完成关注。
4. RootAuth 根据微信返回的用户标识查找关联账号。
5. 如果已有账号，RootAuth 直接完成登录；如果没有账号，RootAuth 自动创建新账号并完成登录。
6. 登录成功后，二维码弹窗关闭，页面跳转至应用回调地址。

无论用户从登录页、注册页还是登录注册合并页扫码，RootAuth 都会根据账号是否已存在自动完成登录或注册。

 

 

 

 

 

 

 

 

 

4.3 API 接入

如果应用使用自建前端，可以通过 RootAuth API 实现微信扫码入口。接入流程通常包括：

1. 获取带场景值的微信二维码。
2. 轮询或查询二维码扫码状态。
3. 在扫码成功后获取用户信息和登录态。

API 接入时，二维码展示、加载状态、过期刷新和登录成功后的页面跳转由应用自行实现。

 

5. 查看用户的微信认证方式

5.1 查看用户记录

用户通过微信扫码完成注册后，RootAuth 会正常创建用户记录。如果微信没有返回邮箱或手机号，用户列表中的对应字段会显示为空。

管理员可以进入「用户管理」→「用户」，打开用户详情后补充邮箱、手机号等基础信息。

 

5.2 查看认证方式

进入用户详情页，在「认证方式」区域可以查看「微信服务号关注」记录。

字段	说明
认证方式	微信服务号关注
标识	与当前用户关联的微信用户标识，例如 OpenID。
最后使用时间	用户最近一次使用微信服务号登录的时间。

6. 绑定或解绑微信账号

微信扫码登录会在没有关联账号时自动创建新用户。如果希望将微信身份绑定到一个已有账号，应用需要在用户登录后通过 RootAuth API 完成绑定。

• 绑定：已登录用户提交微信授权结果，由应用调用 RootAuth API 将微信身份与当前账号关联。
• 解绑：已登录用户发起解绑，由应用调用 RootAuth API 清除当前账号的微信绑定记录。
• 一个微信账号只能关联一个系统账号。

RootAuth 管理后台不提供管理员手动绑定或解绑微信账号的按钮。应用需要自行集成绑定和解绑流程。

 

7. 日志记录

RootAuth 会在「审计日志」→「用户行为日志」中记录微信相关操作。

事件类型	说明
微信服务号注册	用户通过微信扫码创建新账号。
微信服务号登录	用户通过微信扫码登录已有账号。
绑定微信服务号	已登录用户通过应用绑定微信服务号。
解绑微信服务号	已登录用户通过应用解绑微信服务号。

日志会记录用户、IP、国家、时间、结果和失败原因等信息。首次注册且尚未补充邮箱或手机号时，用户字段可能显示用户 ID；绑定账号后优先显示邮箱或手机号。

 

8. 关闭微信登录

如需关闭微信登录，点击微信右侧的「管理」，关闭弹窗顶部的开关，然后保存。

关闭后：

1. Hosted 登录/注册页不再展示微信入口。
2. 已填写的 AppID、AppSecret 和其他配置会保留，用于下次使用。
3. 已有用户的微信认证记录不会被删除。
4. 重新开启后，可以修改配置并保存，新配置会覆盖原有配置。