跳到主要内容
安装配置教程

钉钉H5 https要求怎么配?内置浏览器、可信域名与JSAPI验收清单

钉钉h5 https要求 — 钉钉H5 https要求怎么配?内置浏览器、可信域名与JSAPI验收清单
核心结论

钉钉H5 https要求的核心结论:生产环境应使用受信任CA签发的HTTPS证书,域名与证书SAN匹配,启用TLS 1.2/1.3,页面及JS/CSS/图片/接口全部走https,否则钉钉内置浏览器会出现混合内容拦截或JSAPI鉴权失败。 用 openssl s_client -connect h5.example.com:443 -servername h5.example.com -tls1_2 </dev/null 检查证书链,输出 Verify return code: 0 (ok) 才算通过;再用 curl -I http://h5.example.com 确认返回301到https。 Nginx 1.24.0/1.26.1 建议配置 ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384'; HSTS 可用 max-age=31536000。 钉钉开放平台可信域名需与H5页面主域名同源,dd.config 的 url 必须与当前页面URL一致(含路径和查询参数、不含#后片段),签名失败优先查URL编码、时间戳偏差和jsapi_ticket缓存。 证书选型:单域名DV约0-200元/年,多域名SAN DV约100-800元/年,通配符DV约300-1500元/年,OV约800-3000元/年;钉钉H5生产更看重证书链完整和自动续期,而不是证书类型本身。

钉钉H5 https要求到底卡在哪?问题背景与根本原因

钉钉H5页面跑在 Android WebView 或 iOS WKWebView 里,所以钉钉h5 https要求并不是钉钉发明的协议,而是三层约束叠加的结果:浏览器安全上下文(Secure Context,只有 https 或 localhost 才暴露 crypto.subtle、Service Worker、getUserMedia 等 API)、系统 WebView 的明文流量策略,以及钉钉 JSAPI 鉴权时对页面 URL 与可信域名的比对。理解这一点很关键——把问题当成“买张证书就行”,后面必然反复返工。

最典型的表现来自 Android:从 Android 9(API 28)起,android:usesCleartextTraffic 的默认值变为 false,即 cleartextTrafficPermitted=false。钉钉内置 WebView 沿用宿主 App 的网络安全配置,页面里只要引用一个 http 的图片、脚本或 XHR,控制台就会抛出 net::ERR_CLEARTEXT_NOT_PERMITTED,而且往往整段逻辑静默失败,不像 404 那样显眼。据钉钉开放平台文档,H5 微应用/网页应用需要在开发者后台填写应用首页地址、可信域名(JSAPI 安全域名)和 OAuth 回调地址三项;生产环境应把三者统一到同一个 https 主域名,否则会出现跨域拦截、dd.config 签名 URL 与实际页面 URL 不一致、登录回跳丢 query 参数等连锁问题。

排查应从服务端链路开始,而不是先怀疑钉钉。用 OpenSSL 一次性看清证书链、SAN 与有效期(OpenSSL 1.1.1 / 3.x 均适用):

# 1) 打印服务器下发的完整证书链,并检查是否缺中间证书
openssl s_client -connect h5.example.com:443 -servername h5.example.com -showcerts /dev/null 
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName
# 期望:subjectAltName 中包含当前访问的完整域名;issuer 不应等于 subject(自签)

# 2) 用系统信任库做一次严格校验,报错即说明链不完整或根不受信
openssl s_client -connect h5.example.com:443 -servername h5.example.com 
  -verify_return_error -CAfile /etc/ssl/certs/ca-certificates.crt </dev/null

# 3) 确认 TLS 1.0/1.1 已关闭(应返回 handshake failure)
openssl s_client -connect h5.example.com:443 -tls1_1 </dev/null

# 4) 确认 301/302 跳转没有把 https 降回 http,也没有丢路径
curl -sSI http://h5.example.com/path?x=1 | grep -iE '^(HTTP/|location)'

若第 4 步的 Location 是 http://... 或丢掉了 /path?x=1,钉钉内就会出现“登录后白屏”或“回跳参数丢失”。另一个高频根因是反向代理只终止了 TLS,却没把原始协议传给应用,后端继续用 http 拼绝对 URL,于是页面里混入了明文资源。Nginx 侧的最小修复(add_header ... always 需 1.7.5+,TLSv1.3 需 1.13.0+ 且 OpenSSL 1.1.1+):

server {
    listen 443 ssl;
    server_name h5.example.com;

    ssl_certificate     /etc/nginx/cert/fullchain.pem;  # 必须是「叶子+中间」全链,只配 leaf 会被部分 Android 判为链不完整
    ssl_certificate_key /etc/nginx/cert/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;                # 旧版 WebView 不支持 TLS1.0/1.1,但也不应回退开启
    add_header Strict-Transport-Security "max-age=31536000" always;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-Proto $scheme;     # 缺失时应用会生成 http 绝对 URL,触发混合内容
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    }
}
钉钉内现象 最可能根因 验证方式
ERR_CLEARTEXT_NOT_PERMITTED 页面引用了 http 资源(Android 9+ 默认禁止明文) DevTools Network 过滤 http://
iOS 直接白屏、无报错 自签证书或链不完整,WKWebView 直接拒绝 openssl s_client -verify_return_error
“域名不在安全域名列表” 可信域名只填了主域,实际访问了未覆盖的子域 比对页面 URL 与后台可信域名逐字符一致
dd.config 签名失败 / jsapi 鉴权报错 传入的 url 与 location.href(含 hash 前部分)不一致 打印实际签名 URL 与页面 URL 对比
开发者工具正常、钉钉内失败 CDN 回源走 http,或 LB 未传 X-Forwarded-Proto 在钉钉内抓包看最终请求 scheme

客户端差异同样会造成“同一条链接,不同人结果不同”。Android 钉钉 7.x 与 iOS 钉钉 7.x 使用的 WebView 内核不同,部分老旧 Android 机型的系统根证书库停留在多年前,对交叉签名链更敏感。使用 Let’s Encrypt 证书时,务必确认 fullchain.pem 中包含指向 ISRG Root X1(及新链中的 X2)的完整交叉链——据 Let’s Encrypt 文档,其证书默认有效期 90 天,且已从 ACME 协议层面推动短周期证书,链路配置错误会在续期后突然暴露。

最后一类误判是“只测了一处”。开发者工具 https 正常却在钉钉内失败,通常是四个位置之一没对齐:CDN 回源协议、负载均衡的协议透传、dd.config 的签名 URL、后台可信域名与实际子域。按上面四步命令逐项验证,比反复重装证书有效得多。

钉钉H5 https要求完整实操步骤:从域名到可信域名配置

钉钉H5 https要求真正卡人的地方从来不是”买张证书”,而是六个环节里任意一环出错都会让 JSAPI 静默失效。下面按可执行顺序走一遍,每步都给命令和验收点。

步骤1:域名规划。准备 h5.example.com(页面)与 api.example.com(接口),两条 A 记录指向同一 TLS 入口。证书 SAN 必须同时覆盖这两个名字——据 RFC 5280 §4.2.1.6,客户端只校验 SAN,CN 字段已被主流浏览器忽略,只签单域名会在 H5 页面调接口时报 NET::ERR_CERT_COMMON_NAME_INVALID。生产入口禁止用 IP、非 443 端口或临时域名,钉钉内置浏览器与 OAuth 回调都不接受。

步骤2:申请证书。Let’s Encrypt 官方推荐 certbot(2.10 起支持 --deploy-hook):

# certbot 2.10+,webroot 校验,两个域名同一张证书
certbot certonly --webroot -w /var/www/acme 
  -d h5.example.com -d api.example.com 
  --deploy-hook "systemctl reload nginx"
# 产物目录 /etc/letsencrypt/live/h5.example.com/ 下的 fullchain.pem 与 privkey.pem
# acme.sh 3.0.7 等价写法
acme.sh --issue --webroot /var/www/acme -d h5.example.com -d api.example.com 
  --keylength ec-256 --server letsencrypt
方案 签发耗时 有效期 适用场景
Let’s Encrypt + certbot 1 分钟内 90 天,需自动续期 自建服务、内部测试
acme.sh 1 分钟内 90 天,可签发 ECC 无 root、纯 shell 环境
商业 OV/EV 1–5 个工作日(需提交营业执照等组织资料) 398 天起 需企业身份背书的生产入口

步骤3:配置 TLS 入口。Nginx 1.24.0 / 1.26.1 写法如下,注意证书必须加载 fullchain(叶子证书 + 中间证书),只放叶子证书时安卓 WebView 会报”证书链不完整”:

server {
    listen 80;
    server_name h5.example.com api.example.com;
    return 301 https://$host$request_uri;      # 步骤4:强制 HTTPS
}
server {
    listen 443 ssl;                            # nginx 1.24 用 "listen 443 ssl http2;"
    http2 on;                                  # 1.25.1+ 的新指令写法
    server_name h5.example.com api.example.com;

    ssl_certificate     /etc/letsencrypt/live/h5.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/h5.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;       # 默认 ssl_protocols 为 TLSv1 TLSv1.1 TLSv1.2
    ssl_session_cache   shared:SSL:10m;        # 默认 none,1MB 约存 4000 会话
    ssl_session_timeout 1d;                    # 默认 5m
    ssl_session_tickets off;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-Proto $scheme;   # 后端据此生成 https 链接
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    }
}

前端绝对 URL 统一写 https://,后端生成跳转链接时读取可信代理头而非 $_SERVER['HTTPS'],否则反向代理下会拼出 http 地址导致 301 循环。

步骤5:钉钉开放平台配置。H5 微应用首页地址填 https://h5.example.com/index;可信域名按后台提示填 h5.example.com(据钉钉开放平台文档,该字段通常不带协议与路径);OAuth 回调填 https://h5.example.com/callback。保存后必须退出应用重新进入,必要时清钉钉缓存,否则旧配置仍生效。

步骤6:JSAPI 鉴权。服务端用 appKey/appSecret 换 access_token,再换 jsapi_ticket,按字典序拼接后 SHA1:

# 待签名字符串(顺序固定,url 为当前页面去掉 # 后的完整地址)
jsapi_ticket=abc&noncestr=Wm3WZYTPz0wzccnW&timestamp=1700000000&url=https://h5.example.com/index
dd.config({
  agentId: '123456789',
  corpId: 'dingxxxxxxxx',
  timeStamp: 1700000000,
  nonceStr: 'Wm3WZYTPz0wzccnW',
  signature: '<SHA1 结果>',
  jsApiList: ['biz.util.openLink', 'device.notification.alert']
});
// url 必须与签名时一致,取 location.href.split('#')[0]

签错时最典型的返回是 {"errcode":52013,"errmsg":"签名校验失败"},九成原因是签名 URL 带了 # 之后的内容或 http/https 不一致;若返回 {"errcode":60020,"errmsg":"访问ip不在白名单之中"},去后台把服务器出口 IP 加进白名单即可。

钉钉H5 https要求下的Nginx、Apache与Node配置示例(含版本参数)

同一张证书、同一套 TLS 参数,落到不同 Web 服务器上的写法差别很大,而且各有各的”静默失败”点。下面按钉钉H5 https要求的实际验收场景给出三份可直接复制的配置,并标注版本与默认值。

Nginx 1.24.0 / 1.26.1:证书路径沿用 Let’s Encrypt 的 live/ 目录(据 Let’s Encrypt 文档,该目录是指向 archive/ 的软链,续期后无需 reload 证书文件本身,但需 reload 让 Nginx 重新读取)。

# Nginx 1.24.0 / 1.26.1,/etc/nginx/conf.d/h5.conf
server {
    listen 443 ssl http2;          # 1.25.1 起 http2 参数被弃用,1.26.x 建议改写为 listen 443 ssl; + http2 on;
    server_name h5.example.com;
    ssl_certificate     /etc/letsencrypt/live/h5.example.com/fullchain.pem;  # 必须用 fullchain,缺中间证书钉钉内置浏览器会报错
    ssl_certificate_key /etc/letsencrypt/live/h5.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;   # 默认值为 TLSv1 TLSv1.1 TLSv1.2(旧版本),务必显式覆盖
    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384';
    ssl_prefer_server_ciphers off;         # 默认 on;TLS1.3 时代交给客户端选更优(Mozilla 推荐 off)
    ssl_session_cache   shared:SSL:10m;    # 10MB 约可缓存 4 万个会话
    ssl_session_timeout 1d;
    add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains' always;  # includeSubDomains 前确认所有子域都有 HTTPS

    # 可选:OCSP Stapling,需服务器能直连 CA 的 OCSP 响应器
    ssl_stapling on;
    ssl_stapling_verify on;
    resolver 223.5.5.5 119.29.29.29 valid=300s;
    resolver_timeout 5s;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-Proto $scheme;   # 后端判断 req.secure 的唯一依据
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    }
}

Apache 2.4.59:需先 a2enmod ssl headers(Debian/Ubuntu)或确认 mod_ssl、mod_headers 已加载。注意 SSLCipherSuite 只作用于 TLS 1.2 及以下,TLS 1.3 的套件由 OpenSSL 1.1.1+ 默认控制,想改需用 SSLConfCmd。

# Apache 2.4.59,/etc/apache2/sites-available/h5-ssl.conf
<VirtualHost *:443>
    ServerName h5.example.com
    SSLEngine on
    SSLCertificateFile    /etc/letsencrypt/live/h5.example.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/h5.example.com/privkey.pem
    SSLProtocol -all +TLSv1.2 +TLSv1.3
    SSLCipherSuite HIGH:!aNULL:!MD5
    SSLHonorCipherOrder off
    Header always set Strict-Transport-Security "max-age=31536000"
    ProxyPass        / http://127.0.0.1:8080/
    ProxyPassReverse / http://127.0.0.1:8080/
    RequestHeader set X-Forwarded-Proto "https"
</VirtualHost>
# 修改后:apachectl configtest && systemctl reload apache2

Node 20.11 + Express 4.x:反向代理场景下最容易踩的坑是 req.secure 恒为 false,导致 301 重定向死循环。app.set('trust proxy', 1) 告诉 Express 信任”一跳”代理,它才会去读 X-Forwarded-Proto;设为 true 则无条件信任任何来源,存在被伪造头绕过 HTTPS 校验的风险。

// Node 20.11 + Express 4.18,仅监听 127.0.0.1:8080,由 Nginx 终结 TLS
app.set('trust proxy', 1);                  // 关键:1 = 只信任最近一层代理
app.use((req, res, next) => {
  if (req.secure) return next();            // 读的是 X-Forwarded-Proto=https
  return res.redirect(301, 'https://' + req.headers.host + req.originalUrl);
});
app.use(helmet.hsts({ maxAge: 31536000, includeSubDomains: true }));
项目 Nginx 1.26.1 Apache 2.4.59 Node 20.11 + Express
证书链文件 ssl_certificate 必须 fullchain SSLCertificateFile 必须 fullchain 不直接管证书
协议控制默认值 旧版默认含 TLSv1/1.1,需显式写 默认 SSLProtocol all -SSLv3 取决于前置代理
HSTS 写法 add_header ... always Header always set helmet.hsts()
典型故障 忘记 always,4xx/5xx 不带头 未加载 mod_headers 直接 500 trust proxy 未设 → 重定向循环

上线前用三条命令自检。注意:据 OpenSSL 3.0 文档,s_client 只有加 -servername 才会发送 SNI,否则服务器可能返回默认站点证书,验证结果毫无意义。

# 1) 语法检查 + 平滑重载(Nginx 输出 syntax is ok / test is successful 才算通过)
nginx -t && systemctl reload nginx

# 2) 抓证书链:必须带 -servername 触发 SNI(OpenSSL 3.0 手册)
openssl s_client -connect h5.example.com:443 -servername h5.example.com -showcerts </dev/null

# 3) 校验 SAN 与有效期:RFC 6125 要求证书 SAN 必须匹配实际访问域名,CN 字段已不再作为依据
echo | openssl s_client -connect h5.example.com:443 -servername h5.example.com 2>/dev/null 
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

若第 3 步输出的 SAN 里没有 h5.example.com,或 -dates 显示 notAfter 已过期,钉钉内置浏览器(基于系统 WebView)会直接拦截页面——这就是钉钉h5 https要求里最常被忽略的一环:证书本身合法,但域名不匹配。参数取值可参照 Mozilla SSL Configuration Generator 的 “Intermediate” 档位,它在兼容性与安全性之间留了足够余量。

钉钉H5 https要求方案选型:DV、OV、通配符与多域名证书怎么选

钉钉H5 https要求下,DV、OV、通配符、多域名证书到底差在哪?

先把结论摆在桌面上:钉钉内置浏览器是系统 WebView 的封装,它判断”是否安全”只看三件事——服务器是否下发完整证书链、证书 SAN 是否覆盖你访问的域名、签发者根证书是否在系统信任库中。DV 与 OV 在这一层的表现完全一致,OV 多出来的只是组织信息核验与合规展示价值。据 Let’s Encrypt 官方文档,其证书默认有效期 90 天(官方已公告将逐步缩短至 45 天,时间表以其官网为准),这意味着”自动续期”必须写进钉钉h5 https要求的验收项,而不是可选项。

方案 典型用途 价格区间(人民币/年) 钉钉H5 https要求关注点
单域名 DV h5.example.com 0-200 适合测试与轻量页面,必须部署 fullchain,Let’s Encrypt 有效期 90 天
多域名 SAN DV h5 + api + callback 100-800 一张证书覆盖多个子域,减少钉钉页面跨域证书告警
通配符 DV *.example.com 300-1500 适合多租户 H5,注意通配符只匹配一级子域
OV 单域名/多域名 企业门户、支付 800-3000 浏览器信任与 DV 相同,增加组织核验,适合合规展示
自签 / 内网 CA 开发联调 0 钉钉移动端默认不信任,生产不建议;需导入根证书才可用

选型怎么快速定?三条规则

  • 只有 h5.example.com 和 api.example.com 这类固定几个域名,优先多域名 SAN DV,一张证书、一次续期,省掉漏配某台机器的风险。
  • 存在 tenant1.example.com、tenant2.example.com 这种同级子域且会持续新增,用通配符 *.example.com 更省维护。
  • 出现 a.b.example.com 这种二级子域,通配符不覆盖(RFC 6125 的 wildcard 只匹配一层标签),必须单独加 SAN,否则钉钉里会直接白屏。
# 适用 certbot 2.x(apt/EPEL 默认源),证书默认 90 天
# 场景一:多域名 SAN,HTTP-01 验证,webroot 需可被外网访问 /.well-known/acme-challenge/
certbot certonly --webroot -w /var/www/acme 
  -d h5.example.com -d api.example.com -d callback.example.com 
  --email ops@example.com --agree-tos --no-eff-email

# 场景二:通配符只能走 DNS-01,HTTP-01 无法签发 *.example.com
certbot certonly --manual --preferred-challenges dns 
  -d '*.example.com' -d example.com

# 验收:退出码 0 才算续期链路可用(含 hook、DNS 插件、权限)
certbot renew --dry-run
echo $?   # 0 = 成功;1 = 需看 /var/log/letsencrypt/letsencrypt.log

# 续期后必须让进程重新加载证书文件,否则内存里还是旧证书
systemctl reload nginx

用 acme.sh 的话,安装时默认写入 0 0 * * * 的 crontab,续期靠 --cron;务必用 --install-cert 的 --reloadcmd 把 reload 动作挂上去,并用 crontab -l | grep acme.sh 确认条目没被清理脚本删掉。

CDN 和负载均衡上,证书放哪一层?

放在最外层 TLS 终止点(CDN 边缘或 SLB 监听器),回源协议建议也开 HTTPS;若回源必须走 HTTP,至少要让应用能读到 X-Forwarded-Proto: https,否则钉钉 JSAPI 的鉴权签名、回调地址拼接会因协议判断错误而失败。TLS 参数不必再兼容 TLS 1.0/1.1——据 Mozilla SSL Configuration Generator(2024 版),现代配置以 TLS 1.2/1.3 + ECDHE + AES-GCM/CHACHA20 为主。

# nginx 1.25.1+ 写法;旧版本改为 listen 443 ssl http2;
server {
    listen 443 ssl;
    http2 on;
    ssl_certificate     /etc/nginx/ssl/example.pem;   # 必须是 fullchain,含中间证书
    ssl_certificate_key /etc/nginx/ssl/example.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
}

# 自检:看 SAN 是否覆盖域名、链是否完整
openssl s_client -connect h5.example.com:443 -servername h5.example.com /dev/null 
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

如果输出里出现 Verify return code: 21 (unable to verify the first certificate),说明只部署了站点证书、漏了中间证书,这是钉钉内置浏览器最常见的”https 配置好了但页面打不开”的原因。采购时还要确认报价是否含通配符、支持几个 SAN、是否提供中间证书下载——这三点比 CA 品牌更影响钉钉h5 https要求的落地成本。

钉钉 H5 https 要求本身不复杂,线上报错几乎都集中在“资源改造不彻底”和“证书链不全”两类。按报错原文对号入座,先查第一嫌疑点,再动手改配置。

报错原文 第一嫌疑点 一条命令定位
net::ERR_CLEARTEXT_NOT_PERMITTED 页面仍加载 http:// 资源 grep -rnoE “http://[^”‘ ]+” dist/
Mixed Content … requested an insecure resource 前端写死或后端返回 http 绝对 URL DevTools Network 按 http:// 过滤
ERR_CERT_COMMON_NAME_INVALID / AUTHORITY_INVALID SAN 缺域名、缺中间证书 openssl s_client -showcerts
ERR_SSL_PROTOCOL_ERROR TLS 版本或套件不匹配 openssl s_client -tls1_2
dd.config fail: 签名校验失败 url 不一致、时间戳偏差、ticket 过期 服务端打印待签名串比对
ERR_TOO_MANY_REDIRECTS 反代未传 X-Forwarded-Proto curl -I 看 Location 头

为什么 Android 9 以上才报 ERR_CLEARTEXT_NOT_PERMITTED?因为 Android 9(API 28)起 android:usesCleartextTraffic 默认值变为 false,WebView 直接拒绝明文请求;钉钉内置浏览器在旧机型上走的是系统 WebView,所以同一份代码在新旧手机上表现不同。先全量扫一遍静态资源,再逐个改成 https,接口域名同样要改,不要只改页面地址。

# 扫描构建产物里残留的明文 http 资源(JS/CSS/图片/接口)
grep -rnoE "http://[a-zA-Z0-9./?=&_%:-]+" dist/ | sort -u
# 输出为空才算通过;有结果就逐个替换为 https 或改走同域相对路径

Mixed Content 用 CSP 兜底够不够?不够。据 MDN 对混合内容的说明,upgrade-insecure-requests 只是浏览器侧的重写兜底,图片、XHR 中写死的 http 绝对 URL 一旦被后端拼进 JSON,仍然会失效。真正的修法是让后端返回相对路径或 https 绝对地址。

证书类报错怎么一步定位?据 OpenSSL 文档,-showcerts 会打印服务端发送的完整链。若只输出一段证书,说明 Nginx 只配了域名证书而没带中间证书,Android WebView 会报 ERR_CERT_AUTHORITY_INVALID。

# 查看服务端实际下发的证书链,期望至少两段(叶子证书 + 中间证书)
openssl s_client -connect h5.example.com:443 -servername h5.example.com -showcerts /dev/null 
  | grep -E "^ *[0-9]+ s:|^ *i:"
# Nginx 关键配置:fullchain 必须包含中间证书
ssl_certificate     /etc/letsencrypt/live/h5.example.com/fullchain.pem;  # 不是 cert.pem
ssl_certificate_key /etc/letsencrypt/live/h5.example.com/privkey.pem;
ssl_protocols       TLSv1.2 TLSv1.3;   # 只开 TLS 1.3 会让 Android 6~9 WebView 握手失败
ssl_ciphers         ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256;
proxy_set_header    X-Forwarded-Proto $scheme;  # 缺这行,应用会生成 http 跳转导致重定向循环

Apache 侧对应 SSLCertificateFile 指向 fullchain、SSLCertificateKeyFile 指向私钥;Node/Express 需 app.set('trust proxy', 1) 才会读 X-Forwarded-Proto。若前面还有 CDN 或 SLB,回源协议与证书要各自单独验证一遍。

dd.config 签名失败先看哪三项?据钉钉开放平台 JSAPI 鉴权文档:签名用的 url 必须是当前页面完整 URL(含 ? 参数、不含 # 后片段);timestamp 与服务器时间偏差不得超过 1 小时;jsapi_ticket 有效期 7200 秒,必须缓存并提前刷新。三者任一不符都报“签名校验失败”,与“可信域名未配置”报错文本不同,先分清再改。

# 在服务端把待签名串打出来,与前端 location.href 逐字符比对
string1 = "jsapi_ticket=" + ticket + "&noncestr=" + nonceStr +
          "&timestamp=" + timestamp + "&url=" + url;
console.log(string1);   // url 必须是 https 开头、去掉 #hash 的完整地址

最后提醒:以上每一项都属于钉钉 H5 https 要求的硬性前提,任一项不满足,JSAPI 鉴权或页面加载就会失败,配置可信域名和申请接口权限都补不回来。

钉钉H5 https要求效果验证:如何确认配置在钉钉内置浏览器生效

配置完证书不等于钉钉里就能用。钉钉 7.x 的 Android 端基于系统 WebView、iOS 端基于 WKWebView,两者的混合内容策略和 TLS 行为并不一致,所以验收必须分三层做:命令行 → 钉钉容器 → JSAPI 业务链路。下面是一条可以照抄执行的清单。

第一层:80 端口是否强制跳转?这是钉钉 H5 https 要求里最容易被漏掉的一条——证书配好了,但 80 端口仍在返回 200,用户从旧链接、二维码或消息卡片点进来会先落到明文页,WebView 里的 location.protocol 就是 http:,后续 JSAPI 签名 URL 直接对不上。

# 期望 301 + Location 指向 https,若返回 200 说明未做强制跳转
curl -sI http://h5.example.com | head -n 6
# HTTP/1.1 301 Moved Permanently
# Location: https://h5.example.com/

# 期望 HTTP/2 200,且带 HSTS(RFC 6797)
curl -sI https://h5.example.com | grep -Ei '^HTTP/|strict-transport-security'
# HTTP/2 200
# strict-transport-security: max-age=31536000; includeSubDomains

第二层:TLS 版本与证书 SAN。钉钉 iOS 端要求 TLS 1.2 起步(RFC 8996 已废弃 1.0/1.1),建议同时开 1.3(RFC 8446)。注意 -tls1_3 需要 OpenSSL 1.1.1 及以上。

# TLS 1.2 握手 + 证书链校验,必须看到 Verify return code: 0 (ok)
openssl s_client -connect h5.example.com:443 -servername h5.example.com -tls1_2 /dev/null 
  | grep -E 'Protocol|Verify return code'

# TLS 1.3 是否可用;报 wrong version number / handshake failure 说明未启用
openssl s_client -connect h5.example.com:443 -servername h5.example.com -tls1_3 /dev/null 
  | grep -E 'Protocol|Verify return code'

# SAN 必须同时覆盖 H5 域名和 JSAPI 回调/接口域名
openssl s_client -connect h5.example.com:443 -servername h5.example.com /dev/null 
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName
# X509v3 Subject Alternative Name:
#     DNS:h5.example.com, DNS:api.example.com
# notAfter=Sep 12 03:14:07 2025 GMT   ← 剩余不足 30 天就该告警
验收项 通过标准 失败时的典型含义
80 端口 301 → https,Location 完整 返回 200:未强制跳转,明文页可访问
443 响应 HTTP/2 200 + HSTS 头 HTTP/1.1:未开 h2;无 HSTS:易被降级
TLS 握手 1.2 与 1.3 均 Verify return code: 0 (ok) 非 0:中间证书缺失,Android 端常直接白屏
证书 SAN 含全部业务域名 缺 api 域名:接口请求报 NET::ERR_CERT_COMMON_NAME_INVALID

第三层:钉钉容器内实测。Android/iOS 钉钉 7.x 打开工作台应用,用 vConsole 或在页面注入以下代码,确认协议与容器:

// 期望输出 "https: ... DingTalk/7.x.x"
console.log(location.protocol, navigator.userAgent);

dd.ready(function () {
  // 期望 android / ios,而非 undefined
  console.log('platform:', dd.env.platform, 'version:', dd.env.version);

  // 免登链路验证:能拿到 code 说明可信域名、corpId、agentId、签名 URL 全部对齐
  dd.runtime.permission.requestAuthCode({
    corpId: 'dingxxxxxxxxxxxxxxxx',
    onSuccess: function (res) { console.log('authCode:', res.code); },
    onFail: function (err) { console.log('authFail:', JSON.stringify(err)); }
  });
});

若 onFail 返回 {"errorCode":"3","errorMessage":"invalid url domain"},按钉钉开放平台文档排查顺序是:该域名是否已加入应用「H5 可信域名」、corpId 是否与当前企业一致、页面实际 URL(含 ? 后参数)是否与签名时传入的 URL 完全一致——少一个 / 或参数顺序不同都会失败。

混合内容扫描。钉钉 iOS 端不会自动升级 http:// 子资源,一张 http 图片就能让 JSAPI 静默失效:在 DevTools Console 搜 Mixed Content,Network 面板过滤 http://;命令行可粗查源码:

# 粗查页面内硬编码的 http 资源
curl -s https://h5.example.com | grep -o 'http://[^"'"'"' ]*' | sort -u

发现后应改 https 或走同域反向代理,不要依赖浏览器自动升级。

续期与监控。据 Let’s Encrypt 文档,90 天证书应在到期前 30 天续期,先用 dry-run 验证钩子可用(certbot 2.x 默认 --deploy-hook 不执行除非显式声明):

# certbot 方案:模拟续期,不真正签发
certbot renew --dry-run

# acme.sh 方案:确认 cron 任务已安装并执行一次
acme.sh --cron -f
crontab -l | grep acme.sh

上线后建议用外部拨测每 5 分钟检查四项:443 端口可连、HTTP 状态码为 200、证书剩余天数 > 30、TLS 1.2 握手成功。钉钉 H5 https 要求的失效往往不是配置错,而是证书到期或被中间设备替换导致链断裂——拨测比事后排查便宜得多。

生产环境应按钉钉H5 https要求使用HTTPS。开发联调可以用http加内网调试,但Android 9+会拦截明文请求,JSAPI鉴权、免登、支付、文件等能力在非安全上下文下容易失败;上线验收建议页面、接口、静态资源全部https。

钉钉开放平台的可信域名通常按后台提示填写域名本身,例如 h5.example.com,不带协议和路径;应用首页地址和OAuth回调才填完整URL。可信域名必须与dd.config签名url的主域同源,否则会出现签名校验失败。

共同点是都要求受信任CA证书、TLS 1.2+、无混合内容;差异在JSAPI鉴权和可信域名配置流程。钉钉H5更依赖dd.config的当前页面URL签名和agentId/corpId,企业微信则使用wx.config和corpId/agentConfig,排查时不要混用签名算法和缓存key。

常见原因是证书链不完整、手机系统根证书旧、证书SAN不包含当前子域,或CDN节点返回了默认证书。用 openssl s_client -connect 域名:443 -servername 域名 -showcerts 对比电脑和手机网络下的chain,Nginx/Apache统一部署fullchain.pem。

不建议启用。据RFC 8996,TLS 1.0/1.1已被弃用;钉钉7.x常见WebView支持TLS 1.2/1.3。Nginx配置 ssl_protocols TLSv1.2 TLSv1.3 即可,若必须兼容很旧设备,再单独评估,但不要为兼容旧设备牺牲整体安全基线。

有关系但不全是证书问题。HTTPS配置错误会导致页面地址、跳转地址和签名url不一致;签名本身还要检查jsapi_ticket是否过期(7200秒)、timestamp偏差、noncestr、url是否含#后片段、可信域名是否配置。先保证https地址稳定,再逐项比对签名串。

至少跑四条:curl -I http://域名 看301;curl -I https://域名 看200和HSTS;openssl s_client -connect 域名:443 -servername 域名 -tls1_2


本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

长期从事 SSL/TLS 证书部署与 HTTPS 运维,负责本站证书选型、安装配置与故障排查内容的编写与审核。