
# Security

With `spring_boot_starter_security`, the actuator endpoints pass the security filter chain like any request. `EndpointRequest` matches them without repeating their paths, and `show-details=when-authorized` shows the health details only to users with a role.

## Why

`health` must stay open for the load balancer and Kubernetes; `mappings` and your own endpoints should not. Matching endpoints by id instead of by path keeps the rule right when `management.endpoints.web.base-path` or a path mapping changes.

## Example

```dart
@Configuration()
class ActuatorSecurity {
  // The actuator's own chain: health and info open, the rest for admins.
  @Bean()
  @Order(1)
  SecurityFilterChain actuator(HttpSecurity http) => http
      .securityMatcherOf(EndpointRequest.toAnyEndpoint())
      .authorizeHttpRequests((auth) => auth
          .requestMatchersOf([EndpointRequest.to(['health', 'info'])])
          .permitAll()
          .anyRequest()
          .hasRole('ADMIN'))
      .httpBasic()
      .build();
}
```

```yaml
# lib/resources/application.yml
management:
  endpoints:
    web:
      exposure:
        include: "*"
  endpoint:
    health:
      show-details: when-authorized
      roles: ADMIN
```

```console
$ curl localhost:8080/actuator/health
{"status":"UP"}
$ curl -u admin:secret localhost:8080/actuator/health
{"status":"UP","components":{"diskSpace":{"status":"UP","details":{...}},"ping":{"status":"UP"}}}
```

## EndpointRequest

| Matcher | Matches |
|---|---|
| `EndpointRequest.toAnyEndpoint()` | Every exposed endpoint, and the discovery page |
| `EndpointRequest.to(['health', 'info'])` | Those endpoints, by id |
| `EndpointRequest.toAnyEndpoint().excluding(['health'])` | Every endpoint but those |
| `EndpointRequest.toAnyEndpoint().excludingLinks()` | Every endpoint, not the discovery page |
| `EndpointRequest.toLinks()` | The discovery page only |

`EndpointRequest` is in the security starter. It matches the requests the actuator's web layer recorded (a request attribute set by `webEndpointRequestFilter`), not path patterns of its own, so it follows the base path and path mappings. A path that is not an exposed endpoint (`/actuator/env` while `env` is not exposed) matches nothing and gets the rules of the other matchers.

## when-authorized

`management.endpoint.health.show-details=when-authorized` (and `show-components`, and the same keys of a group) shows the details to a logged-in user with one of `management.endpoint.health.roles`, or to any logged-in user when no role is set. The roles are read from the request's `Authentication`: `ROLE_ADMIN` is the role `ADMIN`. Without the security starter nobody is logged in, so `when-authorized` shows nothing.

## In Spring (Java)

```java
http.securityMatcher(EndpointRequest.toAnyEndpoint())
    .authorizeHttpRequests(auth -> auth
        .requestMatchers(EndpointRequest.to("health", "info")).permitAll()
        .anyRequest().hasRole("ADMIN"));
```

The same matchers and rule; the method names follow the security starter (`securityMatcherOf`, `requestMatchersOf`).

## See also

- [Health](health.md)
- [Endpoints](endpoints.md)
- [spring_boot_starter_security](../spring-boot-starter-security/index.md)
