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

定位常见认证失败问题

定位常见认证失败问题

认证失败不要先改拦截器或重发登录请求,而要按“请求携带 Token → Token 名称与读取位置 → 路由是否命中 → 登录状态是否有效 → 权限是否加载”的顺序逐层缩小范围。这样可以把看似相同的“未登录”或“无权限”,快速定位到具体一层。

学习目标

  • 能区分 Token 未携带、名称不一致、路由误拦截和会话失效
  • 能检查 StpInterface 是否真正为当前账号加载了权限
  • 能用最小日志与请求验证修复是否生效

按认证链路排查而不是猜原因

同一个受保护接口失败,根因可能发生在完全不同的位置。先确认请求里有没有凭证,再确认 Sa-Token 能否读取,随后检查拦截规则、会话状态和权限集合。前一层没有通过时,不要急着检查后一层。

Sa-Token 认证失败排查流程

Sa-Token 的 Token 名称可以通过配置调整,请求读取也可来自 header、cookie 等位置,因此客户端“带了一个 Token”并不等于框架“读到了正确的 Token”。([Sa-Token][1])

检查 Token 是否被框架读到

排障时不要打印完整 Token。可以临时记录请求路径、Token 名称、是否读取到值以及登录判断,并在问题解决后删除这段诊断日志。下面的片段示例适用于 Spring MVC 项目,并假设 /api/auth/login 是公开登录接口。

java
package com.example.auth;

import cn.dev33.satoken.context.SaHolder;
import cn.dev33.satoken.interceptor.SaInterceptor;
import cn.dev33.satoken.stp.StpUtil;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class SaTokenConfigure implements WebMvcConfigurer {

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new SaInterceptor(handle -> {
            String path = SaHolder.getRequest().getRequestPath();
            String tokenValue = StpUtil.getTokenValue();

            System.out.printf(
                    "auth path=%s tokenName=%s tokenPresent=%s isLogin=%s%n",
                    path,
                    StpUtil.getTokenName(),
                    tokenValue != null,
                    StpUtil.isLogin()
            );

            StpUtil.checkLogin();
        }))
        .addPathPatterns("/api/**")
        .excludePathPatterns("/api/auth/login");
    }
}

这段配置的生效行为是:访问 /api/** 时先输出最小诊断信息,再执行登录校验;登录接口被明确排除。Sa-Token 官方路由拦截方式同样通过 addPathPatterns 与 excludePathPatterns 控制命中范围。([GitHub][2])

假设项目配置的 Token 名称为 satoken,用一个已登录 Token 请求受保护接口:

bash
curl -i -H "satoken: <TOKEN>" "http://localhost:<PORT>/api/profile"

预期结果

text
HTTP/1.1 200

同时控制台应出现类似日志;若项目使用了自定义 Token 名称,tokenName 的实际值会不同。

text
auth path=/api/profile tokenName=satoken tokenPresent=true isLogin=true

如果 tokenPresent=false,优先检查前端实际发送的 header 或 cookie 名称、反向代理是否丢弃该头,以及前后端是否把 Authorization、satoken 等不同名称混用了。若 tokenPresent=true 但 isLogin=false,说明问题已经越过“请求未携带 Token”这一层,应转向会话状态。

检查路由是否误拦截或漏拦截

登录接口被包含在全局登录校验里,会出现“还没登录就无法调用登录接口”的死循环;受保护接口误写进排除列表,则可能绕过认证。检查 addPathPatterns、excludePathPatterns、SaRouter.match/notMatch 与 @SaIgnore 是否共同造成了意外结果。

排查时先缩小规则:只保留一条明确的受保护路径和一个明确的登录排除路径,验证正常后再逐步恢复通配规则。不要为了让请求“先通起来”而临时把大范围路径加入排除列表。

检查权限是否真的加载

登录成功不代表一定有权限。Sa-Token 在执行权限校验时,会通过 StpInterface 获取当前账号的权限集合;这个接口不是因为应用启动就自动调用,而是在鉴权发生时才参与。([Sa-Token][3])

遇到“明明登录却一直权限不足”,依次确认:StpInterface 实现类是否被 Spring 扫描;传入的 loginId 是否对应预期用户;loginType 是否属于正确账号体系;返回的权限码是否与 checkPermission 或注解中的字符串完全一致。最有效的诊断是临时记录 loginId 和权限码集合,而不是直接绕过权限校验。

区分会话过期、注销与踢下线

Token 能被读取但登录状态无效时,再检查有效期、活跃超时、主动注销以及被踢下线等状态。StpUtil.logout() 会注销会话;StpUtil.kickout(loginId) 用于踢人下线,官方文档说明二者的语义不同:踢下线会保留特定失效标记,以便后续请求识别“被踢”状态。([GitHub][4])

因此,排障记录应同时包含“Token 是否存在”和“登录为何失效”。如果应用有统一异常处理,建议把未携带、已过期、已注销、被踢下线映射成稳定的业务错误码,前端和接口测试就不必依赖异常文案。

修复后按原失败请求重新验证:先确认 Token 被读到,再确认受保护路由命中,最后确认 isLogin=true 且权限集合包含目标权限。只要这条证据链完整,认证问题就不再需要靠反复试配置定位。

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

目录与阅读设置

阅读设置

17

记录一个想法

定位常见认证失败问题

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

登录哪都通