身份认证与应用安全 / 系统课时

用日志定位认证失败请求

用日志定位认证失败请求

认证失败如果只留下一个 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,避免线程复用时把上一请求的标识带到下一请求。

java
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 头。

java
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> 会因实际请求变化:

text
<TIME> WARN auth event=TOKEN_REJECTED traceId=<ID> reason=EXPIRED method=GET path=/api/orders

reason 最好由异常类型映射成有限集合,不要直接写 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、失败原因、请求位置和最终状态已经能覆盖大部分排障场景。把这些字段放在真正做出认证或授权决定的位置,并始终排除秘密凭证,就能同时提升可定位性和日志安全性。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用日志定位认证失败请求

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通