身份认证与应用安全 / 系统课时
用日志定位认证失败请求
用日志定位认证失败请求
认证失败如果只留下一个 401 或 403,很难判断问题发生在登录、Token 校验、刷新还是权限判断。本节建立最小但可检索的认证日志,让同一次请求通过 traceId 串联起来,同时避免把密码、完整 JWT 或刷新令牌写入日志。
学习目标
- 为登录失败、Token 拒绝、刷新失败和权限拒绝设计可检索的日志字段
- 用 traceId 把入口请求与认证链路中的失败事件关联起来
- 区分 401 与 403 的定位方向,并避免日志泄露认证秘密
先设计可检索的日志字段
认证日志应回答“哪次请求、在哪个阶段、为什么失败”,而不是把上下文全部倾倒出来。推荐至少保留 event、traceId、reason、HTTP 方法、请求路径和结果状态;只有在已经完成身份验证且符合隐私规范时,才记录内部用户标识。
四类事件可以统一命名,例如 LOGIN_FAILURE、TOKEN_REJECTED、REFRESH_REJECTED、ACCESS_DENIED。reason 使用稳定枚举,如 BAD_CREDENTIALS、EXPIRED、INVALID_SIGNATURE、MISSING_AUTHORITY,不要直接把异常堆栈当作业务字段。

用 traceId 串起一次请求
下面是 Spring Boot 3+ 的片段示例。过滤器优先接受格式受限的 X-Request-Id,否则生成新的 UUID;无论请求成功还是异常,都在 finally 中清理 MDC,避免线程复用时把上一请求的标识带到下一请求。
import java.io.IOException;
import java.util.UUID;
import java.util.regex.Pattern;
import org.slf4j.MDC;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
@Component
public class RequestTraceFilter extends OncePerRequestFilter {
private static final Pattern SAFE_ID =
Pattern.compile("[A-Za-z0-9._-]{1,64}");
@Override
protected void doFilterInternal(
HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain) throws ServletException, IOException {
String supplied = request.getHeader("X-Request-Id");
String traceId = supplied != null && SAFE_ID.matcher(supplied).matches()
? supplied
: UUID.randomUUID().toString();
MDC.put("traceId", traceId);
response.setHeader("X-Request-Id", traceId);
try {
filterChain.doFilter(request, response);
} finally {
MDC.remove("traceId");
}
}
}生效后,登录处理器、JWT 校验异常处理器、刷新接口和 AccessDeniedHandler 都可以通过 MDC.get("traceId") 取得同一标识。验证时发送任意请求,检查响应头是否包含 X-Request-Id,再确认相应日志事件携带相同值。
在四个失败点记录原因
日志位置要靠近“决定失败”的地方,而不是统一在最外层捕获所有异常。登录失败记录认证结果和稳定原因;Token 校验失败区分过期、签名错误、格式错误;刷新失败区分刷新令牌过期、撤销或找不到会话;权限拒绝则记录已认证主体和缺失权限。
下面是片段示例,展示 Token 被拒绝时的安全日志格式。它只记录失败原因和请求元数据,不记录 Authorization 头。
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;
import org.springframework.stereotype.Component;
import jakarta.servlet.http.HttpServletRequest;
@Component
public class AuthFailureAudit {
private static final Logger log =
LoggerFactory.getLogger(AuthFailureAudit.class);
public void tokenRejected(HttpServletRequest request, String reason) {
log.warn(
"auth event=TOKEN_REJECTED traceId={} reason={} method={} path={}",
MDC.get("traceId"),
reason,
request.getMethod(),
request.getRequestURI());
}
}预期日志形态如下,<TIME> 与 <ID> 会因实际请求变化:
<TIME> WARN auth event=TOKEN_REJECTED traceId=<ID> reason=EXPIRED method=GET path=/api/ordersreason 最好由异常类型映射成有限集合,不要直接写 exception.getMessage()。第三方库的异常消息可能随版本变化,也可能包含未经清洗的输入,既不利于检索,也可能造成日志注入或敏感信息泄露。
从一条 401 反查认证链路
定位时先拿到客户端响应里的 X-Request-Id,再按相同 traceId 搜索日志。若看到 TOKEN_REJECTED reason=EXPIRED,应继续检查服务器时间、Token 到期边界与刷新时机;若是 INVALID_SIGNATURE,则转向密钥、算法和签发方配置。
401 通常表示当前请求没有形成可接受的认证身份,例如 Token 缺失、过期或校验失败;403 则更常见于身份已经建立,但缺少访问目标资源所需的权限。排查 403 时应优先查看权限映射、角色前缀和授权规则,而不是反复检查密码。
同一 traceId 下如果先出现刷新失败,随后又出现旧 Access Token 的 401,说明客户端可能在刷新失败后仍继续重试旧凭证。日志的价值就在于把这些原本分散的事件还原成一条请求链,而不是只统计状态码数量。
不要记录这些内容
认证日志至少应排除完整 Authorization 请求头、Access Token、Refresh Token、密码、客户端密钥、私钥和签名密钥。即使为了排障临时提高日志级别,也不要让这些值进入集中日志系统。
若确实需要关联某个 Token 的多次失败,优先使用服务端已有的会话 ID 或可信的内部标识;不要直接记录未经验证的 JWT Claim,因为它们可能由攻击者构造。对已认证用户的标识也应遵守业务的隐私与保留策略。
一套有效的认证日志不需要很多字段:稳定事件名、traceId、失败原因、请求位置和最终状态已经能覆盖大部分排障场景。把这些字段放在真正做出认证或授权决定的位置,并始终排除秘密凭证,就能同时提升可定位性和日志安全性。