认证配置
认证配置
1 功能简介
统一访问认证（Access 模式） 给所有被 WAF 代理的站点加一道统一的准入门槛：开启后，访问任何站点都要先在认证中心登录一次；登录成功后，访问其余站点无需再登。
出发点是很多自建的开源服务本身没有安全保障，直接暴露在公网上风险很高。有了这道门槛，只有你放行的账号才能碰到后端服务。
本页配置的是开启后的行为细节。完整用起来需要三件事：
- 在 访问账号 里建好账号
- 在本页指定 认证中心域名
- 打开本页顶部的 总开关
注意
这三步的顺序不要颠倒。总开关一开，所有受保护站点立刻要求登录——如果还没建账号，谁都进不去。
2 总开关
页面顶部是 统一访问认证总开关，可直接在这里开关，改动立即生效，无需保存。
页面提示：关闭时下面的配置全部不生效。建议先建好【访问账号】、配好认证中心域名，再打开。改动立即生效，无需保存。
- 打开 时会弹出确认框：开启后，所有受保护的站点都会要求先登录。请确认已经在【访问账号】里建好了账号，否则谁也进不去。 若此时还没指定认证中心域名，确认框里会额外出现红色提示——没有认证中心就没有登录入口，功能不会真正生效（引擎会放行并记告警日志）。
- 关闭 不需要确认，立即生效。
开关旁边的 去建访问账号 按钮可直接跳到账号页。
提示
这个开关对应系统配置 access 分类下的 access_enable，默认关闭。在 系统配置 里改效果相同。
3 基础设置
3.1 认证中心域名（必填）
指定一个域名专门用来登录：访问任何受保护站点时都会先跳到它，登录一次即可畅通访问全部站点。
下拉里列出的是已经配好且已启动的站点（不含全局网站与泛域名），选一个即可，http/https 和端口都已拼好，不用自己拼。下拉里没有想要的地址时也支持直接输入。
注意
认证中心必须是一个 WAF 正在代理的域名。如果请求根本进不到引擎，跳过去就是一个 403 死循环。保存时会校验这一点。
两种用法都可以：
- 复用某个业务站点的域名 —— 不用额外准备域名，该站点既正常反代业务，也承担登录职责。
- 单独加一个站点 —— 在 网站维护 里加一个如
sso.example.com的站点专门用来登录。
若当前没有可用站点，下拉下方会提示先去 网站维护 添加一个已启动的站点。
注意
认证中心所在的站点不能删除，也不能改掉域名——那等于所有站点同时失去登录入口。尝试删除或改域名时会被拦下，提示先到本页改用其它域名。
3.2 登录有效期
登录一次能保持多久，到期后需要重新登录。默认 720 分钟（12 小时）。
3.3 全局二次验证
开启后，已绑定动态口令的账号登录时需要额外输入 6 位动态码。未绑定的账号不受影响（不会被锁死在登录页）。
站点与账号可以单独覆盖本项，优先级：账号级 > 站点级 > 全局。
3.4 登录失败锁定
连续失败 N 次后锁定 M 分钟。按来源 IP 与账号名两个维度分别计数，任一超限即锁定——两个维度都记是为了同时挡住撞库和针对单账号的分布式爆破。
3.5 全局免认证路径
对所有站点生效，按路径段匹配，一行一条。用于健康检查、webhook 回调等无法登录的调用方。
填 /api 会放行 /api、/api/ 以及 /api/ 下的所有子路径，但不会放行 /apixxx。结尾写不写斜杠效果一样。
提示
放行的是一棵子树，不是所有同前缀的路径——填 /health 不会顺带放行 /healthz。 证书校验路径 /.well-known/acme-challenge/ 已内置放行，无需填写，否则证书续期会失败。
3.6 全局免认证IP组
命中该 IP组 的来源在所有站点上都直接放行。站点可单独指定自己的 IP 组，站点设置优先。
4 高级设置
默认值对绝大多数场景都是合适的，改错了容易把自己挡在外面。
4.1 路径与 Cookie
| 字段 | 说明 |
|---|---|
| 认证路径前缀 | 登录页与认证接口挂载的路径，默认 /samwaf_access。可改成不易猜测的值以隐藏系统特征。即使功能关闭，该前缀也不会转发给后端，若后端确有同名路径请修改此项 |
| Cookie 前缀 | 会话 Cookie 的名称前缀，默认 samwaf_ac。这些 Cookie 在转发给后端前会被自动剥离，后端看不到 |
| Cookie Secure 属性 | 自动判断：HTTPS 请求或站点开启了强制跳转 HTTPS 时才加 Secure；强制开启：全站已是 HTTPS 时可选 |
| 跳转签名密钥 | 用于给跨域跳转请求签名，防止回跳地址被篡改。首次保存配置时自动生成，不会回显，只显示「已设置 / 未设置」 |
注意
纯 HTTP 站点把 Cookie Secure 强制开启后，浏览器不会保存 Cookie，会导致无法登录。
点击 轮换密钥 可更换签名密钥。轮换后所有正在进行中的登录跳转会失效（用户重新跳转一次即可），已登录的会话不受影响。
4.2 有效期精调
| 字段 | 说明 |
|---|---|
| 站点令牌有效期 | 各业务域名上的登录状态有效期，实际取值不会超过中心会话的剩余时间 |
| 跳转票据有效期 | 跨域跳转用的一次性票据，够一次 302 往返即可，最大 300 秒 |
| 空闲超时 | 多久没有活动就自动退出登录，0 表示不启用 |
| 认证结果缓存 | 认证结果的缓存时长，同时也是 踢下线 的最坏生效延迟。上限 60 秒，不建议调大 |
4.3 会话绑定
| 字段 | 说明 |
|---|---|
| 绑定登录IP | 开启后换 IP 立即失效，安全性更高。但移动网络切换、多出口线路会导致频繁掉线 |
| 绑定设备指纹 | 按浏览器 UA 与语言等特征绑定，换浏览器或浏览器升级后需重新登录 |
4.4 免认证旁路
供 webhook、监控等机器调用方免登录访问：
- 服务令牌请求头 —— 填写请求头名称，例如
X-Service-Token。 - 服务令牌 —— 一行一个明文令牌。后端只保存 SHA256，不会回显。
留空表示保持原有令牌不变；填写单个减号 - 表示清空全部令牌。
4.5 未认证行为
| 字段 | 说明 |
|---|---|
| 未认证响应方式 | 自动判断（推荐）：浏览器导航跳登录页，API/WebSocket 返回 401 JSON；一律跳转：强制 302；一律401：全部返回 JSON，适合纯接口站点 |
| 透传身份到后端 | 开启后向后端转发请求时附加 X-SamWaf-Access-User 头，后端可据此识别当前访客。客户端自带的同名头会先被删除，无法伪造 |
提示
WebSocket 在任何设置下都返回 401，因为它不跟随重定向。
5 站点级例外
每个站点可以在 网站维护 的 统一访问认证 标签里单独设置：继承全局 / 强制开启 / 强制关闭，以及本站点专属的免认证路径、免认证 IP 组、二次验证与未认证响应方式。
6 通知
统一访问认证的事件可以推送到 通知渠道。在 通知订阅 里有两个独立的消息类型：
| 消息类型 | 触发事件 |
|---|---|
| 统一认证登录 | 登录成功 |
| 统一认证异常 | 触发锁定、票据重放、回跳地址异常 |
通知正文包含事件、账号、来源 IP、归属地、访问域名与时间。
提示
拆成两类是有意的：只想收安全告警的人不会被每一次正常登录打扰。 高频事件（如未认证被拦、单次密码错误）不会发通知，同一「事件 + IP」5 分钟内也只发一条，避免被扫描时刷屏。
7 万一把自己锁在外面
注意
配置失误可能把整站锁死，请先了解恢复手段再开启。
| 场景 | 恢复手段 |
|---|---|
| 管理端未反代进 WAF（默认情况） | 管理端 26666 端口不经过 WAF 引擎，本功能锁不住它。直接进管理端把总开关关掉即可 |
| 管理端也被反代进了 WAF 且配错 | 编辑 conf/config.yml，把 security.access_force_disable 改成 true 后重启 |
| 容器环境 | 设置环境变量 SAMWAF_ACCESS_DISABLE=1 后重启 |
8 字段说明
| 字段 | 说明 |
|---|---|
| 统一访问认证总开关 | 功能总开关，对应系统配置 access_enable，默认关闭；改动立即生效 |
| 认证中心域名 | 专门用于登录的域名，必填；必须是已配置且已启动的站点 |
| 登录有效期 | 一次登录的保持时长，默认 720 分钟 |
| 全局二次验证 | 是否要求已绑定动态口令的账号输入动态码 |
| 登录失败锁定 | 失败 N 次后锁定 M 分钟，按 IP 与账号名双维度计数 |
| 全局免认证路径 | 对所有站点生效的免认证路径前缀，一行一条 |
| 全局免认证IP组 | 命中即在所有站点放行的 IP 组 |
| 认证路径前缀 | 登录页与认证接口的挂载路径，默认 /samwaf_access |
| Cookie 前缀 | 会话 Cookie 名称前缀，默认 samwaf_ac |
| Cookie Secure 属性 | 自动判断 / 强制开启 |
| 跳转签名密钥 | 跨域跳转的防篡改签名密钥，自动生成、不回显，可轮换 |
| 站点令牌有效期 | 各业务域名上登录状态的有效期 |
| 跳转票据有效期 | 跨域跳转一次性票据的有效期，最大 300 秒 |
| 空闲超时 | 无活动自动退出的时长，0 为不启用 |
| 认证结果缓存 | 认证结果缓存时长，上限 60 秒 |
| 绑定登录IP | 换 IP 后会话是否立即失效 |
| 绑定设备指纹 | 换浏览器后会话是否立即失效 |
| 服务令牌请求头 | 机器调用方携带令牌所用的请求头名称 |
| 服务令牌 | 明文令牌（一行一个），仅存 SHA256；留空不变，- 清空 |
| 未认证响应方式 | 自动判断 / 一律跳转 / 一律401 |
| 透传身份到后端 | 是否向后端附加 X-SamWaf-Access-User |
9 常见问题
开了总开关，站点却照样不用登录？ 多半是没指定认证中心域名。没有认证中心就没有登录入口，引擎此时选择放行并记录告警日志（拦下来的话所有站点会同时 403 且无处可登）。到本页选好认证中心域名并保存即可。
跳到认证中心后一直 403？ 认证中心域名不是 WAF 正在代理的站点，请求进不到引擎。到 网站维护 确认该域名已配置为站点且已启动。
登录成功但马上又要登录？ 检查是不是纯 HTTP 站点却把 Cookie Secure 属性 设成了强制开启——浏览器不会保存 Secure Cookie，登录状态种不上。改回「自动判断」。
证书续期失败了？ 确认
/.well-known/acme-challenge/能被访问。该路径已内置放行、不需要写进免认证路径；若把认证路径前缀改成了与它重叠的值，保存时会被拒绝。和站点的 网站密码访问 有什么区别？ 网站密码访问是按站点的，账号挂在站点下，访问第二个站点还要再登一次；统一访问认证是全局的，登录一次通行所有站点。两者可以并存，同时开启时先过统一访问认证。