跳到主要内容

安全认证机制

引用文件

本文档引用的文件

目录​

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

简介​

本文件面向 yudao-cloud 的安全认证机制，围绕基于 Spring Security 的认证授权体系展开，重点覆盖以下方面：

  • 用户认证：基于 JWT 令牌的认证流程与网关前置校验
  • 权限验证：URL 级别与方法级别的权限控制
  • 会话管理：无状态设计下的会话策略与上下文传递
  • 跨域处理：Spring Cloud Gateway 的跨域与响应头去重
  • 安全过滤器链：登录拦截、权限检查与异常处理
  • 最佳实践与常见漏洞防护

项目结构​

yudao-cloud 采用模块化分层与网关统一入口的架构。安全相关能力主要分布在：

  • 安全框架模块：提供 Spring Security 配置、通用工具、异常处理器与权限服务接口
  • 网关模块：提供全局 Token 校验、跨域处理与登录用户上下文透传
  • 系统模块：提供 OAuth2 令牌校验 RPC 接口
  • WebSocket 模块：提供 WebSocket 握手阶段的用户上下文注入

Mermaid Diagram Code:

graph TB
subgraph "网关层"
GW["Gateway<br/>TokenAuthenticationFilter"]
CORS["CORS 过滤器"]
end
subgraph "业务服务层"
SEC["Spring Security<br/>YudaoWebSecurityConfigurerAdapter"]
TOKF["TokenAuthenticationFilter<br/>(业务侧)"]
SYS["System 模块<br/>OAuth2OpenController"]
end
subgraph "工具与配置"
UTIL_S["SecurityFrameworkUtils<br/>(安全框架)"]
UTIL_G["SecurityFrameworkUtils<br/>(网关)"]
PROP["SecurityProperties"]
LU["LoginUser"]
end
GW --> SYS
GW --> UTIL_G
GW --> LU
SEC --> TOKF
SEC --> UTIL_S
SEC --> PROP
TOKF --> SYS
SYS --> LU

图表来源

章节来源

核心组件​

  • 安全配置适配器：负责禁用 CSRF、无状态会话、异常处理、URL 权限规则与过滤器装配
  • 网关 Token 过滤器：在请求进入业务服务前校验访问令牌并透传用户上下文
  • 业务侧 Token 过滤器：在业务服务内部将令牌解析为 LoginUser 并写入安全上下文
  • 安全工具类：提供令牌提取、上下文读取、登录用户设置与属性透传
  • 安全属性配置：定义令牌请求头/参数、免登录 URL 列表、Mock 模式等
  • 登录用户模型：承载用户标识、类型、额外信息、租户、授权范围与过期时间
  • 权限服务接口：提供权限/角色/授权范围的判定能力
  • 异常处理器：统一返回 401 与 403 错误码
  • 跨域过滤器：处理跨域请求与响应头去重

章节来源

架构总览​

yudao-cloud 的安全架构遵循“网关前置校验 + 业务侧鉴权”的双层模式：

  • 网关层：统一拦截请求，校验访问令牌，解析用户信息，注入租户与用户上下文，转发至后端服务
  • 业务层：基于 Spring Security 的 URL 与方法级权限控制，结合 LoginUser 完成细粒度授权

Mermaid Diagram Code:

sequenceDiagram
participant C as "客户端"
participant GW as "Gateway<br/>TokenAuthenticationFilter"
participant SYS as "System 模块<br/>OAuth2OpenController"
participant S as "业务服务<br/>YudaoWebSecurityConfigurerAdapter"
C->>GW : "HTTP 请求含 Authorization 或 token 参数"
GW->>GW : "提取令牌并校验"
GW->>SYS : "调用 /oauth2/check-token携带 tenant-id"
SYS-->>GW : "返回 OAuth2AccessTokenCheckRespDTO"
GW->>GW : "构建 LoginUser 并缓存"
GW->>GW : "设置 login-user 请求头"
GW->>S : "转发请求带 login-user"
S->>S : "TokenAuthenticationFilter 解析并写入安全上下文"
S-->>C : "业务响应"

图表来源

组件详解​

安全配置适配器（Spring Security）​

  • 禁用 CSRF，启用跨域，无状态会话
  • 统一异常处理：认证失败返回 401，权限不足返回 403
  • URL 权限规则：
    • 静态资源匿名访问
    • 通过注解扫描的 @PermitAll 接口免登录
    • 配置项 yudao.security.permit-all-urls 免登录
    • 自定义 AuthorizeRequestsCustomizer 扩展
    • 默认所有请求需认证
  • 注册 TokenAuthenticationFilter 于 UsernamePasswordAuthenticationFilter 之前

Mermaid Diagram Code:

flowchart TD
Start(["进入 filterChain"]) --> DisableCSRF["禁用 CSRF"]
DisableCSRF --> Stateless["无状态会话"]
Stateless --> ExHandler["异常处理：401/403"]
ExHandler --> PermitAll["静态资源与注解免登录"]
PermitAll --> CustomRules["自定义权限规则"]
CustomRules --> Fallback["其余请求需认证"]
Fallback --> AddFilter["插入 TokenAuthenticationFilter"]
AddFilter --> End(["完成"])

图表来源

章节来源

网关 Token 校验过滤器​

  • 移除可能伪造的 login-user 请求头
  • 提取 Authorization 或 token 参数中的令牌
  • 通过 System 模块的 /oauth2/check-token 校验令牌，携带 tenant-id
  • 缓存 LoginUser，构建并设置登录用户上下文
  • 将 LoginUser 以 login-user 请求头形式透传给后端服务

Mermaid Diagram Code:

flowchart TD
In(["请求进入"]) --> RemoveHeader["移除 login-user 请求头"]
RemoveHeader --> Extract["提取 Authorization/token"]
Extract --> HasToken{"存在令牌？"}
HasToken -- 否 --> Continue["继续转发"]
HasToken -- 是 --> Check["调用 /oauth2/check-token 校验"]
Check --> BuildUser["构建 LoginUser 并缓存"]
BuildUser --> SetCtx["设置登录用户上下文"]
SetCtx --> 透传["设置 login-user 请求头并转发"]

图表来源

章节来源

业务侧 Token 过滤器与上下文​

  • 从请求头或参数中提取令牌
  • 将 LoginUser 写入 Spring Security 的 Authentication 上下文
  • 通过 SecurityFrameworkUtils 将用户信息同步到 WebFrameworkUtils，便于日志等组件使用

章节来源

登录用户模型与工具​

  • LoginUser：包含用户标识、类型、额外信息、租户、授权范围与过期时间
  • SecurityFrameworkUtils：
    • 提供 obtainAuthorization、getLoginUser、setLoginUser 等常用方法
    • 在网关与安全框架中分别提供实现，确保上下文一致

章节来源

权限服务与自定义规则​

  • SecurityFrameworkService：提供 hasPermission、hasAnyPermissions、hasRole、hasAnyRoles、hasScope、hasAnyScopes 等判定接口
  • AuthorizeRequestsCustomizer：允许各模块按需扩展 URL 权限规则
  • WebSocketAuthorizeRequestsCustomizer：针对 WebSocket 路径的免登录配置

章节来源

异常处理与错误码​

  • AuthenticationEntryPointImpl：认证失败返回 401
  • AccessDeniedHandlerImpl：权限不足返回 403
  • 与全局异常处理配合，确保统一错误格式

章节来源

跨域处理​

  • 网关提供 CorsFilter 与 CorsResponseHeaderFilter：
    • CorsFilter：设置标准跨域响应头，OPTIONS 预检直接返回
    • CorsResponseHeaderFilter：修复重复 Origin/Credentials 响应头问题

章节来源

WebSocket 握手与上下文​

  • LoginUserHandshakeInterceptor：在握手前从 TokenAuthenticationFilter 的上下文中获取 LoginUser，并注入到 WebSocketSession

章节来源

依赖关系分析​

Mermaid Diagram Code:

classDiagram
class YudaoWebSecurityConfigurerAdapter {
+filterChain()
+authenticationManagerBean()
}
class TokenAuthenticationFilter_GW {
+filter()
+getLoginUser()
+buildUser()
}
class TokenAuthenticationFilter_App {
+doFilter()
}
class SecurityFrameworkUtils_App {
+obtainAuthorization()
+getLoginUser()
+setLoginUser()
}
class SecurityFrameworkUtils_GW {
+obtainAuthorization()
+setLoginUser()
+setLoginUserHeader()
}
class SecurityProperties {
+tokenHeader
+tokenParameter
+permitAllUrls
+mockEnable
+mockSecret
}
class LoginUser {
+id
+userType
+info
+tenantId
+scopes
+expiresTime
}
class SecurityFrameworkService {
+hasPermission()
+hasAnyPermissions()
+hasRole()
+hasAnyRoles()
+hasScope()
+hasAnyScopes()
}
class OAuth2OpenController {
+checkToken()
}
YudaoWebSecurityConfigurerAdapter --> TokenAuthenticationFilter_App : "注册过滤器"
YudaoWebSecurityConfigurerAdapter --> SecurityFrameworkUtils_App : "使用工具"
YudaoWebSecurityConfigurerAdapter --> SecurityProperties : "读取配置"
TokenAuthenticationFilter_GW --> OAuth2OpenController : "调用校验接口"
TokenAuthenticationFilter_GW --> SecurityFrameworkUtils_GW : "设置上下文"
TokenAuthenticationFilter_App --> SecurityFrameworkUtils_App : "解析令牌"
SecurityFrameworkUtils_App --> LoginUser : "封装用户"
SecurityFrameworkUtils_GW --> LoginUser : "透传用户"
SecurityFrameworkService <|.. SecurityFrameworkServiceImpl : "实现"

图表来源

章节来源

性能考量​

  • 网关层缓存：TokenAuthenticationFilter.java（网关）使用 LoadingCache 缓存 LoginUser，减少远程校验次数，建议合理设置缓存失效时间
  • 异步加载：CacheLoader 采用异步重载策略，降低首次访问延迟
  • 令牌校验：仅在存在令牌时触发校验，无令牌请求直接透传，减少无效调用
  • 跨域优化：CORS 过滤器对 OPTIONS 预检直接返回，避免不必要的后续处理

章节来源

故障排查指南​

  • 401 未认证
    • 检查请求是否携带正确的 Authorization 或 token 参数
    • 确认网关 TokenAuthenticationFilter 是否成功调用 /oauth2/check-token
    • 核对 SecurityProperties 中 tokenHeader 与 tokenParameter 配置
  • 403 权限不足
    • 检查用户角色/权限与授权范围是否满足接口要求
    • 确认自定义 AuthorizeRequestsCustomizer 是否正确配置
  • 跨域问题
    • 确认 CorsFilter 与 CorsResponseHeaderFilter 是否生效
    • 检查响应头是否存在重复 Origin/Credentials
  • WebSocket 握手失败
    • 确认 LoginUserHandshakeInterceptor 能从上下文中获取 LoginUser
    • 检查 TokenAuthenticationFilter 是否已在握手前完成令牌校验

章节来源

结论​

yudao-cloud 的安全认证机制通过“网关前置校验 + 业务侧鉴权”的双层设计，实现了无状态、可扩展、易维护的认证授权体系。结合统一的异常处理、跨域支持与上下文透传，能够满足多租户、多模块场景下的安全需求。建议在生产环境中：

  • 合理配置免登录 URL 与权限规则
  • 使用 HTTPS 与强令牌策略
  • 定期清理过期令牌与缓存
  • 监控 401/403 比例与跨域响应头状态
用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答