身份认证与应用安全 / 系统课时
配置跨域与认证请求头
配置跨域与认证请求头
前后端分离时,登录成功并不代表后续鉴权一定能到达后端:浏览器会先按 CORS 规则检查跨域请求,自定义 Token 请求头还可能触发预检。本篇用 Spring MVC 全局配置把允许源、预检和 Sa-Token 请求头一次配置清楚,并给出可复现的验证方法。
学习目标
- 理解预检请求与真实鉴权请求的先后关系
- 配置允许的前端来源、HTTP 方法和 Sa-Token 请求头
- 用预检结果区分 CORS 故障与 Token 鉴权故障
为什么认证请求会先出现 OPTIONS
Sa-Token 的 token-name 默认是 satoken,框架可使用这个名称从请求 Header 中读取 Token;如果修改了 sa-token.token-name,前端发送的请求头名称和 CORS 允许列表也应同步修改。([GitHub][1])
当前端跨域发送 satoken 这类自定义请求头,或者以 application/json 等方式发起非简单请求时,浏览器通常会先发送 OPTIONS 预检。预检携带目标方法和计划使用的请求头,服务端只有明确允许后,浏览器才继续发送真正的登录后接口请求。Spring MVC 会根据已声明的 CORS 配置处理预检请求。([Home][2])

因此,浏览器报 CORS 错误而后端业务日志完全没有真实请求时,应先检查预检,不要立即怀疑 Sa-Token 登录状态。
用 Spring MVC 集中配置 CORS
对于统一由 /api/** 提供接口的 Spring MVC 项目,可以集中声明允许的来源、方法和请求头。下面是片段示例,需要放入已有 Spring Boot Web 应用,并将前端地址替换为实际地址。
package com.example.auth.config;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class CorsConfig implements WebMvcConfigurer {
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/api/**")
// 生产环境应填写明确的可信前端来源。
.allowedOrigins("http://localhost:5173")
.allowedMethods("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS")
.allowedHeaders("Content-Type", "satoken")
// 只有前端需要读取响应头中的 Token 时才需要暴露它。
.exposedHeaders("satoken")
.allowCredentials(false)
.maxAge(3600);
}
}这段配置的生效行为是:来自 http://localhost:5173、匹配 /api/** 的跨域请求可以使用列出的 HTTP 方法,并允许浏览器发送 Content-Type 和 satoken 请求头。如果项目把 token-name 改成了 Authorization 等名称,这里的 allowedHeaders 与 exposedHeaders 也要对应调整。
Header Token 模式通常不依赖浏览器自动携带 Cookie,因此示例使用 allowCredentials(false)。如果项目确实采用跨域 Cookie,则需要按实际需求启用凭据,同时将允许来源配置为明确域名;Spring 文档明确指出启用凭据时不能把 allowedOrigins 配成通配符 *。([Home][2])
先验证预检再检查鉴权
选择项目中一个真实存在、位于 /api/** 下的接口,将 <PORT> 和 <PATH> 替换成实际值。先只模拟浏览器的预检请求:
curl -i -X OPTIONS "http://localhost:<PORT>/api/<PATH>" \
-H "Origin: http://localhost:5173" \
-H "Access-Control-Request-Method: GET" \
-H "Access-Control-Request-Headers: satoken"预期输出:关键响应信息应包含允许当前前端来源和 satoken 请求头;响应头顺序可能不同。
HTTP/1.1 200
Access-Control-Allow-Origin: http://localhost:5173
Access-Control-Allow-Headers: satoken预检通过后,再让前端发送真实请求并携带有效 Token。此时如果接口返回未登录或无权限,说明请求已经越过 CORS,应转向检查 Token 值、Token 名称和 Sa-Token 鉴权规则,而不是继续修改跨域配置。
按现象定位常见阻断点
如果预检响应没有 Access-Control-Allow-Origin,优先检查前端的协议、主机和端口是否与 allowedOrigins 完全匹配。如果提示 satoken 请求头不被允许,则检查 allowedHeaders 与实际 Token 名称是否一致。
如果 OPTIONS 本身就得到认证层的 401 或 403,说明 MVC CORS 之前的网关、自定义 Servlet Filter 或其他安全过滤链可能已经拦截预检,应让该层正确处理或放行预检,而不是要求浏览器给 OPTIONS 附带登录 Token。
把预检和真实请求分开验证后,排查路径会很清晰:预检失败先修 CORS;预检成功但真实请求鉴权失败,再检查 Sa-Token。