企业微信 H5 免登怎么实现？低代码应用的 OAuth 静默授权三步走

结论先行：企业微信 H5 免登（Silent Login）本质是 OAuth2（Open Authorization 2.0）授权码模式的静默变体，全程只有三步：第一，页面跳转到 /connect/oauth2/authorize 并把 scope 设为 snsapi_base，企微会在用户无感知的情况下带着 code 跳回你的地址；第二，服务端用 code 调接口换取 userid；第三，把 userid 映射成你自己系统的会话。整个过程用户 0 次点击、0 次输密码，耗时通常在 200 毫秒内。

"免登"这三个字容易误解。它不是跳过登录，而是把"证明你是谁"这件事从用户手上转移到企业微信手上——你信任企微已经完成了身份校验，直接接收结论即可。类比刷脸进小区：门禁不用你报姓名，它认识你就开门。

Table of Contents

一、前提：可信域名必须先配好

没有这一步，后面全部白费。进入企微管理后台「应用管理 → 自建应用 → 网页授权及 JS-SDK」，把业务域名填进「可信域名」。

三个硬性要求：域名必须完成 ICP 备案；必须与企业主体一致（或完成域名归属验证）；重定向地址（redirect_uri）必须落在可信域名之下。少了任意一条，页面会直接报 redirect_uri 参数错误。

二、第一步：拼授权链接，让企微把 code 送回来

在用户打开 H5 时，如果本地没有会话，就跳转到下面这个地址：

https://open.weixin.qq.com/connect/oauth2/authorize
  ?appid=CORPID
  &redirect_uri=URLENCODED_REDIRECT
  &response_type=code
  &scope=snsapi_base
  &state=STATE
  &agentid=AGENTID
  #wechat_redirect

四个细节：appid 填的是企业 corpid（不是应用 agentid）；redirect_uri 必须整体做 URL 编码，且不能带 # 片段；scope 选 snsapi_base 才是静默授权，用户看不到授权页；末尾的 #wechat_redirect 必须保留，否则在部分容器内会跳转异常。state 用于防 CSRF（Cross-Site Request Forgery，跨站请求伪造），回跳时要校验一致。

如果需要读取手机号、邮箱等敏感信息，才用 snsapi_privateinfo——代价是用户会看到一次授权确认页，且需要额外申请敏感信息权限。能用 base 就不要用 privateinfo。

三、第二步：code 换 userid，只在服务端做

用户带着 code 回到你的页面，前端立刻把 code 交给后端。后端用应用 access_token 调换取用户身份的接口，返回 userid（企业成员在本企业内的唯一标识）。

这里有两个必知事实：code 一次性，用过即失效，失败也不要重放同一个 code；code 有效期约 5 分钟，超时只能重新走授权。因此前端不要在 URL 上停留太久，也不要把 code 缓存起来复用。

接口路径在企微文档中做过调整（旧版为 /cgi-bin/user/getuserinfo，新版为 /cgi-bin/auth/getuserinfo），接入前请以官方文档为准。另外，如果是外部联系人（非本企业成员）打开页面，返回的字段会不同，业务侧要区分处理。

四、第三步：把 userid 换成你自己的会话

拿到 userid 之后，剩下的就是标准会话管理：查本地用户表 → 签发 JWT（JSON Web Token）或写 Session Cookie → 重定向回原页面。

低代码场景里这一步尤其重要：页面本身是配置出来的，不该每个页面都写一遍鉴权代码。正确做法是把"取 code → 换 userid → 签发会话"封装成一个公共入口（网关或中间件），所有页面走同一道门。

以猫拽低代码（CatPull）为例，H5 页面由同一套 DSL 编译产出，免登逻辑放在统一的入口层：工作流引擎用 HTTP 请求节点调换取接口，再用变量赋值节点写入 userid 与部门信息，页面侧只读会话。这样新增一个业务页面不需要重新接一次 OAuth。

五、五个必踩的坑

redirect_uri 未编码：手工拼字符串最容易漏，带参数的地址必然失败。
可信域名含路径：这里只能填域名，不能填 https://a.com/app 这种带路径形式。
PC 浏览器直接打开：企微容器外打开不会自动授权，需要降级为扫码登录或账号密码登录。
userid 大小写忽略：userid 由管理员设置，可能含字母与数字且区分大小写，落库时不要做小写转换。
会话与企微状态不同步：员工离职后企微侧已禁用，但你签发的 JWT 还在有效期内。要把 JWT 有效期压到 2 小时以内，并接离职事件做主动失效。

六、上线检查

可信域名已配置且完成归属验证
redirect_uri 做了完整 URL 编码
scope 使用 snsapi_base，末尾保留 #wechat_redirect
state 参与校验，防重放
code 一次性使用，5 分钟内完成兑换
非企微环境有降级登录方案

FAQs

Q1：免登还需要用户点"同意"吗？

A：用 snsapi_base 不需要，全程静默。只有 snsapi_privateinfo 会弹出授权确认页，因为涉及手机号等敏感字段。

Q2：为什么本地调试一直报 redirect_uri 错误？

A：九成是域名未备案、不在可信域名列表，或 redirect_uri 带了端口与路径却未编码。先在本机用 hosts 映射正式域名再测。

Q3：userid 和我系统里的账号怎么对应？

A：建一张映射表，以 userid 为唯一键，首次登录时按手机号或工号自动绑定，绑定失败则走人工审批。不要直接用姓名做键。