配置微信公众号扫码登录

SovereignID 使用公众号网页授权处理微信内登录，并通过带参数临时二维码和事件消息完成 PC 扫码登录。 上线前需要同时配置公众号域名、接口 IP 白名单和服务器消息推送。

一、准备公众号和 SovereignID

公众号管理员应先确认账号已获得网页授权与带参数二维码接口权限，并准备 AppID、AppSecret、公众号原始 ID 和平台下载的 MP_verify_*.txt 校验文件。

1. 为生产环境生成独立 Fernet 密钥，设置 WECHAT_CREDENTIAL_ENCRYPTION_KEY；不要复用 DJANGO_SECRET_KEY。
2. 设置 WECHAT_IDENTITY_GLOBAL_ENABLED=true，完成数据库迁移和生产发布。
3. 使用超级管理员进入 Django Admin，在“微信公众号”中新建公众号。
4. 填写 AppID、AppSecret、原始 ID、Webhook Token、EncodingAESKey，以及校验文件的文件名和内容。
5. 先勾选“启用”但暂不勾选“默认登录公众号”，保存后复制系统生成的服务器回调 URL、OAuth 回调 URL 和域名验证 URL。

conda run -n SovereignID python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

WECHAT_CREDENTIAL_ENCRYPTION_KEY=<独立 Fernet 密钥>
WECHAT_IDENTITY_GLOBAL_ENABLED=true

二、绑定业务域名

在微信公众平台（部分新版页面标为“微信开发者平台”）进入“设置与开发 → 公众号设置 → 功能设置”，找到“业务域名”并点击“设置”。 填写 SovereignID 的公网域名，例如 id.example.com，不要包含 https://、端口或路径。

1. 把平台提供的 MP_verify_*.txt 文件名和文件内容原样填入 SovereignID 公众号配置。
2. 访问 Admin 显示的“域名验证 URL”，确认返回 HTTP 200，响应正文与校验文件内容完全一致。
3. 回到微信平台提交域名并完成校验。反向代理不得拦截或重写根路径下的校验文件请求。

三、配置 JS 接口安全域名

在同一“功能设置”区域打开“JS 接口安全域名”，填写同一个 SovereignID 公网域名，例如 id.example.com。 这里同样只填写域名，不带协议和路径，并使用上一步的 MP_verify_*.txt 完成验证。

当前扫码登录主要依赖公众号二维码接口和事件消息，不依赖前端 JSSDK；仍建议绑定该域名，为微信内页面能力和后续扩展保留一致的可信域名边界。

四、配置网页授权域名

在“设置与开发 → 公众号设置 → 功能设置”的“网页授权域名”中，或在“接口权限 → 网页服务 → 网页授权”入口，填写 SovereignID 公网域名。 微信内登录使用 snsapi_base，OAuth 回调 URL 的域名必须与这里完全一致。

五、配置接口 IP 白名单

SovereignID 需要使用 AppID 和 AppSecret 获取公众号全局 Access Token，再调用带参数二维码接口。 在“设置与开发 → 基本配置”的“IP 白名单”中填写生产节点实际访问微信 API 时使用的公网出口 IP。多节点或经 NAT 出口时，应填写所有可能的稳定出口地址。

六、打开消息推送

进入微信公众平台/微信开发者平台的“设置与开发 → 基本配置 → 服务器配置（消息推送）”，点击“修改配置”。 按下表填写后先提交验证，再点击“启用”。

微信提交服务器配置时会向 URL 发起校验请求。若失败，先确认公众号在 SovereignID 中已经“启用”、全局开关已打开、Token 一致，并检查反向代理是否允许该 URL 的 GET 和 POST 请求。

七、启用登录并验收

1. 在 Django Admin 选中公众号，执行“测试 Access Token（不显示 token）”，确认接口检测成功。
2. 确认微信平台的服务器配置已启用，消息模式为安全模式、数据格式为 XML。
3. 将公众号设为“启用”和“默认登录公众号”；系统最多允许一个默认登录公众号。
4. 使用已关注公众号的微信扫码，确认收到 SCAN 事件并完成登录。
5. 使用未关注公众号的微信扫码，关注后确认收到带 qrscene_ 参数的订阅事件并完成登录。
6. 在微信内打开登录页，确认网页授权回调正常；再验证首次联系方式校验、绑定、解绑和 OIDC 回跳。

八、常见排错