Spring Boot Actuator 端点安全加固最佳实践

在构建基于 Spring Boot 的微服务和企业应用程序时，监控和管理系统运行状态至关重要。Spring Boot Actuator 提供了一系列用于监控和管理应用程序的端点，但这些端点也可能成为安全隐患。特别是自定义端点，如果没有正确配置安全措施，可能会导致敏感信息泄露或被未授权访问。

本文将深入探讨 Spring Boot Actuator 自定义端点的安全加固技术，从基础配置到高级安全策略，帮助开发者构建既可靠又安全的端点。

1. Spring Boot Actuator 简介

Spring Boot Actuator 是 Spring Boot 框架的一个子项目，提供了许多用于监控和管理应用程序的生产级特性。这些特性以 HTTP 端点（也称为”Actuator 端点”）或 JMX MBeans 的形式暴露出来。

1.1 内置端点

Actuator 提供了多种内置端点，包括：

/health：应用健康状态
/info：应用程序信息
/metrics：应用指标
/env：环境配置
/loggers：日志配置
等等…

1.2 自定义端点

除了内置端点，Spring Boot Actuator 还允许开发者创建自定义端点，以满足特定的业务需求。自定义端点可以提供特定于应用的监控或管理功能。

import java.util.HashMap;
import java.util.Map;

@Component
@Endpoint(id = “custom”)
public class CustomEndpoint {

private Map<String, Object> customMetrics = new HashMap<>();

public CustomEndpoint() {
customMetrics.put(“lastAccess”, System.currentTimeMillis());
customMetrics.put(“accessCount”, 0);
}

@ReadOperation
public Map<String, Object> getCustomMetrics() {
// 更新访问计数
customMetrics.put(“accessCount”, (Integer) customMetrics.get(“accessCount”) + 1);
customMetrics.put(“lastAccess”, System.currentTimeMillis());
return customMetrics;
}

@WriteOperation
public Map<String, Object> updateCustomMetric(String key, Object value) {
customMetrics.put(key, value);
return customMetrics;
}
}

上述代码创建了一个简单的自定义端点，提供了读取和写入自定义指标的功能。然而，如果没有适当的安全措施，这个端点可能会被恶意用户利用来修改应用程序状态或获取敏感信息。

2. 自定义端点的安全风险分析

在实现自定义端点时，我们必须意识到以下安全风险：

2.1 信息泄露

未受保护的端点可能会泄露敏感信息，如：

系统配置
环境变量（可能包含密码或密钥）
业务数据
用户信息

2.2 未授权操作

特别是对于支持写操作的端点，未经授权的访问可能导致：

更改应用程序行为
修改关键配置
触发不必要的操作

2.3 拒绝服务

如果端点执行资源密集型操作，恶意用户可能会重复访问导致系统资源耗尽。

2.4 权限提升

某些端点可能提供功能允许用户修改权限配置，导致权限提升。

3. 基础安全配置

在深入探讨自定义端点安全之前，先了解 Spring Boot Actuator 的基础安全配置。

3.1 端点暴露控制

首先，应该控制哪些端点被暴露：

# 在 application.properties 或 application.yml 中

# 仅暴露特定端点
management.endpoints.web.exposure.include=health,info,custom
# 或者排除特定端点
management.endpoints.web.exposure.exclude=env,beans

# 禁用特定端点
management.endpoint.shutdown.enabled=false

# 为所有端点配置基础路径（默认为 /actuator）
management.endpoints.web.base-path=/management

3.2 添加 Spring Security 依赖

确保项目中添加了 Spring Security 依赖：

<!– Maven –>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>

<!– Gradle –>
// implementation ‘org.springframework.boot:spring-boot-starter-security’

3.3 基础安全配置

下面是一个基础的 Spring Security 配置，用于保护 Actuator 端点：

import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.provisioning.InMemoryUserDetailsManager;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class ActuatorSecurityConfig {

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests((requests) -> requests
// 允许所有用户访问 /health 和 /info 端点
.requestMatchers(EndpointRequest.to(“health”, “info”)).permitAll()
// 要求访问所有其他端点的用户具有 ACTUATOR_ADMIN 角色
.requestMatchers(EndpointRequest.toAnyEndpoint()).hasRole(“ACTUATOR_ADMIN”)
// 要求访问自定义端点的用户具有 CUSTOM_ENDPOINT 角色
.requestMatchers(EndpointRequest.to(“custom”)).hasRole(“CUSTOM_ENDPOINT”)
// 其他请求需要认证
.anyRequest().authenticated()
)
// 启用 HTTP 基本认证
.httpBasic();

return http.build();
}

@Bean
public InMemoryUserDetailsManager userDetailsService() {
UserDetails user = User.builder()
.username(“user”)
.password(passwordEncoder().encode(“password”))
.roles(“USER”)
.build();

UserDetails actuatorAdmin = User.builder()
.username(“admin”)
.password(passwordEncoder().encode(“admin”))
.roles(“USER”, “ACTUATOR_ADMIN”, “CUSTOM_ENDPOINT”)
.build();

UserDetails customEndpointUser = User.builder()
.username(“custom”)
.password(passwordEncoder().encode(“custom”))
.roles(“USER”, “CUSTOM_ENDPOINT”)
.build();

return new InMemoryUserDetailsManager(user, actuatorAdmin, customEndpointUser);
}

@Bean
public PasswordEncoder passwordEncoder() {
return new BCryptPasswordEncoder();
}
}

4. 自定义端点的安全加固策略

仅仅依靠基础安全配置可能不足以保护自定义端点。下面介绍几种安全加固策略。

4.1 方法级安全控制

使用 Spring Security 的方法级安全注解可以为端点操作添加精细的权限控制：

import java.util.HashMap;
import java.util.Map;

@Component
@Endpoint(id = “custom”)
public class SecureCustomEndpoint {

private Map<String, Object> customMetrics = new HashMap<>();

public SecureCustomEndpoint() {
customMetrics.put(“lastAccess”, System.currentTimeMillis());
customMetrics.put(“accessCount”, 0);
}

// 只允许具有 READ_METRICS 权限的用户读取
@ReadOperation
@PreAuthorize(“hasAuthority(‘CUSTOM_READ’) or hasRole(‘ACTUATOR_ADMIN’)”)
public Map<String, Object> getCustomMetrics() {
customMetrics.put(“accessCount”, (Integer) customMetrics.get(“accessCount”) + 1);
customMetrics.put(“lastAccess”, System.currentTimeMillis());
return customMetrics;
}

// 只允许具有 WRITE_METRICS 权限的用户写入，并且只能在工作时间内操作
@WriteOperation
@PreAuthorize(“hasAuthority(‘CUSTOM_WRITE’) and hasRole(‘ACTUATOR_ADMIN’) and @securityService.isWorkingHours()”)
public Map<String, Object> updateCustomMetric(String key, Object value) {
customMetrics.put(key, value);
return customMetrics;
}
}

别忘了启用方法级安全：

import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;

@Configuration
@EnableMethodSecurity
public class MethodSecurityConfig {
// 配置内容…
}

以及上面引用的安全服务：

import org.springframework.stereotype.Service;

import java.time.LocalTime;

@Service
public class SecurityService {

/**
* 判断当前是否为工作时间（工作日9:00-18:00）
*
* @return 是否为工作时间
*/
public boolean isWorkingHours() {
LocalTime now = LocalTime.now();
LocalTime start = LocalTime.of(9, 0);
LocalTime end = LocalTime.of(18, 0);

return now.isAfter(start) && now.isBefore(end);
}
}

4.2 输入验证和输出过滤

保护端点的一个重要方面是验证输入和过滤输出，以防止注入攻击和敏感信息泄露：

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.boot.actuate.endpoint.annotation.Selector;
import org.springframework.boot.actuate.endpoint.annotation.WriteOperation;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.stereotype.Component;

import java.util.HashMap;
import java.util.Map;
import java.util.regex.Pattern;

@Component
@Endpoint(id = “systemInfo”)
public class SystemInfoEndpoint {

private static final Logger logger = LoggerFactory.getLogger(SystemInfoEndpoint.class);

// 安全的键名模式，只允许字母数字和下划线
private static final Pattern SAFE_KEY_PATTERN = Pattern.compile(“^[a-zA-Z0-9_]+$”);

// 敏感数据关键字
private static final String[] SENSITIVE_KEYWORDS = {
“password”, “credential”, “secret”, “key”, “token”, “auth”
};

private Map<String, Object> systemInfo = new HashMap<>();

public SystemInfoEndpoint() {
// 初始化系统信息
systemInfo.put(“javaVersion”, System.getProperty(“java.version”));
systemInfo.put(“startTime”, System.currentTimeMillis());
}

@ReadOperation
@PreAuthorize(“hasRole(‘ACTUATOR_ADMIN’)”)
public Map<String, Object> getSystemInfo() {
// 创建一个副本，以避免直接暴露内部状态
Map<String, Object> filteredInfo = new HashMap<>(systemInfo);

// 过滤掉敏感信息
filterSensitiveInfo(filteredInfo);

return filteredInfo;
}

@ReadOperation
@PreAuthorize(“hasRole(‘ACTUATOR_ADMIN’)”)
public Object getSystemInfoByKey(@Selector String key) {
// 验证键名是否安全
if (!isValidKey(key)) {
logger.warn(“检测到不安全的键名访问尝试: {}”, key);
throw new IllegalArgumentException(“Invalid key format”);
}

Object value = systemInfo.get(key);

// 检查是否为敏感信息
if (value != null && isSensitiveKey(key)) {
logger.warn(“尝试访问敏感信息: {}”, key);
return “******”;
}

return value;
}

@WriteOperation
@PreAuthorize(“hasRole(‘ADMIN’)”)
public void updateSystemInfo(String key, String value) {
// 验证键名是否安全
if (!isValidKey(key)) {
logger.warn(“尝试使用不安全的键名更新: {}”, key);
throw new IllegalArgumentException(“Invalid key format”);
}

// 验证是否尝试更新敏感信息
if (isSensitiveKey(key)) {
logger.warn(“尝试更新敏感信息: {}”, key);
throw new IllegalArgumentException(“Cannot update sensitive information”);
}

// 对值进行验证（实际应用中可能需要更复杂的验证）
if (value == null || value.isEmpty()) {
throw new IllegalArgumentException(“Value cannot be empty”);
}

// 记录更新操作
logger.info(“系统信息更新: {} = {}”, key, value);

// 更新信息
systemInfo.put(key, value);
}

/**
* 验证键名是否安全
*/
private boolean isValidKey(String key) {
return key != null && SAFE_KEY_PATTERN.matcher(key).matches();
}

/**
* 判断键名是否包含敏感关键字
*/
private boolean isSensitiveKey(String key) {
if (key == null) return false;

String lowerKey = key.toLowerCase();
for (String keyword : SENSITIVE_KEYWORDS) {
if (lowerKey.contains(keyword)) {
return true;
}
}

return false;
}

/**
* 过滤敏感信息
*/
private void filterSensitiveInfo(Map<String, Object> info) {
for (Map.Entry<String, Object> entry : info.entrySet()) {
if (isSensitiveKey(entry.getKey())) {
entry.setValue(“******”);
}
}
}
}

4.3 速率限制和防暴力攻击

为防止暴力攻击和拒绝服务攻击，可以实现速率限制：

import java.time.Duration;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicInteger;

import org.springframework.stereotype.Component;

/**
* 简单的速率限制器实现
*/
@Component
public class RateLimiter {

// 存储每个 IP 的访问计数
private final Map<String, AccessCounter> accessCounters = new ConcurrentHashMap<>();

// 每分钟允许的最大请求数
private final int MAX_REQUESTS_PER_MINUTE = 30;

// 封禁时间（分钟）
private final int BAN_DURATION_MINUTES = 5;

/**
* 检查给定 IP 是否允许访问
*
* @param ipAddress 客户端 IP 地址
* @return 是否允许访问
*/
public boolean allowAccess(String ipAddress) {
// 清理过期的访问记录
cleanupExpiredEntries();

// 检查 IP 是否被封禁
if (isBanned(ipAddress)) {
return false;
}

// 获取或创建访问计数器
AccessCounter counter = accessCounters.computeIfAbsent(ipAddress,
k -> new AccessCounter());

// 记录访问并检查是否超过限制
return counter.incrementAndCheck(MAX_REQUESTS_PER_MINUTE);
}

/**
* 检查 IP 是否被封禁
*/
private boolean isBanned(String ipAddress) {
AccessCounter counter = accessCounters.get(ipAddress);
if (counter == null) {
return false;
}

return counter.isBanned();
}

/**
* 手动封禁 IP
*/
public void banIp(String ipAddress, int durationMinutes) {
AccessCounter counter = accessCounters.computeIfAbsent(ipAddress,
k -> new AccessCounter());
counter.ban(durationMinutes);
}

/**
* 清理过期的访问记录
*/
private void cleanupExpiredEntries() {
long currentTime = System.currentTimeMillis();
accessCounters.entrySet().removeIf(entry ->
entry.getValue().isExpired(currentTime));
}

/**
* 访问计数器，记录访问次数和时间
*/
private static class AccessCounter {
// 一分钟内的访问次数
private final AtomicInteger count = new AtomicInteger(0);

// 上一次重置计数的时间
private long lastResetTime = System.currentTimeMillis();

// 封禁到期时间，0 表示未封禁
private long banExpiryTime = 0;

/**
* 增加访问计数并检查是否超过限制
*
* @param limit 访问限制
* @return 是否允许访问
*/
public boolean incrementAndCheck(int limit) {
long currentTime = System.currentTimeMillis();

// 如果已经过了一分钟，重置计数器
if (currentTime – lastResetTime > Duration.ofMinutes(1).toMillis()) {
count.set(0);
lastResetTime = currentTime;
}

// 增加计数并检查是否超过限制
int current = count.incrementAndGet();
if (current > limit) {
// 超过限制，封禁 IP
ban(BAN_DURATION_MINUTES);
return false;
}

return true;
}

/**
* 封禁访问
*
* @param durationMinutes 封禁时长（分钟）
*/
public void ban(int durationMinutes) {
banExpiryTime = System.currentTimeMillis() +
Duration.ofMinutes(durationMinutes).toMillis();
}

/**
* 检查是否处于封禁状态
*/
public boolean isBanned() {
return banExpiryTime > System.currentTimeMillis();
}

/**
* 检查计数器是否已过期（未使用超过 10 分钟）
*/
public boolean isExpired(long currentTime) {
// 如果被封禁，检查封禁是否已过期
if (banExpiryTime > 0 && currentTime > banExpiryTime) {
return true;
}

// 如果未被封禁，检查是否超过 10 分钟未使用
return !isBanned() &&
currentTime – lastResetTime > Duration.ofMinutes(10).toMillis();
}
}
}

将速率限制器应用到端点上：

import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.http.HttpStatus;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.stereotype.Component;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;
import org.springframework.web.server.ResponseStatusException;

import javax.servlet.http.HttpServletRequest;
import java.util.HashMap;
import java.util.Map;

@Component
@Endpoint(id = “performance”)
public class RateLimitedEndpoint {

private final RateLimiter rateLimiter;

public RateLimitedEndpoint(RateLimiter rateLimiter) {
this.rateLimiter = rateLimiter;
}

@ReadOperation
@PreAuthorize(“hasRole(‘ACTUATOR_ADMIN’)”)
public Map<String, Object> getPerformanceMetrics() {
// 获取当前请求的 IP 地址
String clientIp = getClientIp();

// 检查是否允许访问
if (!rateLimiter.allowAccess(clientIp)) {
throw new ResponseStatusException(HttpStatus.TOO_MANY_REQUESTS,
“Rate limit exceeded. Try again later.”);
}

// 执行资源密集型操作
Map<String, Object> metrics = collectPerformanceMetrics();

return metrics;
}

/**
* 获取客户端 IP 地址
*/
private String getClientIp() {
HttpServletRequest request = ((ServletRequestAttributes) RequestContextHolder
.getRequestAttributes()).getRequest();

// 尝试获取 X-Forwarded-For 头
String xForwardedFor = request.getHeader(“X-Forwarded-For”);
if (xForwardedFor != null && !xForwardedFor.isEmpty()) {
// X-Forwarded-For 可能包含多个 IP，取第一个
return xForwardedFor.split(“,”)[0].trim();
}

// 回退到远程地址
return request.getRemoteAddr();
}

/**
* 收集性能指标（模拟资源密集型操作）
*/
private Map<String, Object> collectPerformanceMetrics() {
Map<String, Object> metrics = new HashMap<>();

// 添加一些性能指标
Runtime runtime = Runtime.getRuntime();
long totalMemory = runtime.totalMemory();
long freeMemory = runtime.freeMemory();
long usedMemory = totalMemory – freeMemory;

metrics.put(“totalMemoryMB”, totalMemory / (1024 * 1024));
metrics.put(“freeMemoryMB”, freeMemory / (1024 * 1024));
metrics.put(“usedMemoryMB”, usedMemory / (1024 * 1024));
metrics.put(“availableProcessors”, runtime.availableProcessors());

// 获取线程信息
ThreadGroup rootGroup = Thread.currentThread().getThreadGroup();
ThreadGroup parentGroup;
while ((parentGroup = rootGroup.getParent()) != null) {
rootGroup = parentGroup;
}
int activeThreadCount = rootGroup.activeCount();
metrics.put(“activeThreadCount”, activeThreadCount);

return metrics;
}
}

4.4 安全上下文传播

在微服务环境中，安全上下文的传播是一个重要的考虑因素。以下是实现安全上下文传播的示例：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.web.client.RestTemplate;

import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpRequest;
import org.springframework.http.client.ClientHttpRequestExecution;
import org.springframework.http.client.ClientHttpRequestInterceptor;
import org.springframework.http.client.ClientHttpResponse;

import java.io.IOException;
import java.util.Collections;

/**
* 配置用于微服务间通信的 RestTemplate，传播安全上下文
*/
@Configuration
public class SecurityContextPropagationConfig {

@Bean
public RestTemplate secureRestTemplate() {
RestTemplate restTemplate = new RestTemplate();

// 添加安全上下文传播拦截器
restTemplate.setInterceptors(
Collections.singletonList(new SecurityContextInterceptor())
);

return restTemplate;
}

/**
* 实现安全上下文传播的拦截器
*/
private static class SecurityContextInterceptor implements ClientHttpRequestInterceptor {

@Override
public ClientHttpResponse intercept(HttpRequest request, byte[] body,
ClientHttpRequestExecution execution) throws IOException {

// 获取当前的认证信息
Authentication authentication = SecurityContextHolder.getContext().getAuthentication();

if (authentication != null) {
// 将认证信息添加到请求头
// 实际项目中，可能需要使用JWT或其他方式传递认证信息
HttpHeaders headers = request.getHeaders();

// 添加用户名和角色到请求头
headers.add(“X-Auth-Username”, authentication.getName());

// 将权限转换为请求头
StringBuilder roles = new StringBuilder();
authentication.getAuthorities().forEach(authority -> {
if (roles.length() > 0) {
roles.append(“,”);
}
roles.append(authority.getAuthority());
});

headers.add(“X-Auth-Roles”, roles.toString());
}

// 执行原始请求
return execution.execute(request, body);
}
}
}

5. 高级认证与授权技术

对于更复杂的安全需求，我们可以采用更高级的认证和授权技术。

5.1 OAuth2 / JWT 集成

对于微服务架构，OAuth2 和 JWT 是更适合的认证授权机制：

import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class OAuth2SecurityConfig {

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http
.csrf(csrf -> csrf.disable())
.sessionManagement(session -> session
.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
)
.authorizeHttpRequests(authorize -> authorize
// 允许所有用户访问 /health 和 /info 端点
.requestMatchers(EndpointRequest.to(“health”, “info”)).permitAll()
// 要求访问所有其他端点的用户具有 ACTUATOR_ADMIN 角色
.requestMatchers(EndpointRequest.toAnyEndpoint()).hasRole(“ACTUATOR_ADMIN”)
// 其他请求需要认证
.anyRequest().authenticated()
)
// 配置 OAuth2 资源服务器，使用 JWT 作为令牌
.oauth2ResourceServer(oauth2 -> oauth2
.jwt(jwt -> jwt
.jwtAuthenticationConverter(jwtAuthenticationConverter())
)
);

return http.build();
}

/**
* JWT 认证转换器，用于从 JWT 中提取权限
*/
@Bean
public JwtAuthenticationConverter jwtAuthenticationConverter() {
JwtGrantedAuthoritiesConverter grantedAuthoritiesConverter = new JwtGrantedAuthoritiesConverter();
// 配置角色声明的前缀
grantedAuthoritiesConverter.setAuthorityPrefix(“ROLE_”);
// 配置角色声明的键名
grantedAuthoritiesConverter.setAuthoritiesClaimName(“roles”);

JwtAuthenticationConverter jwtAuthenticationConverter = new JwtAuthenticationConverter();
jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter(grantedAuthoritiesConverter);

return jwtAuthenticationConverter;
}
}

同时，需要在配置文件中添加 JWT 相关配置：

# application.properties 或 application.yml

# JWT 配置
spring.security.oauth2.resourceserver.jwt.issuer-uri=https://auth.example.com
spring.security.oauth2.resourceserver.jwt.jwk-set-uri=https://auth.example.com/.well-known/jwks.json

# 或者使用 RSA 公钥验证 JWT
# spring.security.oauth2.resourceserver.jwt.public-key-location=classpath:public.pem

5.2 双因素认证（2FA）

对于特别敏感的端点，可以实现双因素认证：

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;

@RestController
@RequestMapping(“/api/2fa”)
public class TwoFactorAuthController {

private final Map<String, PendingAuth> pendingAuths = new HashMap<>();

@Autowired
private UserDetailsService userDetailsService;

@Autowired
private TwoFactorAuthService twoFactorService;

/**
* 第一步：用户名密码认证，发送 2FA 验证码
*/
@PostMapping(“/request”)
public Map<String, String> requestTwoFactorAuth(@RequestBody Map<String, String> credentials) {
String username = credentials.get(“username”);
String password = credentials.get(“password”);

// 这里应该验证用户名和密码
UserDetails user = userDetailsService.loadUserByUsername(username);
// 省略密码验证步骤…

// 生成并发送验证码
String otpCode = twoFactorService.generateAndSendOtp(username);

// 生成会话 ID
String sessionId = UUID.randomUUID().toString();

// 存储等待验证的用户
pendingAuths.put(sessionId, new PendingAuth(username, System.currentTimeMillis()));

// 返回会话 ID
return Collections.singletonMap(“sessionId”, sessionId);
}

/**
* 第二步：验证 2FA 代码并完成登录
*/
@PostMapping(“/verify”)
public Map<String, String> verifyTwoFactorAuth(@RequestBody Map<String, String> verificationRequest) {
String sessionId = verificationRequest.get(“sessionId”);
String otpCode = verificationRequest.get(“otpCode”);

// 验证会话 ID
PendingAuth pendingAuth = pendingAuths.get(sessionId);
if (pendingAuth == null) {
throw new IllegalArgumentException(“Invalid or expired session ID”);
}

// 检查会话是否过期（5 分钟）
if (System.currentTimeMillis() – pendingAuth.timestamp > 5 * 60 * 1000) {
pendingAuths.remove(sessionId);
throw new IllegalArgumentException(“Session expired”);
}

// 验证 OTP 代码
if (!twoFactorService.verifyOtp(pendingAuth.username, otpCode)) {
throw new IllegalArgumentException(“Invalid OTP code”);
}

// 完成认证过程
UserDetails user = userDetailsService.loadUserByUsername(pendingAuth.username);

// 创建认证对象并设置到安全上下文
Authentication auth = new UsernamePasswordAuthenticationToken(
user, null, user.getAuthorities()
);
SecurityContextHolder.getContext().setAuthentication(auth);

// 清理会话
pendingAuths.remove(sessionId);

// 返回 JWT 或其他令牌
String token = generateToken(user);
return Collections.singletonMap(“token”, token);
}

/**
* 为验证成功的用户生成 JWT 令牌
*/
private String generateToken(UserDetails user) {
// 实际项目中，可能使用 JWT 库生成令牌
return “sample-jwt-token”;
}

/**
* 存储等待验证的用户信息
*/
private static class PendingAuth {
final String username;
final long timestamp;

PendingAuth(String username, long timestamp) {
this.username = username;
this.timestamp = timestamp;
}
}
}

2FA 服务的实现：

import org.springframework.stereotype.Service;

import java.security.SecureRandom;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.TimeUnit;

@Service
public class TwoFactorAuthService {

// 存储用户的 OTP 代码
private final Map<String, OtpData> otpMap = new HashMap<>();

// OTP 代码的有效期（秒）
private static final long OTP_VALIDITY_SECONDS = 300; // 5 分钟

/**
* 生成并发送 OTP 验证码
*
* @param username 用户名
* @return 生成的 OTP 代码
*/
public String generateAndSendOtp(String username) {
// 生成 6 位随机数字
String otpCode = generateOtpCode();

// 存储 OTP
otpMap.put(username, new OtpData(otpCode, System.currentTimeMillis()));

// 发送 OTP（实际项目中可能通过短信或邮件发送）
sendOtp(username, otpCode);

return otpCode;
}

/**
* 验证 OTP 代码
*
* @param username 用户名
* @param otpCode 用户提供的 OTP 代码
* @return 验证是否成功
*/
public boolean verifyOtp(String username, String otpCode) {
OtpData otpData = otpMap.get(username);

// 检查 OTP 是否存在
if (otpData == null) {
return false;
}

// 检查 OTP 是否过期
long currentTime = System.currentTimeMillis();
if (currentTime – otpData.timestamp > TimeUnit.SECONDS.toMillis(OTP_VALIDITY_SECONDS)) {
// 移除过期的 OTP
otpMap.remove(username);
return false;
}

// 验证 OTP 代码
boolean isValid = otpData.otpCode.equals(otpCode);

// 验证成功后移除 OTP，防止重复使用
if (isValid) {
otpMap.remove(username);
}

return isValid;
}

/**
* 生成随机的 OTP 代码
*/
private String generateOtpCode() {
SecureRandom random = new SecureRandom();
int code = 100_000 + random.nextInt(900_000); // 生成 6 位数字
return String.valueOf(code);
}

/**
* 发送 OTP 代码给用户
* 实际项目中，这里应该调用短信或邮件服务
*/
private void sendOtp(String username, String otpCode) {
// 模拟发送 OTP
System.out.println(“Sending OTP code ” + otpCode + ” to user ” + username);

// 实际实现可能是：
// emailService.sendEmail(userEmail, “Your OTP code”, “Your OTP code is: ” + otpCode);
// 或
// smsService.sendSms(userPhone, “Your OTP code is: ” + otpCode);
}

/**
* 存储 OTP 数据的内部类
*/
private static class OtpData {
final String otpCode;
final long timestamp;

OtpData(String otpCode, long timestamp) {
this.otpCode = otpCode;
this.timestamp = timestamp;
}
}
}

为高敏感度的 Actuator 端点添加 2FA 验证：

import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.boot.actuate.endpoint.annotation.WriteOperation;
import org.springframework.boot.actuate.endpoint.web.WebEndpointResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.context.request.RequestAttributes;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;

import javax.servlet.http.HttpServletRequest;
import java.util.HashMap;
import java.util.Map;

@Component
@Endpoint(id = “sensitive-operations”)
public class TwoFactorRequiredEndpoint {

private final TwoFactorAuthService twoFactorService;

// 存储已完成 2FA 的会话
private final Map<String, Long> verifiedSessions = new HashMap<>();

// 会话有效期（毫秒）
private static final long SESSION_VALIDITY_MS = 30 * 60 * 1000; // 30 分钟

public TwoFactorRequiredEndpoint(TwoFactorAuthService twoFactorService) {
this.twoFactorService = twoFactorService;
}

@ReadOperation
public Object getSensitiveOperations() {
// 验证请求是否已通过 2FA
if (!verifyTwoFactorAuth()) {
return new WebEndpointResponse<>(
Map.of(“message”, “Two-factor authentication required”),
401 // Unauthorized
);
}

// 已验证，返回敏感数据
Map<String, Object> sensitiveData = new HashMap<>();
sensitiveData.put(“databaseConnectionDetails”, “jdbc:mysql://prod-db:3306/myapp”);
sensitiveData.put(“apiKeys”, Map.of(
“payment-gateway”, “sk_********”,
“email-service”, “api_********”
));
sensitiveData.put(“lastDatabaseBackup”, “2023-12-01 03:15:22”);

return sensitiveData;
}

@WriteOperation
public Object executeSensitiveOperation(String operation, String param) {
// 验证请求是否已通过 2FA
if (!verifyTwoFactorAuth()) {
return new WebEndpointResponse<>(
Map.of(“message”, “Two-factor authentication required”),
401 // Unauthorized
);
}

// 已验证，执行敏感操作
Map<String, Object> result = new HashMap<>();

switch (operation) {
case “restartService”:
result.put(“status”, “Service restart initiated”);
result.put(“service”, param);
break;
case “flushCache”:
result.put(“status”, “Cache flushed successfully”);
result.put(“cacheType”, param);
break;
case “triggerBackup”:
result.put(“status”, “Backup triggered”);
result.put(“backupTarget”, param);
break;
default:
result.put(“error”, “Unknown operation: ” + operation);
}

return result;
}

/**
* 验证请求是否已通过双因素认证
*/
private boolean verifyTwoFactorAuth() {
HttpServletRequest request = getCurrentRequest();

// 获取会话 ID
String sessionId = request.getHeader(“X-2FA-Session-ID”);
if (sessionId == null || sessionId.isEmpty()) {
return false;
}

// 检查会话是否已验证
Long timestamp = verifiedSessions.get(sessionId);
if (timestamp == null) {
return false;
}

// 检查会话是否已过期
long currentTime = System.currentTimeMillis();
if (currentTime – timestamp > SESSION_VALIDITY_MS) {
verifiedSessions.remove(sessionId);
return false;
}

// 更新会话时间戳
verifiedSessions.put(sessionId, currentTime);

return true;
}

/**
* 获取当前 HTTP 请求
*/
private HttpServletRequest getCurrentRequest() {
RequestAttributes requestAttributes = RequestContextHolder.getRequestAttributes();
if (requestAttributes instanceof ServletRequestAttributes) {
return ((ServletRequestAttributes) requestAttributes).getRequest();
}
throw new IllegalStateException(“Not a servlet request”);
}
}

6. 安全审计与日志记录

为全面监控和审计端点访问，我们需要实现详细的日志记录。

6.1 审计日志拦截器

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;
import org.springframework.web.servlet.ModelAndView;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.UUID;

@Component
public class ActuatorAuditInterceptor implements HandlerInterceptor {

private static final Logger auditLogger = LoggerFactory.getLogger(“ACTUATOR_AUDIT”);

@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
// 生成请求 ID
String requestId = UUID.randomUUID().toString();
request.setAttribute(“requestId”, requestId);

// 获取请求信息
String method = request.getMethod();
String uri = request.getRequestURI();
String queryString = request.getQueryString();
String fullPath = queryString != null ? uri + “?” + queryString : uri;

// 获取客户端信息
String clientIp = getClientIp(request);
String userAgent = request.getHeader(“User-Agent”);

// 获取认证信息
Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
String username = authentication != null ? authentication.getName() : “anonymous”;

// 记录请求开始日志
auditLogger.info(
“Actuator Request | ID: {} | User: {} | IP: {} | {} {} | Agent: {}”,
requestId, username, clientIp, method, fullPath, userAgent
);

// 记录请求开始时间
request.setAttribute(“requestStartTime”, System.currentTimeMillis());

return true;
}

@Override
public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) {
// 仅记录请求处理完成的时间点
request.setAttribute(“requestEndTime”, System.currentTimeMillis());
}

@Override
public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
// 获取请求 ID
String requestId = (String) request.getAttribute(“requestId”);

// 获取请求处理开始和结束时间
Long startTime = (Long) request.getAttribute(“requestStartTime”);
Long endTime = (Long) request.getAttribute(“requestEndTime”);

// 计算处理时间
long duration = (endTime != null && startTime != null) ? (endTime – startTime) : -1;

// 获取响应状态
int status = response.getStatus();

// 获取认证信息
Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
String username = authentication != null ? authentication.getName() : “anonymous”;

// 记录异常信息
if (ex != null) {
auditLogger.error(
“Actuator Error | ID: {} | User: {} | Status: {} | Duration: {}ms | Error: {}”,
requestId, username, status, duration, ex.getMessage(), ex
);
} else {
// 记录请求完成日志
auditLogger.info(
“Actuator Response | ID: {} | User: {} | Status: {} | Duration: {}ms”,
requestId, username, status, duration
);
}
}

/**
* 获取客户端 IP 地址
*/
private String getClientIp(HttpServletRequest request) {
String xForwardedFor = request.getHeader(“X-Forwarded-For”);
if (xForwardedFor != null && !xForwardedFor.isEmpty()) {
return xForwardedFor.split(“,”)[0].trim();
}
return request.getRemoteAddr();
}
}

注册拦截器：

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 ActuatorInterceptorConfig implements WebMvcConfigurer {

private final ActuatorAuditInterceptor auditInterceptor;

public ActuatorInterceptorConfig(ActuatorAuditInterceptor auditInterceptor) {
this.auditInterceptor = auditInterceptor;
}

@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(auditInterceptor)
.addPathPatterns(“/actuator/**”)
.addPathPatterns(“/management/**”); // 如果使用自定义路径
}
}

6.2 Spring Actuator 事件监听

Spring Boot Actuator 提供了事件机制，可以监听端点访问事件：

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.actuate.audit.AuditEvent;
import org.springframework.boot.actuate.audit.listener.AuditApplicationEvent;
import org.springframework.boot.actuate.endpoint.web.ExposableWebEndpoint;
import org.springframework.boot.actuate.endpoint.web.WebEndpointsSupplier;
import org.springframework.boot.actuate.endpoint.web.annotation.EndpointWebExtension;
import org.springframework.context.event.EventListener;
import org.springframework.security.authentication.event.AbstractAuthenticationFailureEvent;
import org.springframework.security.authentication.event.AuthenticationSuccessEvent;
import org.springframework.security.core.Authentication;
import org.springframework.stereotype.Component;

import java.util.Map;
import java.util.stream.Collectors;

@Component
public class ActuatorEventListener {

private static final Logger logger = LoggerFactory.getLogger(“ACTUATOR_EVENTS”);

private final WebEndpointsSupplier endpointsSupplier;

public ActuatorEventListener(WebEndpointsSupplier endpointsSupplier) {
this.endpointsSupplier = endpointsSupplier;
}

/**
* 监听 Actuator 审计事件
*/
@EventListener
public void onAuditEvent(AuditApplicationEvent event) {
AuditEvent auditEvent = event.getAuditEvent();

// 记录详细的审计日志
logger.info(
“Audit Event | Principal: {} | Type: {} | Timestamp: {} | Data: {}”,
auditEvent.getPrincipal(),
auditEvent.getType(),
auditEvent.getTimestamp(),
auditEvent.getData()
);

// 对于敏感操作，可以发送警报
if (isSecurityCriticalEvent(auditEvent)) {
alertSecurityTeam(auditEvent);
}
}

/**
* 监听认证成功事件
*/
@EventListener
public void onAuthenticationSuccess(AuthenticationSuccessEvent event) {
Authentication authentication = event.getAuthentication();

logger.info(
“Authentication Success | User: {} | Authorities: {}”,
authentication.getName(),
authentication.getAuthorities()
);
}

/**
* 监听认证失败事件
*/
@EventListener
public void onAuthenticationFailure(AbstractAuthenticationFailureEvent event) {
String username = event.getAuthentication().getName();
String exceptionMessage = event.getException().getMessage();

logger.warn(
“Authentication Failure | User: {} | Reason: {}”,
username,
exceptionMessage
);
}

/**
* 判断事件是否为安全敏感事件
*/
private boolean isSecurityCriticalEvent(AuditEvent event) {
String type = event.getType();

// 判断是否为关键事件
boolean isCritical = type.startsWith(“ENDPOINT_ACCESS”) &&
isSensitiveEndpoint(event) ||
type.equals(“AUTHORIZATION_FAILURE”) ||
type.equals(“AUTHENTICATION_FAILURE”);

return isCritical;
}

/**
* 判断访问的端点是否敏感
*/
private boolean isSensitiveEndpoint(AuditEvent event) {
Map<String, Object> data = event.getData();

// 获取请求的端点 ID
Object endpointId = data.get(“endpointId”);
if (endpointId == null) {
return false;
}

// 敏感端点列表
String[] sensitiveEndpoints = {
“env”, “loggers”, “heapdump”, “threaddump”,
“shutdown”, “custom”, “sensitive-operations”
};

for (String sensitive : sensitiveEndpoints) {
if (endpointId.equals(sensitive)) {
return true;
}
}

return false;
}

/**
* 对关键安全事件发送警报
*/
private void alertSecurityTeam(AuditEvent event) {
// 实际实现中，可能发送邮件、短信或调用警报 API
logger.error(
“SECURITY ALERT: Critical security event detected | Principal: {} | Type: {} | Data: {}”,
event.getPrincipal(),
event.getType(),
event.getData()
);

// 示例：发送邮件通知
// emailService.sendSecurityAlert(“Security Alert: Critical Actuator Event”,
// String.format(“User %s triggered a critical security event: %s”,
// event.getPrincipal(), event.getType()),
// “security-team@example.com”);
}
}

6.3 Actuator 访问日志配置

配置专门的 Actuator 访问日志：

<?xml version=”1.0″ encoding=”UTF-8″?>
<configuration>
<!– 默认日志配置 –>
<include resource=”org/springframework/boot/logging/logback/defaults.xml”/>
<include resource=”org/springframework/boot/logging/logback/console-appender.xml”/>

<!– 应用名称 –>
<property name=”APP_NAME” value=”myapp”/>
<!– 日志文件路径 –>
<property name=”LOG_PATH” value=”${LOG_PATH:-./logs}”/>

<!– 常规应用日志 –>
<appender name=”FILE” class=”ch.qos.logback.core.rolling.RollingFileAppender”>
<file>${LOG_PATH}/${APP_NAME}.log</file>
<rollingPolicy class=”ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy”>
<fileNamePattern>${LOG_PATH}/${APP_NAME}-%d{yyyy-MM-dd}.%i.log</fileNamePattern>
<maxFileSize>10MB</maxFileSize>
<maxHistory>30</maxHistory>
<totalSizeCap>1GB</totalSizeCap>
</rollingPolicy>
<encoder>
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} – %msg%n</pattern>
</encoder>
</appender>

<!– Actuator 审计日志 –>
<appender name=”ACTUATOR_AUDIT” class=”ch.qos.logback.core.rolling.RollingFileAppender”>
<file>${LOG_PATH}/actuator-audit.log</file>
<rollingPolicy class=”ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy”>
<fileNamePattern>${LOG_PATH}/actuator-audit-%d{yyyy-MM-dd}.%i.log</fileNamePattern>
<maxFileSize>10MB</maxFileSize>
<maxHistory>90</maxHistory>
<totalSizeCap>2GB</totalSizeCap>
</rollingPolicy>
<encoder>
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} – %msg%n</pattern>
</encoder>
</appender>

<!– Actuator 事件日志 –>
<appender name=”ACTUATOR_EVENTS” class=”ch.qos.logback.core.rolling.RollingFileAppender”>
<file>${LOG_PATH}/actuator-events.log</file>
<rollingPolicy class=”ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy”>
<fileNamePattern>${LOG_PATH}/actuator-events-%d{yyyy-MM-dd}.%i.log</fileNamePattern>
<maxFileSize>10MB</maxFileSize>
<maxHistory>90</maxHistory>
<totalSizeCap>2GB</totalSizeCap>
</rollingPolicy>
<encoder>
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} – %msg%n</pattern>
</encoder>
</appender>

<!– 安全警报日志（同时发送到控制台） –>
<appender name=”SECURITY_ALERTS” class=”ch.qos.logback.core.rolling.RollingFileAppender”>
<file>${LOG_PATH}/security-alerts.log</file>
<rollingPolicy class=”ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy”>
<fileNamePattern>${LOG_PATH}/security-alerts-%d{yyyy-MM-dd}.%i.log</fileNamePattern>
<maxFileSize>10MB</maxFileSize>
<maxHistory>365</maxHistory>
<totalSizeCap>5GB</totalSizeCap>
</rollingPolicy>
<encoder>
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level – %msg%n</pattern>
</encoder>
</appender>

<!– 控制台安全警报 –>
<appender name=”SECURITY_CONSOLE” class=”ch.qos.logback.core.ConsoleAppender”>
<encoder>
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %highlight([%thread] %-5level) %boldRed(%logger{36}) – %msg%n</pattern>
</encoder>
<filter class=”ch.qos.logback.classic.filter.ThresholdFilter”>
<level>WARN</level>
</filter>
</appender>

<!– 为不同的日志配置单独的 logger –>
<logger name=”ACTUATOR_AUDIT” level=”INFO” additivity=”false”>
<appender-ref ref=”ACTUATOR_AUDIT”/>
</logger>

<!– 安全相关日志额外写入安全日志文件 –>
<logger name=”org.springframework.security” level=”INFO” additivity=”true”>
<appender-ref ref=”SECURITY_ALERTS”/>
</logger>

<!– 根日志配置 –>
<root level=”INFO”>
<appender-ref ref=”CONSOLE”/>
<appender-ref ref=”FILE”/>
</root>
</configuration>

7. 最佳实践与案例分析

下面是一个综合的最佳实践案例，展示如何配置一个生产级的安全自定义端点。

7.1 安全配置最佳实践清单

# Spring Boot Actuator 安全配置检查清单

## 基础安全配置

– [ ] 仅暴露必要的端点
“`properties
management.endpoints.web.exposure.include=health,info,custom
“`

– [ ] 显式禁用不需要的端点
“`properties
management.endpoint.shutdown.enabled=false
“`

– [ ] 配置自定义的端点路径（避免使用默认路径）
“`properties
management.endpoints.web.base-path=/management
“`

– [ ] 启用 HTTPS (TLS)
“`properties
server.ssl.key-store=classpath:keystore.p12
server.ssl.key-store-password=your-password
server.ssl.key-store-type=PKCS12
server.ssl.key-alias=tomcat
server.ssl.enabled=true
“`

## 认证与授权

– [ ] 添加 Spring Security 依赖
“`xml
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
“`

– [ ] 配置基于角色的访问控制
“`java
http.authorizeHttpRequests(requests -> requests
.requestMatchers(EndpointRequest.to(“health”, “info”)).permitAll()
.requestMatchers(EndpointRequest.toAnyEndpoint()).hasRole(“ACTUATOR_ADMIN”)
.anyRequest().authenticated()
);
“`

– [ ] 为敏感端点配置方法级安全
“`java
@PreAuthorize(“hasRole(‘ADMIN’) and hasAuthority(‘WRITE_PRIVILEGE’)”)
“`

– [ ] 对于高度敏感的端点，实现双因素认证或 IP 限制
“`properties
management.server.address=10.0.0.5
“`

## 加密与信息保护

– [ ] 敏感信息使用加密配置
“`properties
# 使用 EncryptableProperties
datasource.password=ENC(encrypted_password_here)
“`

– [ ] 配置 CORS 保护自定义端点
“`properties
management.endpoints.web.cors.allowed-origins=https://admin.example.com
management.endpoints.web.cors.allowed-methods=GET,POST
“`

– [ ] 启用 CSRF 保护
“`java
http.csrf().csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse());
“`

## 监控与审计

– [ ] 配置专门的 Actuator 审计日志
“`xml
<logger name=”ACTUATOR_AUDIT” level=”INFO” additivity=”false”>
<appender-ref ref=”ACTUATOR_AUDIT_FILE”/>
</logger>
“`

– [ ] 实现请求拦截器记录所有端点访问
“`java
registry.addInterceptor(auditInterceptor).addPathPatterns(“/actuator/**”);
“`

– [ ] 配置端点访问事件监听器
“`java
@EventListener
public void onAuditEvent(AuditApplicationEvent event) {
// 处理审计事件
}
“`

– [ ] 为关键操作设置自动警报
“`java
if (isCriticalOperation(event)) {
notificationService.sendSecurityAlert(…);
}
“`

## 输入验证与防护

– [ ] 对所有端点输入实施严格验证
“`java
if (!SAFE_PATTERN.matcher(input).matches()) {
throw new IllegalArgumentException(“Invalid input”);
}
“`

– [ ] 实现速率限制防止暴力攻击
“`java
if (!rateLimiter.allowAccess(clientIp)) {
throw new ResponseStatusException(HttpStatus.TOO_MANY_REQUESTS);
}
“`

– [ ] 过滤敏感信息不暴露给客户端
“`java
private void filterSensitiveInfo(Map<String, Object> info) {
for (String key : sensitiveKeys) {
if (info.containsKey(key)) {
info.put(key, “******”);
}
}
}
“`

## 其他最佳实践

– [ ] 定期审查端点安全配置
– [ ] 实施定期安全测试（渗透测试）
– [ ] 保持 Spring Boot 和依赖库的最新安全补丁
– [ ] 使用专门的管理网络访问生产环境的 Actuator 端点
– [ ] 在监控系统中设置 Actuator 访问警报
– [ ] 遵循最小权限原则配置端点权限

7.2 安全端点完整案例

下面是一个综合案例，展示如何创建一个安全的自定义 Actuator 端点：

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.actuate.endpoint.annotation.DeleteOperation;
import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.boot.actuate.endpoint.annotation.Selector;
import org.springframework.boot.actuate.endpoint.annotation.WriteOperation;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.stereotype.Component;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;

import javax.servlet.http.HttpServletRequest;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.Collection;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.CopyOnWriteArrayList;
import java.util.regex.Pattern;

/**
* 安全系统配置端点
*
* 该端点允许管理员查看和修改与系统安全相关的配置
*/
@Component
@Endpoint(id = “securityconfig”)
public class SecureSystemConfigEndpoint {

private static final Logger logger = LoggerFactory.getLogger(SecureSystemConfigEndpoint.class);

// 键名验证模式：只允许字母、数字、下划线和点
private static final Pattern VALID_KEY_PATTERN = Pattern.compile(“^[\\w\\.]+$”);

// 敏感关键字
private static final String[] SENSITIVE_KEYWORDS = {
“password”, “secret”, “key”, “token”, “credential”, “private”
};

// 系统配置存储
private final Map<String, Object> securityConfigs = new ConcurrentHashMap<>();

// 配置修改历史
private final Map<String, Collection<ConfigChange>> configHistory = new ConcurrentHashMap<>();

private final RateLimiter rateLimiter;
private final AuditService auditService;
private final NotificationService notificationService;

@Autowired
public SecureSystemConfigEndpoint(
RateLimiter rateLimiter,
AuditService auditService,
NotificationService notificationService) {
this.rateLimiter = rateLimiter;
this.auditService = auditService;
this.notificationService = notificationService;

// 初始化一些安全配置
securityConfigs.put(“security.session.timeout”, 1800);
securityConfigs.put(“security.login.maxAttempts”, 5);
securityConfigs.put(“security.password.minLength”, 12);
securityConfigs.put(“security.mfa.enabled”, true);
securityConfigs.put(“security.jwt.expiration”, 3600);
}

/**
* 读取所有安全配置
*/
@ReadOperation
@PreAuthorize(“hasRole(‘ACTUATOR_ADMIN’) or hasRole(‘SECURITY_AUDITOR’)”)
public Map<String, Object> getSecurityConfigs() {
String clientIp = getClientIp();
String username = getCurrentUsername();

// 速率限制检查
if (!rateLimiter.allowAccess(clientIp)) {
logger.warn(“Rate limit exceeded for IP: {} when accessing security configs”, clientIp);
auditService.logSecurityEvent(username, clientIp, “RATE_LIMIT_EXCEEDED”, “securityconfig:read”, null);
throw new SecurityException(“Rate limit exceeded”);
}

// 审计日志
auditService.logSecurityEvent(username, clientIp, “CONFIG_READ”, “securityconfig:read_all”, null);

// 过滤敏感数据
Map<String, Object> filteredConfigs = new HashMap<>(securityConfigs);
for (Map.Entry<String, Object> entry : filteredConfigs.entrySet()) {
if (isSensitiveKey(entry.getKey())) {
entry.setValue(“******”);
}
}

return filteredConfigs;
}

/**
* 读取特定配置项
*/
@ReadOperation
@PreAuthorize(“hasRole(‘ACTUATOR_ADMIN’) or hasRole(‘SECURITY_AUDITOR’)”)
public Object getSecurityConfig(@Selector String key) {
String clientIp = getClientIp();
String username = getCurrentUsername();

// 验证键名
validateKey(key);

// 速率限制检查
if (!rateLimiter.allowAccess(clientIp)) {
logger.warn(“Rate limit exceeded for IP: {} when accessing security config: {}”, clientIp, key);
auditService.logSecurityEvent(username, clientIp, “RATE_LIMIT_EXCEEDED”, “securityconfig:read:” + key, null);
throw new SecurityException(“Rate limit exceeded”);
}

// 审计日志
auditService.logSecurityEvent(username, clientIp, “CONFIG_READ”, “securityconfig:read:” + key,
Map.of(“key”, key));

Object value = securityConfigs.get(key);

// 如果是敏感数据，则不返回实际值
if (value != null && isSensitiveKey(key)) {
return “******”;
}

return value;
}

/**
* 更新配置项
*/
@WriteOperation
@PreAuthorize(“hasRole(‘ACTUATOR_ADMIN’) and hasRole(‘SECURITY_ADMIN’)”)
public Map<String, Object> updateSecurityConfig(String key, String value) {
String clientIp = getClientIp();
String username = getCurrentUsername();

// 验证键名和值
validateKey(key);
if (value == null || value.trim().isEmpty()) {
throw new IllegalArgumentException(“Value cannot be empty”);
}

// 速率限制检查
if (!rateLimiter.allowAccess(clientIp)) {
logger.warn(“Rate limit exceeded for IP: {} when updating security config: {}”, clientIp, key);
auditService.logSecurityEvent(username, clientIp, “RATE_LIMIT_EXCEEDED”, “securityconfig:write:” + key, null);
throw new SecurityException(“Rate limit exceeded”);
}

// 记录当前值（用于审计）
Object oldValue = securityConfigs.get(key);

// 转换值为适当的类型
Object typedValue = convertValue(key, value);

// 更新配置
securityConfigs.put(key, typedValue);

// 记录变更
ConfigChange change = new ConfigChange(
username,
clientIp,
LocalDateTime.now(),
oldValue,
typedValue
);

// 记录变更历史
addConfigChange(key, change);

// 审计日志
Map<String, Object> auditData = new HashMap<>();
auditData.put(“key”, key);
auditData.put(“oldValue”, isSensitiveKey(key) ? “******” : oldValue);
auditData.put(“newValue”, isSensitiveKey(key) ? “******” : typedValue);

auditService.logSecurityEvent(username, clientIp, “CONFIG_UPDATE”, “securityconfig:write:” + key, auditData);

// 对于关键安全配置的更改，发送通知
if (isHighPriorityConfig(key)) {
notificationService.sendSecurityAlert(
“Critical Security Configuration Change”,
String.format(“Security config ‘%s’ was changed by %s from %s at %s”,
key, username, clientIp,
LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME)),
“security-team@example.com”
);
}

logger.info(“Security config updated: {} = {} (by user: {}, IP: {})”,
key, isSensitiveKey(key) ? “******” : typedValue, username, clientIp);

// 返回完整的配置（过滤敏感数据）
return getSecurityConfigs();
}

/**
* 删除配置项
*/
@DeleteOperation
@PreAuthorize(“hasRole(‘ACTUATOR_ADMIN’) and hasRole(‘SECURITY_ADMIN’) and hasAuthority(‘CONFIG_DELETE’)”)
public Map<String, Object> deleteSecurityConfig(@Selector String key) {
String clientIp = getClientIp();
String username = getCurrentUsername();

// 验证键名
validateKey(key);

// 速率限制检查
if (!rateLimiter.allowAccess(clientIp)) {
logger.warn(“Rate limit exceeded for IP: {} when deleting security config: {}”, clientIp, key);
auditService.logSecurityEvent(username, clientIp, “RATE_LIMIT_EXCEEDED”, “securityconfig:delete:” + key, null);
throw new SecurityException(“Rate limit exceeded”);
}

// 检查是否为核心配置（不允许删除）
if (isCoreConfig(key)) {
logger.error(“Attempt to delete core config: {} by user: {}, IP: {}”, key, username, clientIp);
auditService.logSecurityEvent(username, clientIp, “CORE_CONFIG_DELETE_ATTEMPT”,
“securityconfig:delete:” + key, Map.of(“key”, key));
throw new SecurityException(“Cannot delete core security configuration: ” + key);
}

// 记录当前值（用于审计）
Object oldValue = securityConfigs.get(key);

// 删除配置
securityConfigs.remove(key);

// 记录变更
ConfigChange change = new ConfigChange(
username,
clientIp,
LocalDateTime.now(),
oldValue,
null
);

// 记录变更历史
addConfigChange(key, change);

// 审计日志
Map<String, Object> auditData = new HashMap<>();
auditData.put(“key”, key);
auditData.put(“oldValue”, isSensitiveKey(key) ? “******” : oldValue);

auditService.logSecurityEvent(username, clientIp, “CONFIG_DELETE”, “securityconfig:delete:” + key, auditData);

// 通知安全团队
notificationService.sendSecurityAlert(
“Security Configuration Deleted”,
String.format(“Security config ‘%s’ was deleted by %s from %s at %s”,
key, username, clientIp,
LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME)),
“security-team@example.com”
);

logger.info(“Security config deleted: {} (by user: {}, IP: {})”, key, username, clientIp);

// 返回完整的配置（过滤敏感数据）
return getSecurityConfigs();
}

/**
* 检查配置项是否为核心配置（不允许删除）
*/
private boolean isCoreConfig(String key) {
String[] coreConfigs = {
“security.session.timeout”,
“security.login.maxAttempts”,
“security.password.minLength”,
“security.mfa.enabled”
};

for (String coreKey : coreConfigs) {
if (coreKey.equals(key)) {
return true;
}
}

return false;
}

/**
* 检查配置项是否为高优先级（需要通知）
*/
private boolean isHighPriorityConfig(String key) {
String[] highPriorityKeys = {
“security.mfa.enabled”,
“security.login.maxAttempts”,
“security.jwt.secret”,
“security.password.minLength”
};

for (String highPriorityKey : highPriorityKeys) {
if (highPriorityKey.equals(key)) {
return true;
}
}

return false;
}

/**
* 验证键名是否安全
*/
private void validateKey(String key) {
if (key == null || key.trim().isEmpty()) {
throw new IllegalArgumentException(“Key cannot be empty”);
}

if (!VALID_KEY_PATTERN.matcher(key).matches()) {
logger.warn(“Invalid key format attempted: {}”, key);
throw new IllegalArgumentException(“Invalid key format”);
}
}

/**
* 将字符串值转换为适当的类型
*/
private Object convertValue(String key, String value) {
// 根据键名推断类型
if (key.endsWith(“.timeout”) || key.endsWith(“.expiration”) ||
key.endsWith(“.maxAttempts”) || key.endsWith(“.minLength”) ||
key.endsWith(“.size”) || key.endsWith(“.count”)) {
try {
return Integer.parseInt(value);
} catch (NumberFormatException e) {
throw new IllegalArgumentException(“Value for ” + key + ” must be an integer”);
}
} else if (key.endsWith(“.enabled”) || key.endsWith(“.active”) ||
key.endsWith(“.required”)) {
return Boolean.parseBoolean(value);
} else if (key.endsWith(“.ratio”) || key.endsWith(“.factor”)) {
try {
return Double.parseDouble(value);
} catch (NumberFormatException e) {
throw new IllegalArgumentException(“Value for ” + key + ” must be a decimal number”);
}
}

// 默认返回字符串
return value;
}

/**
* 添加配置变更记录
*/
private void addConfigChange(String key, ConfigChange change) {
configHistory.computeIfAbsent(key, k -> new CopyOnWriteArrayList<>())
.add(change);
}

/**
* 检查键名是否包含敏感信息关键字
*/
private boolean isSensitiveKey(String key) {
if (key == null) {
return false;
}

String lowerKey = key.toLowerCase();
for (String keyword : SENSITIVE_KEYWORDS) {
if (lowerKey.contains(keyword)) {
return true;
}
}

return false;
}

/**
* 获取当前用户名
*/
private String getCurrentUsername() {
Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
return authentication != null ? authentication.getName() : “anonymous”;
}

/**
* 获取客户端 IP 地址
*/
private String getClientIp() {
HttpServletRequest request = ((ServletRequestAttributes) RequestContextHolder
.getRequestAttributes()).getRequest();

String xForwardedFor = request.getHeader(“X-Forwarded-For”);
if (xForwardedFor != null && !xForwardedFor.isEmpty()) {
return xForwardedFor.split(“,”)[0].trim();
}

return request.getRemoteAddr();
}

/**
* 配置变更记录类
*/
private static class ConfigChange {
private final String username;
private final String ipAddress;
private final LocalDateTime timestamp;
private final Object oldValue;
private final Object newValue;

public ConfigChange(String username, String ipAddress, LocalDateTime timestamp,
Object oldValue, Object newValue) {
this.username = username;
this.ipAddress = ipAddress;
this.timestamp = timestamp;
this.oldValue = oldValue;
this.newValue = newValue;
}

// Getters…
public String getUsername() { return username; }
public String getIpAddress() { return ipAddress; }
public LocalDateTime getTimestamp() { return timestamp; }
public Object getOldValue() { return oldValue; }
public Object getNewValue() { return newValue; }
}
}

现在，我们需要实现相关的辅助服务接口：