跳到主要内容

安全组件 (yudao-spring-boot-starter-security)

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 组件详解
  6. 依赖关系分析
  7. 性能与安全特性
  8. 故障排查指南
  9. 结论
  10. 附录

简介​

本文件面向 yudao-spring-boot-starter-security 安全组件，系统性阐述其与 Spring Security 的集成方式、JWT 令牌认证机制、权限控制策略与上下文设计。重点覆盖以下方面：

  • Spring Security 配置与过滤链
  • JWT 令牌校验与登录用户上下文(LoginUser)注入
  • 密码加密策略与认证入口
  • 权限注解与数据权限控制
  • 自定义认证过滤器、权限拦截器与访问控制清单
  • 最佳实践：密码加密、令牌刷新、权限缓存与安全配置

项目结构​

该安全组件位于 yudao-framework 子模块中，围绕 Spring Security 自动配置、Web 安全适配器、令牌过滤器、上下文工具与权限服务展开；同时配合网关与报表模块的令牌透传与上下文注入。

Mermaid Diagram Code:

graph TB
subgraph "安全核心"
A["YudaoSecurityAutoConfiguration<br/>自动配置与Bean注册"]
B["YudaoWebSecurityConfigurerAdapter<br/>SecurityFilterChain配置"]
C["TokenAuthenticationFilter<br/>请求级令牌校验与上下文注入"]
D["LoginUser<br/>登录用户上下文模型"]
E["SecurityFrameworkUtils<br/>上下文工具"]
F["SecurityProperties<br/>安全配置属性"]
end
subgraph "权限与注解"
G["SecurityFrameworkServiceImpl<br/>权限/角色缓存服务"]
H["DataPermissionContextHolder<br/>数据权限上下文"]
I["DataPermissionAnnotationAdvisor<br/>注解切面"]
J["DataPermissionAnnotationInterceptor<br/>注解拦截器"]
end
subgraph "网关与外部集成"
K["Gateway TokenAuthenticationFilter<br/>网关令牌透传"]
L["Gateway SecurityFrameworkUtils<br/>网关上下文工具"]
M["JmReportTokenServiceImpl<br/>报表模块令牌注入"]
end
A --> B
B --> C
C --> E
C --> F
C --> G
G --> H
H --> I
I --> J
K --> L
M --> E

图表来源

章节来源

核心组件​

  • 自动配置与Bean注册：负责认证入口、权限不足处理器、密码编码器、SecurityContextHolder策略等。
  • Web安全适配器：定义 SecurityFilterChain，禁用CSRF与Session，配置异常处理、URL放行规则与自定义权限映射。
  • 令牌认证过滤器：从请求头或参数提取令牌，调用系统令牌API校验，构建 LoginUser 并注入上下文；支持模拟登录。
  • 登录用户上下文：承载用户标识、用户类型、租户、授权范围、过期时间与临时上下文。
  • 上下文工具：统一从请求中提取令牌、设置/移除登录用户、构造认证对象。
  • 权限服务：封装权限/角色查询与缓存，提升鉴权性能。
  • 数据权限注解体系：通过上下文与拦截器在方法执行前后维护注解上下文，实现数据维度的权限控制。
  • 网关与报表集成：网关侧透传登录用户信息，报表侧基于前端令牌注入上下文。

章节来源

架构总览​

整体采用“请求级令牌校验 + 上下文注入 + 方法级权限注解 + 数据权限注解”的分层安全架构。请求进入后，先由令牌过滤器完成令牌校验与上下文设置；随后业务层通过注解与权限服务进行细粒度控制。

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant Gateway as "网关/服务"
participant Sec as "Spring Security过滤链"
participant Filter as "TokenAuthenticationFilter"
participant OAuth2 as "系统令牌API"
participant Ctx as "SecurityFrameworkUtils"
participant Biz as "业务接口"
Client->>Gateway : "携带Authorization/Token请求"
Gateway->>Sec : "进入SecurityFilterChain"
Sec->>Filter : "前置过滤器执行"
Filter->>Ctx : "提取令牌"
alt "存在令牌"
Filter->>OAuth2 : "checkAccessToken(token)"
OAuth2-->>Filter : "返回用户信息/过期时间"
Filter->>Ctx : "setLoginUser(LoginUser)"
else "不存在令牌"
Filter-->>Sec : "跳过上下文设置"
end
Sec-->>Biz : "放行至业务接口"
Biz-->>Client : "返回响应"

图表来源

组件详解​

Spring Security 集成与配置​

  • 自动配置：注册认证入口、权限不足处理器、密码编码器、SecurityContextHolder 策略，确保线程本地上下文可跨线程传递。
  • Web 安全适配器：禁用 CSRF 与 Session，开启 CORS；统一异常处理；基于注解与配置项收集免登录 URL；最后统一要求认证。
  • 方法级安全：启用 securedEnabled，结合注解实现细粒度权限控制。

Mermaid Diagram Code:

classDiagram
class YudaoSecurityAutoConfiguration {
+authenticationEntryPoint()
+accessDeniedHandler()
+passwordEncoder()
+securityContextHolderMethodInvokingFactoryBean()
}
class YudaoWebSecurityConfigurerAdapter {
+authenticationManagerBean()
+filterChain(httpSecurity)
-getPermitAllUrlsFromAnnotations()
}
class SecurityProperties {
+tokenHeader
+tokenParameter
+mockEnable
+mockSecret
+permitAllUrls
+passwordEncoderLength
}
YudaoSecurityAutoConfiguration --> SecurityProperties : "读取配置"
YudaoWebSecurityConfigurerAdapter --> SecurityProperties : "读取配置"

图表来源

章节来源

JWT 令牌认证机制​

  • 令牌来源：优先从请求头 Authorization 中提取，其次从 token 参数中提取；网关与报表模块另有透传与注入逻辑。
  • 校验流程：调用系统令牌 API 校验令牌有效性，若有效则构建 LoginUser（包含用户ID、用户类型、租户ID、授权范围、过期时间），否则返回空（允许放行至业务自行判断）。
  • 用户类型匹配：当请求中带有用户类型时，需与令牌中的用户类型一致，否则拒绝访问。
  • 模拟登录：在开发模式下，可通过特定前缀+用户ID的令牌进行模拟登录，便于调试。

Mermaid Diagram Code:

flowchart TD
Start(["进入过滤器"]) --> HasHeader["尝试从Header获取login-user"]
HasHeader --> FoundHeader{"存在?"}
FoundHeader --> |是| ParseHeader["解析Header中的LoginUser"]
FoundHeader --> |否| ExtractToken["从Header/参数提取令牌"]
ExtractToken --> HasToken{"存在令牌?"}
HasToken --> |否| Continue["继续过滤链"]
HasToken --> |是| CheckToken["调用checkAccessToken校验"]
CheckToken --> Valid{"校验通过?"}
Valid --> |否| AllowNull["返回null(放行)"]
Valid --> |是| MatchType{"用户类型匹配?"}
MatchType --> |否| Deny["抛出拒绝访问"]
MatchType --> |是| BuildUser["构建LoginUser并注入上下文"]
ParseHeader --> Inject["注入上下文"]
AllowNull --> Continue
BuildUser --> Inject
Inject --> Continue
Deny --> End(["结束"])
Continue --> End

图表来源

章节来源

登录用户上下文(LoginUser)设计​

  • 字段：用户ID、用户类型、额外信息、租户ID、授权范围、过期时间、上下文缓存。
  • 上下文缓存：用于按 LoginUser 维度的临时缓存，避免重复查询。
  • 与上下文工具配合：通过工具类设置/获取/移除登录用户，支持网关与服务间透传。

Mermaid Diagram Code:

classDiagram
class LoginUser {
+id : Long
+userType : Integer
+info : Map~String,String~
+tenantId : Long
+scopes : String[]
+expiresTime : LocalDateTime
+context : Map~String,Object~
+setContext(key,value)
+getContext(key,type)
}
class SecurityFrameworkUtils {
+obtainAuthorization(...)
+setLoginUser(user,request)
+removeLoginUser(exchange)
}
LoginUser <-- SecurityFrameworkUtils : "注入/移除"

图表来源

章节来源

权限控制策略与注解使用​

  • URL放行：通过注解扫描与配置项收集免登录URL，静态资源与显式标注免登录的接口可匿名访问。
  • 方法级权限：启用 securedEnabled 后，可在业务接口上使用权限注解实现细粒度控制。
  • 数据权限：通过 DataPermission 注解与拦截器在方法执行前后维护注解上下文，实现数据维度的权限控制。

Mermaid Diagram Code:

classDiagram
class DataPermissionContextHolder {
+get() : DataPermission
+add(dp)
+remove() : DataPermission
}
class DataPermissionAnnotationAdvisor {
+advice : Advice
+pointcut : Pointcut
}
class DataPermissionAnnotationInterceptor {
+invoke(invocation) : Object
-dataPermissionCache : Map
}
DataPermissionAnnotationAdvisor --> DataPermissionAnnotationInterceptor : "装配Advice"
DataPermissionAnnotationInterceptor --> DataPermissionContextHolder : "入栈/出栈"

图表来源

章节来源

自定义认证过滤器与权限拦截器​

  • 认证过滤器：在 UsernamePasswordAuthenticationFilter 之前执行，负责令牌校验与上下文注入；异常时统一通过全局异常处理器转换为JSON响应。
  • 权限拦截器：通过注解切面与拦截器在方法执行前后维护数据权限上下文，支持缓存与嵌套调用场景。

章节来源

访问控制清单与免登录策略​

  • 注解扫描：遍历RequestMappingHandlerMapping，收集带 @PermitAll 的接口，按HTTP方法分别归集URL。
  • 配置项补充：支持通过 yudao.security.permit-all-urls 配置免登录URL清单。
  • 兜底规则：异步请求与未命中上述规则的请求均需认证。

章节来源

会话管理与上下文传播​

  • 无状态：禁用Session，基于Token实现无状态认证。
  • 线程本地：通过自定义 SecurityContextHolder 策略，确保上下文在线程间可传递。
  • 网关透传：网关侧将登录用户信息通过 Header 透传至下游服务，下游服务再注入到本地上下文。

章节来源

权限注解与权限服务​

  • 权限服务：封装 hasAnyRoles 等权限查询，并使用缓存降低频繁调用带来的开销。
  • 缓存策略：针对角色/权限查询设置短期缓存，平衡实时性与性能。

章节来源

外部集成与令牌注入​

  • 网关集成：网关过滤器根据令牌解析用户信息，若过期则透传空用户，由下游服务自行判定。
  • 报表集成：报表模块基于前端传递的令牌，构建 LoginUser 并注入上下文，便于报表查询。

章节来源

依赖关系分析​

  • 组件耦合：过滤器依赖配置属性、全局异常处理器与系统令牌API；上下文工具贯穿请求生命周期；权限服务依赖权限API与缓存。
  • 外部依赖：Spring Security、Spring Web、Guava Cache、系统权限API与OAuth2令牌API。
  • 循环依赖：各模块职责清晰，未见循环依赖迹象。

Mermaid Diagram Code:

graph LR
Props["SecurityProperties"] --> Adapter["YudaoWebSecurityConfigurerAdapter"]
Adapter --> Filter["TokenAuthenticationFilter"]
Filter --> Utils["SecurityFrameworkUtils"]
Filter --> OAuth2["OAuth2TokenApi"]
Filter --> PermSvc["SecurityFrameworkServiceImpl"]
PermSvc --> DP["DataPermission体系"]

图表来源

性能与安全特性​

  • 密码加密：通过配置项设置 BCrypt 加密复杂度，兼顾安全性与性能。
  • 权限缓存：角色/权限查询使用短期缓存，降低频繁调用成本。
  • 令牌校验：请求级令牌校验，避免Session占用，适合高并发场景。
  • 模拟登录：仅在开发环境启用，生产务必关闭，防止安全风险。
  • 线程本地上下文：确保跨线程传递，避免上下文丢失。

章节来源

故障排查指南​

  • 令牌无效或过期：检查令牌来源与有效期，确认系统令牌API返回；必要时在开发环境启用模拟登录进行验证。
  • 用户类型不匹配：确认请求中用户类型与令牌中的用户类型一致。
  • 无状态会话：如出现上下文丢失，检查线程本地策略与过滤器顺序。
  • 免登录规则：确认注解扫描与配置项是否正确收集URL，避免误放行。
  • 网关透传：确认网关是否正确设置 login-user 头，下游服务是否正确解析。

章节来源

结论​

yudao-spring-boot-starter-security 通过“请求级令牌校验 + 上下文注入 + 方法级权限注解 + 数据权限注解”的组合，提供了高可用、高性能、易扩展的安全能力。建议在生产环境中严格关闭模拟登录、合理配置免登录URL、启用权限缓存，并结合网关与下游服务的上下文透传机制，确保安全与性能的平衡。

附录​

  • 参考文档：《芋道 Spring Boot 安全框架 Spring Security 入门》

章节来源

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答