企业微信可信域名是应用调用网页授权和JS-SDK能力前必须配置的一类安全边界。很多集成问题并不是代码写错，而是域名没有被纳管到可信域名范围，导致OAuth2.0回调被拒绝或JS-SDK签名校验失败。理解可信域名包含的范围，比单纯填写一个主域名更重要。
一、企业微信可信域名具体指哪些？
在企业微信管理后台的同一个配置项中，可信域名并不区分OAuth2.0授权回调域名和JS-SDK可信域名，而是作为统一白名单同时作用于两类场景。第一类是企业微信OAuth2.0网页授权回调，当用户在企业微信内打开应用页面，需要跳转到已登记域名下的地址获取身份信息，redirect_uri 必须落在可信域名范围内。第二类是页面调用企业微信JS-SDK，例如获取地理位置、调起扫一扫、分享到微信等，当前网页URL的域名部分也必须与可信域名匹配。
可信域名还可以进一步从形态上区分主域名和子域名。假设 ippipp.com 是已备案主域，企业微信不会因为 ippipp.com 已通过校验就自动信任 a.ippipp.com。如果业务页面部署在子域名上，必须把 a.ippipp.com 单独加入可信域名列表。另外，可信域名不允许使用 IP 地址、localhost，也不能带协议头和端口号，只能填写纯域名。
从应用维度看，每一个自建应用或代开发应用都有独立的可信域名配置。即使同一企业在企业微信中有多个应用，A应用配置了 www.ippipp.com，B应用也不会继承这个设置。因此需要按应用分别维护域名白名单，避免在新增应用时遗漏。
二、可信域名的配置步骤与验证机制
配置入口在企业微信管理后台的“应用管理”中，选择目标应用后进入“网页授权及JS-SDK”区域。点击设置可信域名后，可以同时填写一个或多个域名，多个域名通常以换行或逗号分隔。填写完成后系统会生成一个校验文件，例如 WW_verify_AbCdEf123456.txt，文件内容是平台给出的一串随机字符。
开发者需要把这个校验文件上传到域名根目录，并确保通过 HTTP 协议能够直接访问，例如 http://www.ippipp.com/WW_verify_AbCdEf123456.txt。企业微信服务器会请求这个地址来确认域名归属。如果服务器配置了强制 HTTPS 跳转，需要保留 HTTP 访问或对校验路径做例外处理，否则可能出现“验证文件访问失败”。验证通过后配置才会生效，后续修改域名时同样需要重新验证。
# 将企业微信校验文件放到站点根目录后，可由Nginx直接返回
location = /WW_verify_AbCdEf123456.txt {
return 200 "AbCdEf123456";
add_header Content-Type text/plain;
}
在实际环境中，很多团队会把该文件提交到前端静态资源目录里。要特别注意文件内容不能被压缩、改行或增加HTML包裹，必须以纯文本原样返回。除了 HTTP 可访问，域名本身还需要完成 ICP 备案，未备案域名即使文件访问正常，也可能在企业微信侧无法通过应用审核或校验。
配置完成后，网页授权的 redirect_uri 可以使用可信域名下的任意路径，例如 https://www.ippipp.com/callback。但构造 OAuth2.0 链接时，redirect_uri 必须进行 URL 编码，并且不能携带自定义端口。示例链接如下：
String redirectUri = URLEncoder.encode("https://www.ippipp.com/callback", "UTF-8");
String oauthUrl = "https://open.weixin.qq.com/connect/oauth2/authorize"
+ "?appid=" + corpId
+ "&redirect_uri=" + redirectUri
+ "&response_type=code"
+ "&scope=snsapi_base"
+ "&state=STATE#wechat_redirect";
三、如何保障企业微信可信域名安全？
可信域名本身就是一道回调防篡改边界。OAuth2.0 授权码会通过 redirect_uri 返回给业务服务器，如果允许任意地址接收回调，攻击者可以诱导用户访问恶意链接并把授权码发送到自己的服务器。企业微信通过只允许可信域名下的地址作为回调目标，能显著降低授权码泄露风险。因此开发者在选择可信域名时，应优先使用业务专用的独立域名，避免把内容管理系统、论坛、测试环境等易被上传恶意文件的站点作为统一域名。
第二层保障是强制 HTTPS。虽然配置可信域名时填写的是纯域名，但业务页面和回调地址都应使用 HTTPS。企业微信 JS-SDK 在非 HTTPS 页面中通常会直接拒绝调用或签名失败，因为页面内容可能被运营商或中间人注入脚本。同时 HTTPS 能保护 OAuth2.0 回调阶段的 code 和 access_token 不被明文嗅探。证书应覆盖所有子域名或逐个子域名配置，避免出现证书不匹配。
第三层保障是结合企业微信的“企业可信IP”与 JS-SDK 签名机制。应用获取 access_token 时，企业微信会校验请求来源 IP 是否在配置的可信 IP 列表中，这可以防止密钥泄露后被外部服务器调用。JS-SDK 签名则由后端使用 jsapi_ticket、随机串、时间戳和当前页面完整 URL 生成，前端不能直接持有 ticket。签名 URL 要与地址栏中的 URL 完全一致，不能混入 hash 部分，也不能通过前端字符串拼接生成。
import hashlib
import time
import uuid
def generate_js_sign(jsapi_ticket: str, url: str) -> dict:
noncestr = uuid.uuid4().hex
timestamp = int(time.time())
raw = f"jsapi_ticket={jsapi_ticket}&noncestr={noncestr}×tamp={timestamp}&url={url}"
signature = hashlib.sha1(raw.encode("utf-8")).hexdigest()
return {
"appId": "corp_id",
"timestamp": timestamp,
"nonceStr": noncestr,
"signature": signature,
}
第四层是运维层面的最小权限原则。不要为了省事直接填写企业根域名或泛域名，避免一个小的测试子域被攻破后影响整个应用。可信域名列表应定期盘点，下线的活动页面、废弃的测试域名要及时移除。如果企业存在多个应用，建议为每个应用配置独立二级域名，并在服务器上按应用隔离，避免单点故障。
四、常见问题与注意事项
最常见的问题是校验文件无法通过验证。出现这种情况时，先不要反复点击验证按钮，应检查文件是否放在域名根目录、文件名是否完全一致、服务器是否正确返回文件内容。部分反向代理会把不存在的 .txt 文件转发到前端首页，导致看起来能访问但内容不对，企业微信会校验失败。解决方式是在 Nginx、网关或 CDN 上显式放行该校验路径。
第二个高频问题是 redirect_uri 参数错误。这类错误通常由三个原因引起：可信域名配置的是 www.ippipp.com，但回调地址写成了 ippipp.com；回调地址带上了非 80 或 443 端口；redirect_uri 没有做 URL 编码，链接被截断或解析错误。开发时应把回调地址定义为统一配置项，由后端拼接 OAuth2.0 链接，避免前端硬编码。
第三个问题是子域名和主域名混淆。企业微信不会自动信任主域名下的所有子域名，需要逐个添加。对于使用多环境部署的团队，生产环境、预发布环境和测试环境如果使用不同子域名，则必须分别配置。测试环境若使用 IP 或 localhost，则不能用企业微信标准 OAuth 流程，需要准备正式域名并启用内网映射工具，但域名必须已经完成备案并通过归属验证。
另外，JS-SDK 报 invalid signature 时，可以优先核查签名 URL 和当前页面 URL 是否逐字符一致。常见差异包括 URL 中多了末尾斜杠、经过服务端归一化、SPA 路由被改写、页面 URL 中包含 query 参数但签名时未携带。处理时应把签名 URL 的获取放到服务端，基于请求头中的完整 URL 或前端实际地址生成，但要注意防止 URL 被代理重写。