跳到主要内容

微信开放平台对接说明

操作场景​

微信开放平台（open.weixin.qq.com）提供基于 OAuth 2.0 的网站应用授权登录能力，允许用户通过微信授权（PC 端表现为扫码授权，移动端微信内浏览器直接弹出授权确认）完成第三方网站的身份认证。通过对接微信开放平台，可实现 HAP 用户使用微信授权登录。

前提条件​

  1. 拥有已通过开发者资质认证的微信开放平台账号（需提供企业营业执照等资料）。
  2. HAP 服务可被公网访问，且回调域名已完成 ICP 备案（微信开放平台要求）。

操作步骤​

配置微信开放平台网站应用​

  1. 登录 微信开放平台

  2. 进入 管理中心 > 网站应用，点击 创建网站应用

    create-app-entry

  3. 填写应用基本信息（应用名称、应用简介、应用官网、应用图标等），点击 下一步

    警告

    表单中的 网站信息登记表扫描件 为必填项：需先点击 《微信开放平台网站信息登记表》 链接下载模板，打印后由企业加盖公章并由负责人签字，再将盖章签字后的纸质件扫描或拍照上传（支持 JPG/PNG/BMP，单文件不超过 5MB，最多 10 张）。该资料缺失或盖章不清晰会导致审核不通过。

    app-basic-info

  4. 填写授权回调域，需与 HAP 服务对外访问的域名一致（仅填写域名，无需协议和路径）

    • 例如 HAP 访问地址为 https://hap.domain.com，此处填写 hap.domain.com
    • 该域名需与后续 HAP 在添加微信登录后生成的 回调地址 中的域名保持一致
    app-callback-domain

  5. 提交后等待微信团队审核，审核通过后即可在应用详情中查看 AppID 和 AppSecret

    app-appid-secret

HAP 集成微信授权登录​

  1. 平台管理员登录 HAP，进入 平台管理 > 安全 > 登录设置

  2. 在 SSO 区域点击 + 服务，选择 微信

    sso-add-service

  3. 在弹出的对话框中填写以下信息，点击 保存

    • appid：微信开放平台网站应用的 AppID，如 wx9619034219c838xxxx
    • appsecret：微信开放平台网站应用的 AppSecret
    • 回调地址：由 HAP 自动生成，格式为 https://{HAP域名}/orgsso/weixin/callback，点击 复制 备用
    weixin-config

  4. 将上一步复制的 回调地址 中的域名（如 hap.domain.com）回填到微信开放平台对应网站应用的 授权回调域（创建应用时已填过的话，可在应用详情中修改），需与 HAP 一侧严格一致。

  5. 保存后，HAP 登录页将出现 微信 登录入口

用户 SSO 登录​

前提：先在个人信息中绑定第三方账号

使用微信 SSO 登录的前提是用户已在平台中提前绑定微信账号。绑定路径：右上角头像 > 个人账户 > 账户与隐私 > 第三方账户 > 选择 微信 点击 绑定 完成绑定。

未绑定的用户即使微信授权成功，也会被引导至 绑定页面 而非登录成功页面，需要先完成账号绑定后才能后续使用微信授权直接登录。

bind-third-party

  1. 访问 HAP 登录页，点击 微信登录 入口

    login-entry

  2. 跳转至微信扫码授权页面，使用微信扫码并在手机端点击 允许 完成授权

    wechat-authorize

  3. 授权完成后自动跳转回 HAP，已绑定该微信的用户直接登录成功；未绑定的用户会先跳转到绑定页面，绑定后即可登录。

  4. 登录失败排查

    • 私有部署 平台管理员登录 HAP，进入 平台管理 > 运维管理 > 日志，检索 服务名 为 sso 的日志；微信侧的 errcode/errmsg 会记录在 sso 服务日志中

    • 常见错误（按实际返回的错误码区分）：

      错误返回触发阶段排查方向
      微信授权页直接提示 redirect_uri 参数错误跳转到 open.weixin.qq.com/connect/qrconnect 时微信开放平台 授权回调域 与 HAP 自动生成的回调地址（https://{HAP域名}/orgsso/weixin/callback）域名不一致；两侧域名必须严格匹配，开放平台只填域名不带协议和路径
      MissParams发起授权前 / 回调时HAP 一侧 appid、appsecret、回调地址 未保存完整，或微信回调时未带 code 参数；重新到 登录设置 > SSO > 微信 检查并保存
      GetUserAccessTokenFaild用 code 换取 access_token 时查看 sso 日志中打印的 body：
      · errcode 40029 invalid code：授权码已过期或被使用，重新发起登录
      · errcode 40013 invalid appid：检查填写的 appid
      · errcode 40125 invalid appsecret：检查填写的 appsecret 是否被重置
      GetUserInfoFaild用 access_token + openid 拉取用户信息时查看 sso 日志中打印的 body：
      · errcode 40001 invalid credential：access_token 无效或已过期
      · errcode 40003 invalid openid：openid 与 token 不匹配
      授权成功但跳到绑定页面而非登录成功回调成功后当前微信账号未在 HAP 个人账户 > 账户与隐私 > 第三方账户 中绑定该用户；按页面提示完成绑定即可