Skip to content

starter-security ​

1. 职责 ​

把 Spring Security 配置成「无状态 Token 认证」的一套固定姿势:从 Authorization 头(或 token 参数)取令牌,调 OAuth2TokenCommonApi 校验,把 LoginUser 放进 SecurityContext,再用 @PreAuthorize("@ss.hasPermission('system:user:query')") 做功能权限。

它同时提供项目里所有「当前用户」相关工具:SecurityFrameworkUtils.getLoginUserId()(MyBatis 自动填充的取值来源)、@PermitAll 免登录扫描、AuthorizeRequestsCustomizer 业务放行扩展点,以及基于 mzt-log 的 @OperateLog 操作日志。

它不解决:令牌的签发与存储(在 pmforge-module-system 的 OAuth2 模块)、数据权限(biz-data-permission)、租户校验(biz-tenant)。

本节路径均省略公共前缀 framework/pmforge-spring-boot-starter-security/src/main/java/com/pmforge/framework/。

2. 关键类 ​

类作用路径
PmforgeSecurityAutoConfiguration认证组件装配:密码编码器、Token 过滤器、@ss、LoginUser 线程传递security/config/PmforgeSecurityAutoConfiguration.java
PmforgeWebSecurityConfigurerAdapterSecurityFilterChain:CORS、关闭 CSRF、STATELESS、放行规则、@EnableMethodSecuritysecurity/config/PmforgeWebSecurityConfigurerAdapter.java
SecurityPropertiespmforge.security.*security/config/SecurityProperties.java
TokenAuthenticationFilter解析令牌 → OAuth2TokenCommonApi.checkAccessToken → 构建 LoginUser → 写 SecurityContextsecurity/core/filter/TokenAuthenticationFilter.java
LoginUserid、userType、info(昵称/部门)、tenantId、scopes、expiresTime、visitTenantIdsecurity/core/LoginUser.java
SecurityFrameworkService(Bean 名 ss)hasPermission/hasAnyPermissions/hasRole/hasScope 等 SpEL 入口security/core/service/SecurityFrameworkService.java
SecurityFrameworkServiceImpl实际判定;跨租户访问(visitTenantId != tenantId)时直接放行security/core/service/SecurityFrameworkServiceImpl.java
SecurityFrameworkUtils取当前用户/用户 ID/昵称/部门;setLoginUser 同时写进 request 供访问日志读取security/core/util/SecurityFrameworkUtils.java
AuthenticationEntryPointImpl / AccessDeniedHandlerImpl未登录 → 401;无权限 → 403,均输出 CommonResult JSONsecurity/core/handler/
TransmittableThreadLocalSecurityContextHolderStrategy让 SecurityContext 能跨 @Async/线程池传递security/core/context/
AuthorizeRequestsCustomizer业务模块往 FilterChain 里插放行规则的抽象类(buildAdminApi/buildAppApi)security/config/AuthorizeRequestsCustomizer.java
PmforgeOperateLogConfiguration / LogRecordServiceImpl@EnableLogRecord + ILogRecordService 实现,落库交给 OperateLogCommonApioperatelog/config/、operatelog/core/service/

3. 自动配置 ​

配置类生效条件注册了什么
PmforgeSecurityAutoConfiguration@AutoConfigureOrder(-1),先于 Spring Security 自动配置(否则改基础包后 org.* 规则不生效)PasswordEncoder(BCryptPasswordEncoder,强度取 passwordEncoderLength);TokenAuthenticationFilter;@Bean("ss") SecurityFrameworkService;AuthenticationEntryPointImpl、AccessDeniedHandlerImpl;MethodInvokingFactoryBean 把 SecurityContextHolder 策略换成 TTL 版本
PmforgeWebSecurityConfigurerAdapter@AutoConfigureOrder(-1) + @EnableMethodSecurity(securedEnabled = true)SecurityFilterChain:CORS 开启、CSRF 关闭、SessionCreationPolicy.STATELESS、frameOptions.disable;AuthenticationManager
PmforgeOperateLogConfiguration始终装配@EnableLogRecord(tenant = "");@Primary ILogRecordService = LogRecordServiceImpl

放行顺序(SecurityFilterChain 内的 authorizeHttpRequests):GET 静态资源 → @PermitAll(方法级/类级,按 RequestMethod 逐个放开,未指定 method 则 6 个方法全放)→ pmforge.security.permit-all-urls → 各 AuthorizeRequestsCustomizer → 兜底 anyRequest().authenticated();ASYNC 类型一律放行(SSE 需要)。

4. 配置项 ​

前缀键默认值说明
pmforge.securitytoken-headerAuthorization令牌请求头
pmforge.securitytoken-parametertoken令牌参数(WebSocket 无法带 header 时用)
pmforge.securitymock-enablefalse本地免登录调试开关
pmforge.securitymock-secrettestmock-enable=true 时,Bearer <mock-secret><userId> 直接当该用户
pmforge.securitypermit-all-urls空免登录路径;示例配置写作 permit-all_urls(下划线与连字符混用,靠宽松绑定生效)
pmforge.securitypassword-encoder-length4BCrypt 强度,调大启动与登录都会变慢

5. 扩展点 ​

  • 放行新路径:继承 AuthorizeRequestsCustomizer,在 customize 里 registry.requestMatchers(buildAdminApi("/xxx/**")).permitAll();getOrder() 默认 0,越小越先。
  • 免登录接口:Controller 或方法上标 @PermitAll(javax.annotation.security.PermitAll,Boot 2.7 生态),框架启动时扫描一次,运行期新增不生效。
  • 权限判定:Service 层用 @PreAuthorize("@ss.hasPermission('system:user:query')");无权限抛 403 由 AccessDeniedHandlerImpl 处理。
  • 当前用户:SecurityFrameworkUtils.getLoginUserId();需要整对象用 getLoginUser()。
  • 操作日志:方法上标 @OperateLog(type = ..., module = ...),bizId 会被 Long.parseLong 解析成业务主键。
  • 密码强度:改 pmforge.security.password-encoder-length 只影响新哈希,老密码仍可校验。

6. 常见坑 ​

  1. @PermitAll 是启动时扫描的:PmforgeWebSecurityConfigurerAdapter 在构建 FilterChain 时反射收集注解 URL,因此运行时动态注册的 Controller 不会被放行。
  2. 跨租户访问会整体跳过权限校验:SecurityFrameworkServiceImpl.skipPermissionCheck() 在 loginUser.visitTenantId != tenantId 时返回 true,功能权限与数据权限一起放行——这是「租户切换」功能的前提,也是越权排查时最容易被忽略的一环。
  3. 操作日志的 bizNo 必须是数字:LogRecordServiceImpl 对 logRecord.getBizNo() 直接 Long.parseLong,传订单号之类的字符串会抛 NumberFormatException。
  4. mock-enable 是危险开关:打开后任何以 mockSecret 开头的令牌都会被当成对应用户,示例 mock-secret=test,生产环境务必保持 false。
  5. SecurityContext 策略被换成 TTL 实现:好处是 @Async 能拿到用户;但线程池复用线程时若未 clear,会串用上一个请求的用户(TTL 的 TtlRunnable 已在 starter-job 里装饰线程池)。
  6. OAuth2TokenCommonApi 校验异常被吞掉:TokenAuthenticationFilter 捕获 ServiceException 后返回 null,即「当作未登录」继续走,而不是直接 401——所以免登录接口不会因为 token 过期而报错。

7. 关联页面 ​