Spring Security with Spring Boot Actuator: the authorization model that survived the incident
68% of security misconfigs in Spring Boot come from configuration that looks secure because it doesn't throw an error. Yeah, read that again. No exception, no warning in the log, nothing. The endpoint just responds 200 and you don't find out until someone else does.
That's exactly what happened in the case I described in the previous post. Actuator running in production, /env and /metrics returning data without asking for credentials — all because Spring Boot 3's default configuration doesn't lock down what you don't know about. We closed the misconfigured endpoints. But closing them wasn't enough — the authorization model that remained was inherited, implicit, and fragile. It had to be rebuilt.
My thesis is this: an inherited-by-default authorization model is technically worse than an explicit one, even if both produce the same observable behavior today. Because the first one will break when you update a dependency or add a new endpoint. The second one will scream.
The problem with the SecurityFilterChain we had
Before the incident, the Spring Boot 3 + Java 21 backend had no SecurityFilterChain dedicated to Actuator. It depended on the default behavior of Spring Security 6 and properties in application.yml. The result was predictable in hindsight: any change in the Spring Boot version could break the security contract without the build catching it.
This is what you don't want to have:
# ❌ Ambiguous configuration — what you do NOT want
management:
endpoints:
web:
exposure:
include: "*" # exposes EVERYTHING — terrible in production
endpoint:
health:
show-details: always # stack traces and details to anyone
Spring Boot with include: "*" exposes /actuator/env, /actuator/heapdump, /actuator/threaddump, /actuator/loggers, and a long list. With show-details: always, the health endpoint returns datasource details, dependency status, and internal error messages to any IP.
The problem wasn't just "who can see what?". It was that the model wasn't explicit. Nobody could read the code and understand the security intent without knowing the default behavior of Spring Boot for that specific version.
The resulting SecurityFilterChain: before/after with real code
The rebuild started with a design decision: Actuator needs its own SecurityFilterChain, separate from the application's main chain. Spring Security 6 with Spring Boot 3.x supports this natively with @Order.
// SecurityConfig.java
// Dedicated chain for Actuator — explicit order before the main app chain
@Bean
@Order(1) // Processed before the app chain
public SecurityFilterChain actuatorSecurityFilterChain(HttpSecurity http) throws Exception {
http
// Only applies to Actuator routes
.securityMatcher("/actuator/**")
.authorizeHttpRequests(auth -> auth
// Public health only for Railway/k8s probe — no internal details
.requestMatchers("/actuator/health/liveness").permitAll()
.requestMatchers("/actuator/health/readiness").permitAll()
// General health without details — useful for load balancer
.requestMatchers("/actuator/health").permitAll()
// Info public — only what we explicitly configure in application.yml
.requestMatchers("/actuator/info").permitAll()
// Metrics, env, loggers — ACTUATOR_ADMIN only
.requestMatchers("/actuator/metrics/**").hasRole("ACTUATOR_ADMIN")
.requestMatchers("/actuator/env/**").hasRole("ACTUATOR_ADMIN")
.requestMatchers("/actuator/loggers/**").hasRole("ACTUATOR_ADMIN")
// Everything else in Actuator — also requires ACTUATOR_ADMIN
.anyRequest().hasRole("ACTUATOR_ADMIN")
)
// Actuator doesn't need CSRF — it's an internal API
.csrf(csrf -> csrf.disable())
// HTTP Basic auth for private endpoints — over HTTPS only
.httpBasic(Customizer.withDefaults())
// No session state in Actuator
.sessionManagement(session ->
session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
);
return http.build();
}
// Main application chain — order 2, processes everything else
@Bean
@Order(2)
public SecurityFilterChain appSecurityFilterChain(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests(auth -> auth
.requestMatchers("/api/public/**").permitAll()
.anyRequest().authenticated()
)
// ... rest of app configuration
;
return http.build();
}
The @Order(1) is critical. Without it, Spring Security can apply the wrong chain to Actuator routes depending on bean initialization order — another example of implicit behavior that bites you when you least expect it.
application.yml: what gets exposed and what doesn't
The SecurityFilterChain controls who can access. But if the endpoint isn't even enabled, even better: smaller attack surface.
# application.yml — explicit Actuator configuration
management:
endpoints:
web:
# ✅ Explicit whitelist — only what we actually need
exposure:
include:
- health
- info
- metrics
- loggers
- env
# heapdump and threaddump — disabled in production
# too risky, too much sensitive information in a dump
exclude:
- heapdump
- threaddump
- httptrace
endpoint:
health:
# No details on general health — UP/DOWN only
show-details: never
# Kubernetes/Railway probes separated
probes:
enabled: true
group:
# Liveness group — only what's critical for the process to be alive
liveness:
include:
- livenessState
show-details: never
# Readiness group — datasource + external dependencies
readiness:
include:
- readinessState
- db
show-details: never
# Info: only what we explicitly decide to expose
info:
enabled: true
info:
env:
enabled: false # Don't expose environment variables in /actuator/info
git:
mode: simple # Only commit hash and branch — not the full history
The heapdump point deserves a separate note: a heap dump from a digital identity backend contains tokens, hashed passwords, session data, and potentially cryptographic keys in memory. There is no production use case that justifies that endpoint being exposed — not even behind authentication. We disabled it completely.
Real validation: how to confirm the lockdown actually worked
This is what frustrates me most about generic security posts: they explain the configuration but don't show how to verify that the lockdown actually worked. Because "it works" in dev with spring.profiles.active=dev means nothing for production.
The validation procedure I used, reproducible with any backend:
# 1. Verify that public endpoints respond without credentials
curl -s -o /dev/null -w "%{http_code}" https://my-backend.railway.app/actuator/health
# Expected: 200
curl -s -o /dev/null -w "%{http_code}" https://my-backend.railway.app/actuator/health/liveness
# Expected: 200
curl -s -o /dev/null -w "%{http_code}" https://my-backend.railway.app/actuator/info
# Expected: 200
# 2. Verify that private endpoints reject without credentials
curl -s -o /dev/null -w "%{http_code}" https://my-backend.railway.app/actuator/metrics
# Expected: 401 (not 200, not 403 with details)
curl -s -o /dev/null -w "%{http_code}" https://my-backend.railway.app/actuator/env
# Expected: 401
# 3. Verify that disabled endpoints don't exist
curl -s -o /dev/null -w "%{http_code}" https://my-backend.railway.app/actuator/heapdump
# Expected: 404 (not 401 — the endpoint doesn't exist, it's not just protected)
# 4. Verify access with valid credentials for ACTUATOR_ADMIN
curl -s -u "actuator-admin:SECURE_PASSWORD" \
https://my-backend.railway.app/actuator/metrics \
| jq '.names[:5]'
# Expected: list of available metrics
# 5. Verify that incorrect credentials return 401, not useful information
curl -s -u "admin:wrong" https://my-backend.railway.app/actuator/metrics
# Expected: 401 with no body containing error details
Point 3 is the most important and the most commonly skipped: there's a real difference between an endpoint that returns 401 and one that returns 404. If /actuator/heapdump returns 401, it exists but is protected. If it returns 404, the endpoint is disabled — attack surface effectively eliminated, not just covered.
Common mistakes when configuring this in Spring Boot 3
Mistake 1: Trusting management.server.port as security
Moving Actuator to an internal port (e.g., 8081) looks like a solution, but on Railway, Fly.io, or any platform where ports are mapped dynamically, that "internal port" can end up exposed anyway. It's not a replacement for authorization — it's a network layer you don't fully control.
Mistake 2: Using hasAuthority instead of hasRole
Spring Security 6 automatically prefixes roles with ROLE_ when you use hasRole("ACTUATOR_ADMIN"). If you mix hasAuthority("ACTUATOR_ADMIN") and hasRole("ACTUATOR_ADMIN") in the same chain, you'll get inconsistent behavior that's a nightmare to debug. Pick one and be consistent throughout the entire model.
Mistake 3: The Actuator chain without securityMatcher
If you create a SecurityFilterChain for Actuator without securityMatcher("/actuator/**"), Spring Security will apply it to all routes according to order. @Order(1) without the matcher is a ticking time bomb.
Mistake 4: show-details: when_authorized with the wrong model
when_authorized seems like the balanced option, but its behavior depends on who is "authorized" according to Spring Security at that moment. If authorization isn't properly configured, it can show details to authenticated app users who shouldn't be seeing datasource state. never for the public endpoint, always only on the protected endpoint — that's more predictable.
Mistake 5: Not checking what /actuator/env actually exposes
The /env endpoint on a typical backend exposes environment variables, Spring properties, and resolved values. That includes DATABASE_URL, JWT_SECRET, REDIS_PASSWORD — any variable you've defined in the environment. Even behind authentication, you need to think carefully about who holds the ACTUATOR_ADMIN role in production.
FAQ: Spring Boot Actuator Security and Spring Security in production
Why do I need a separate SecurityFilterChain for Actuator instead of just properties in application.yml?
The management.endpoints properties control which endpoints are enabled and exposed. The SecurityFilterChain controls who can access them and with what credentials. They're two orthogonal layers. You can disable an endpoint from application.yml and Spring Security never sees it — that's fine. But relying only on properties without an explicit chain means your security behavior is coupled to the defaults of whichever version of Spring Boot you're running, which change between minor versions.
What role should the ACTUATOR_ADMIN user have?
In Spring Security 6, hasRole("ACTUATOR_ADMIN") expects the user to have the authority ROLE_ACTUATOR_ADMIN. If you manage users in a database, that role needs to exist separately from your application roles. Ideally it's a dedicated technical user, with credentials rotated periodically, used only for internal observability — never the same user the app uses at runtime.
How do I handle Railway or Kubernetes health probes without exposing internal details?
With Spring Boot 3's health groups: management.endpoint.health.group.liveness and management.endpoint.health.group.readiness. Each group exposes /actuator/health/liveness and /actuator/health/readiness respectively. These can be public (permitAll() in the chain) with show-details: never — they only return {"status":"UP"} or {"status":"DOWN"} with zero internal detail. The general health at /actuator/health can also be public but equally detail-free.
Is it safe to have /actuator/info public?
Depends on what you expose in that endpoint. By default, Spring Boot can expose the Java version, the Spring Boot version, Git information, and environment variables prefixed with info.. That last one is the problem: if you have INFO_SOMETHING=sensitive_value in your environment, it can show up. With management.info.env.enabled: false and management.info.git.mode: simple you can have a public /actuator/info that only returns commit hash, branch, and artifact version — enough for operational debugging, nothing sensitive.
How do I integrate this with an API Gateway that already handles authentication?
If the backend sits behind a gateway (Kong, AWS API Gateway, your own Nginx), the temptation is to assume the gateway protects everything and relax the backend's authorization model. Don't. The defense in depth principle says every layer has to be secure independently. The gateway can go down, can be misconfigured, can have a bypass. The backend has to survive on its own.
How do I validate that Spring Security is actually processing Actuator routes and not the wrong chain?
With Spring Security's debug log. Enable logging.level.org.springframework.security: DEBUG in a staging environment, make a request to /actuator/metrics without credentials, and look in the log for which SecurityFilterChain was selected. You'll see something like Trying to match request against ... DefaultSecurityFilterChain. If the chain that shows up isn't the Actuator one, your @Order or securityMatcher is wrong. That's the only reliable diagnostic.
My take after rebuilding this
Locking down endpoints isn't enough. Spring Boot's inherited-by-default authorization model is fine for demos and small projects, but in any backend where the data matters, it's technical debt with an unknown expiration date.
What's still standing after rebuilding this is a model where every rule has an explicit intent that's readable in the code. Anyone who opens the SecurityFilterChain can understand what's protected, why, and with what credentials — without needing to know the defaults of the specific Spring Boot version being used.
If you're running Spring Boot Actuator in production and you've never written an explicit SecurityFilterChain for it, now is the time. Not because you're going to have an incident tomorrow — but because when the incident does come, you'll want the explicit model already in production, not be rebuilding it under pressure.
For the broader context of how I handle infrastructure security across different layers of the stack, you can also check out the encryption analysis with Themis vs Web Crypto API and the post on Jakarta EE vs Spring Boot in real production backends.
Original source:
- Spring Boot Docs — Securing HTTP Endpoints: https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html#actuator.endpoints.security
This article was originally published on juanchi.dev
Top comments (0)