主题
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 |
PmforgeWebSecurityConfigurerAdapter | SecurityFilterChain:CORS、关闭 CSRF、STATELESS、放行规则、@EnableMethodSecurity | security/config/PmforgeWebSecurityConfigurerAdapter.java |
SecurityProperties | pmforge.security.* | security/config/SecurityProperties.java |
TokenAuthenticationFilter | 解析令牌 → OAuth2TokenCommonApi.checkAccessToken → 构建 LoginUser → 写 SecurityContext | security/core/filter/TokenAuthenticationFilter.java |
LoginUser | id、userType、info(昵称/部门)、tenantId、scopes、expiresTime、visitTenantId | security/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 JSON | security/core/handler/ |
TransmittableThreadLocalSecurityContextHolderStrategy | 让 SecurityContext 能跨 @Async/线程池传递 | security/core/context/ |
AuthorizeRequestsCustomizer | 业务模块往 FilterChain 里插放行规则的抽象类(buildAdminApi/buildAppApi) | security/config/AuthorizeRequestsCustomizer.java |
PmforgeOperateLogConfiguration / LogRecordServiceImpl | @EnableLogRecord + ILogRecordService 实现,落库交给 OperateLogCommonApi | operatelog/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.security | token-header | Authorization | 令牌请求头 |
pmforge.security | token-parameter | token | 令牌参数(WebSocket 无法带 header 时用) |
pmforge.security | mock-enable | false | 本地免登录调试开关 |
pmforge.security | mock-secret | test | mock-enable=true 时,Bearer <mock-secret><userId> 直接当该用户 |
pmforge.security | permit-all-urls | 空 | 免登录路径;示例配置写作 permit-all_urls(下划线与连字符混用,靠宽松绑定生效) |
pmforge.security | password-encoder-length | 4 | BCrypt 强度,调大启动与登录都会变慢 |
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. 常见坑
@PermitAll是启动时扫描的:PmforgeWebSecurityConfigurerAdapter在构建 FilterChain 时反射收集注解 URL,因此运行时动态注册的 Controller 不会被放行。- 跨租户访问会整体跳过权限校验:
SecurityFrameworkServiceImpl.skipPermissionCheck()在loginUser.visitTenantId != tenantId时返回 true,功能权限与数据权限一起放行——这是「租户切换」功能的前提,也是越权排查时最容易被忽略的一环。 - 操作日志的
bizNo必须是数字:LogRecordServiceImpl对logRecord.getBizNo()直接Long.parseLong,传订单号之类的字符串会抛NumberFormatException。 mock-enable是危险开关:打开后任何以mockSecret开头的令牌都会被当成对应用户,示例mock-secret=test,生产环境务必保持false。SecurityContext策略被换成 TTL 实现:好处是@Async能拿到用户;但线程池复用线程时若未 clear,会串用上一个请求的用户(TTL 的TtlRunnable已在starter-job里装饰线程池)。OAuth2TokenCommonApi校验异常被吞掉:TokenAuthenticationFilter捕获ServiceException后返回null,即「当作未登录」继续走,而不是直接 401——所以免登录接口不会因为 token 过期而报错。
7. 关联页面
- starter-web:Filter 顺序、
/admin-api前缀 - starter-mybatis:
creator/updater自动填充依赖登录上下文 - starter-biz-tenant:租户校验用的正是
LoginUser.tenantId - starter-biz-data-permission:复用
skipPermissionCheck - 横切机制、认证与权限、操作日志