网页授权域名白名单

一、网页授权域名白名单是什么

网页授权域名白名单是开放平台在OAuth2.0授权流程中实施的一项域名级安全校验机制。开发者在接入网页授权能力时，需要先将自己发起授权或接收授权回调的域名登记到平台后台。平台在收到授权请求时，会检查回调地址redirect_uri的域名是否与白名单一致，如果不一致则拒绝该授权请求。

该机制广泛存在于微信公众平台、微信开放平台、支付宝开放平台、QQ互联、微博开放平台等主流平台中。虽然不同平台的名称和配置细节有所差异，但核心逻辑相同：只有被加入白名单的网页授权域名，才允许使用对应应用的身份信息获取用户授权。

二、为什么需要网页授权域名白名单

网页授权域名白名单的核心作用是安全防护。通过白名单校验，平台可以防止攻击者冒用他人的AppID和AppSecret构造授权链接，将用户引导到仿冒页面；同时可以避免授权码code被非法第三方获取。网页授权成功后，应用可以获取用户授权范围内的身份信息，例如微信的openid、头像、昵称等，因此白名单是保护用户数据和平台安全的重要防线。

需要特别强调的是，网页授权域名白名单不是IP白名单。网页授权域名白名单校验的是授权回调URL中的域名；而IP白名单通常用于限制服务器端调用接口时使用的出口IP。两者属于不同安全层，不能混淆。

三、如何配置网页授权域名白名单

以微信公众平台为例，配置入口通常位于公众号后台的“网页授权域名”功能设置中，也可以在“开发-接口权限-网页授权获取用户基本信息”中进入修改页面。配置时需要填写一个可公开访问的域名，例如www.example.com。微信要求该域名不能带协议头，例如不能填写https://www.example.com，也不能带路径，例如不能填写https://www.example.com/oauth/callback。

填写域名后，平台会生成一个随机校验文件，常见形式为MP_verify_xxxxx.txt。开发者需要将该文件上传到域名根目录下，并确保通过公网可以访问，例如访问https://www.example.com/MP_verify_xxxxx.txt。平台校验通过后，该域名即被加入网页授权域名白名单。

部分平台要求填写完整的授权回调地址，而不是仅填写域名。例如支付宝开放平台、QQ互联通常要求配置完整的Callback URL，此时需要填写https://www.example.com/oauth/callback这类完整地址，且后续OAuth2.0请求中的redirect_uri必须与该地址完全匹配。

四、配置与使用中的注意事项

第一，redirect_uri中的域名必须与白名单中的域名完全匹配，包括子域名。白名单配置的是www.example.com，那么example.com或api.example.com均不能使用。第二，如果平台支持端口配置，回调地址中的端口也必须一致；白名单未包含端口时，默认使用80或443端口。第三，微信网页授权域名白名单只校验域名部分，不校验具体路径，因此回调地址可以放在该域名下的任意路径中。

在微信网页授权中，redirect_uri参数必须经过URL编码。完整授权链接通常形如：https://open.weixin.qq.com/connect/oauth2/authorize?appid=APPID&redirect_uri=REDIRECT_URI&response_type=code&scope=snsapi_userinfo&state=STATE#wechat_redirect。其中scope可以是snsapi_base或snsapi_userinfo，但无论使用哪种，redirect_uri的域名都必须位于白名单内。

另外，部分平台要求域名已完成ICP备案，或强制使用HTTPS。开发者应提前确认域名解析正常、备案状态有效，并保证域名验证文件可以长期访问，不能在上线后删除，否则可能影响后续授权校验。

五、常见错误与排查方法

常见的配置错误包括：域名中误加了http://或https://；填写了带路径的URL；域名填错；子域名与白名单不一致；使用内网IP或无法公网访问的域名；某些平台不支持使用裸IP作为网页授权域名。如果授权时出现“redirect_uri参数错误”或“当前网页不在域名白名单中”等提示，应优先检查后台白名单配置与当前请求中的redirect_uri是否一致。

如果修改白名单后仍然提示错误，还需要检查是否存在CDN缓存。验证文件和回调页面如果经过CDN，应确保缓存实时更新，否则平台服务器可能访问到旧的校验内容。对于微信第三方平台，还需要区分“授权发起页域名”和“授权回调域名”，这两个白名单分别约束授权入口页面和授权回调地址，不能混填。

六、安全建议

配置网页授权域名白名单后，开发者还应采取以下安全措施：授权回调地址应使用HTTPS加密传输；发起授权请求时应携带并校验state参数，以防护CSRF跨站请求伪造攻击；授权码code必须在服务器端换取access_token，不能将code暴露给前端页面或第三方；定期检查白名单配置，及时删除不再使用的域名或子域名。

综上，网页授权域名白名单是OAuth2.0网页授权安全链路中的基础配置。它把应用身份与回调域名进行绑定，从而降低授权码被劫持、用户被钓鱼的风险。开发者在配置时应当严格按照平台规范填写域名，并在实际请求中保持redirect_uri精确匹配，才能保证网页授权流程安全、稳定地运行。