Actuators: Types, Operation, Selection, and Control

Spring Boot Actuator Configprops Endpoint

Learn how Spring Boot Actuator's configprops endpoint exposes bound configuration-properties beans, how to inspect values safely, and how to troubleshoot binding and exposure problems.

The Spring Boot Actuator configprops endpoint reports configuration-properties beans registered in a running application. It is useful when you need to confirm that external configuration was bound to the typed Java objects your application uses.

This endpoint does not show every property source in the application. Instead, it shows the configuration-properties beans and their effective bound values. Use the env endpoint when you need to inspect environment property sources, candidate values, and precedence.

What the configprops endpoint does

Spring Boot Actuator is a Spring Boot module that provides production monitoring and management endpoints. The configprops endpoint is one of those endpoints.

A configuration-properties bean is a typed object populated from externalized configuration: settings supplied outside application code through configuration files, environment variables, command-line arguments, config trees, and other property sources.

For example, a bean with the prefix app.mail can receive values from properties such as app.mail.host and app.mail.port. The endpoint reports the registered bean, its prefix, and the values that were successfully bound.

• Verify that a property reached the intended Java object.
• Find the configuration-property prefixes active in a deployed application.
• Detect unexpected defaults.
• Confirm effective configuration at runtime.
• Inspect nested objects, collections, and maps when diagnosing configuration.

Prerequisites and endpoint availability

Add the Actuator starter to the application. The exact version should match the Spring Boot version used by the application.

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

implementation("org.springframework.boot:spring-boot-starter-actuator")

The application must also have configuration-properties beans. These are commonly declared with @ConfigurationProperties and registered using @ConfigurationPropertiesScan, @EnableConfigurationProperties, or component registration where supported by the application design.

Two separate settings affect an Actuator endpoint:

• Enabled: Actuator permits the endpoint to operate.
• Exposed: the endpoint is made available through a transport such as HTTP or JMX.

An enabled endpoint that is not exposed over HTTP still returns no HTTP response because it is not available through that transport. Conversely, including an endpoint in web exposure does not bypass security controls.

management.endpoints.web.exposure.include=configprops
management.endpoints.web.base-path=/actuator

The usual HTTP path is /actuator/configprops. A custom management base path changes that URL. A dedicated management port also changes where the request must be sent.

management.server.port=8081

Servlet and reactive applications can both expose Actuator endpoints over HTTP, but details of endpoint behavior and configuration keys can vary between Spring Boot releases. Verify the settings and response format against the deployed version.

Accessing the endpoint

With the default management base path and application port, open the endpoint in a browser:

http://localhost:8080/actuator/configprops

An HTTP client can retrieve the same JSON response:

curl -u user:password http://localhost:8080/actuator/configprops

Management platforms, service checks, and application-management tooling can call the endpoint in the same way, provided they have network access and authorization.

When Actuator discovery is enabled, the management root commonly provides links to exposed endpoints. Follow the discovery link rather than assuming the default path when a custom base path or management port is in use.

Some Spring Boot versions support a prefix-based selector path for a specific configuration-properties group:

curl -u user:password http://localhost:8080/actuator/configprops/app.mail

Use this only when supported by the deployed version. If it is unsupported, retrieve the full report and filter the JSON by prefix or bean identifier locally, while protecting any sensitive output.

Example configuration-properties bean

The following class represents mail settings under the app.mail prefix:

@ConfigurationProperties(prefix = "app.mail")
public class MailProperties {
    private String host = "localhost";
    private int port = 25;
    private String username;
    private Duration timeout = Duration.ofSeconds(5);
    private Tls tls = new Tls();

    public static class Tls {
        private boolean enabled;
        // getters and setters
    }
    // getters and setters
}

Register it with scanning:

@SpringBootApplication
@ConfigurationPropertiesScan
public class Application {
}

Equivalent registration can use @EnableConfigurationProperties(MailProperties.class). A configuration-properties class must be registered in the application context before it appears in the report.

Example external configuration:

app:
  mail:
    host: smtp.internal
    port: 587
    username: service-mailer
    timeout: 8s
    tls:
      enabled: true

The report should contain an entry whose prefix is app.mail. Inspect the host, port, timeout, and nested TLS value to confirm that the deployed settings reached the application.

Understanding the response structure

The response is JSON. Applications with more than one Spring application context can show a top-level contexts object. Each context contains the configuration-properties bean entries associated with that context.

{
  "contexts": {
    "application": {
      "beans": {
        "app.mail-com.example.MailProperties": {
          "prefix": "app.mail",
          "properties": {
            "host": "smtp.internal",
            "port": 587,
            "timeout": "8s",
            "tls": {
              "enabled": true
            }
          }
        }
      }
    }
  }
}

Nested configuration classes appear as nested JSON objects. Collections appear as arrays or indexed values, and maps appear as JSON objects with their keys. The exact formatting and origin fields can differ between Spring Boot versions.

Names in the report do not always match external property spelling. Java property names, canonical configuration names, and relaxed binding rules are involved. For example, a Java property named maxConnections can bind from the canonical key max-connections.

Values may come from defaults in the Java class, configuration files, profile-specific files, environment variables, command-line arguments, config trees, system properties, or other property sources. The configprops report normally shows the effective value after binding, not every losing candidate value.

Configuration-properties binding concepts

@ConfigurationProperties associates a typed Java object with a configuration prefix. Spring Boot converts strings and structured values into Java types such as numbers, durations, data sizes, enums, nested objects, collections, and maps.

Relaxed binding allows equivalent naming styles across sources:

Nested configuration classes organize related settings. Immutable configuration classes can use constructor-based binding where supported by the Spring Boot version. Validation annotations can reject invalid values during startup, and field initializers or constructor defaults provide fallback values when no external value is supplied.

Filtering and targeted inspection

Start by searching the report for the expected prefix, such as app.mail or app.storage. If the prefix is not obvious, search for the configuration class name or bean identifier.

• Confirm the entry has the expected prefix.
• Inspect the direct property containing the suspected problem.
• Expand nested objects and collections.
• Check whether the value is the intended override or a class default.
• Use origin information, when present, to identify the source of the effective value.

For app.storage, inspect values such as bucket, region, and nested credentials or endpoint settings. A present bean with an unexpected value indicates a binding, source, or precedence issue; a missing bean usually indicates registration, scanning, profile, or artifact trouble.

Handling sensitive values

Configuration reports can reveal passwords, tokens, connection strings, internal hostnames, bucket names, feature flags, and other operational details. Actuator applies sanitization to values whose key names match recognized sensitive patterns, replacing the value with a masked representation.

Default matching is based on key names. A custom property such as app.mail.privateCredential might not be recognized as sensitive in every version or configuration. Add custom keys or patterns using the version-appropriate management endpoint sanitization setting. A commonly used setting is:

management.endpoint.env.keys-to-sanitize= password,secret,key,token,credential

Confirm the exact property name and supported pattern behavior in the documentation for the Spring Boot version being deployed. Sanitization configuration has evolved, and settings can apply to endpoint reports differently across releases.

Security and production exposure

Do not publicly expose configprops by default. Use Spring Security rules to restrict management endpoints to approved operators or service identities.

• Expose only the management endpoints required for operations.
• Place management endpoints on a separate port when that fits the deployment architecture.
• Restrict the management port to an internal network, administrative subnet, or private service mesh.
• Require TLS and strong authentication for remote access.
• Give users the least privilege needed for diagnostics.
• Prevent endpoint responses from being copied into public logs, tickets, or monitoring systems.

The trade-off is straightforward: broader visibility can make incident diagnosis faster, but it increases disclosure risk. Prefer narrowly scoped, audited diagnostic access over general public exposure.

Configprops compared with related endpoints

Use configprops to inspect the effective bound object and env to investigate competing sources. For a binding-related auto-configuration problem, add conditions. Use startup information and application logs when the application fails before the endpoint can be queried.

Configuration troubleshooting workflow

1. Confirm availability. Check that Actuator is present, the endpoint is enabled, and HTTP exposure includes configprops.
2. Confirm the route. Check the management base path, dedicated management port, TLS scheme, and any reverse proxy prefix.
3. Authenticate correctly. A 401 means credentials are missing or invalid; a 403 means the identity lacks authorization.
4. Find the expected prefix. Search for the prefix or configuration class identifier.
5. Inspect bound values. Compare each value with the intended deployment configuration, including nested values and collection indexes.
6. Inspect origins. When available, use origin metadata to identify the file, environment variable, command-line argument, or other source.
7. Compare property sources. Use env to investigate candidates and property precedence, the ordering that determines which value wins.
8. Validate profiles and deployment inputs. Check active profiles, mounted files, injected secrets, environment variables, command-line options, and the deployed artifact version.
9. Check startup diagnostics. Binding failures, conversion errors, and validation failures should be reviewed in startup logs and Spring Boot failure analysis.

This process distinguishes several different failures. A 404 usually indicates an availability, exposure, path, or port problem. A missing custom prefix usually indicates that the bean was not registered, scanning missed its package, the context is not active, or the wrong artifact is running. A present bean with a default value usually indicates naming, injection, conversion, profile, or precedence trouble.

Practical example: environment-variable binding

Suppose a bean uses the prefix app.storage and expects the property app.storage.bucket. The corresponding environment variable is:

APP_STORAGE_BUCKET=production-files

If configprops shows the default bucket instead, check the following:

• The deployment actually injects APP_STORAGE_BUCKET into the process.
• The name uses uppercase letters and underscores, with the dash removed from each canonical segment.
• The active profile does not provide a higher-precedence value.
• The application is using the expected artifact and configuration class.
• A mounted secret or config tree is not overriding the environment value.

Then use env to inspect the candidate sources and precedence, and use configprops to confirm the value finally bound to the storage bean.

Practical example: safely masking a custom secret-like property

Assume a configuration bean contains app.integration.privateCredential. If the deployed Spring Boot version does not mask that name by default, configure an additional sanitization key or pattern using the version-supported management endpoint setting:

management.endpoint.env.keys-to-sanitize=privateCredential,credential,token

Test the rule with a non-production value, confirm that the response is masked, and still protect the endpoint with security and network controls. Do not treat a masked report as permission to expose the endpoint to the public internet.

Common access and binding problems

Version and deployment considerations

Actuator response details, selector support, endpoint configuration keys, sanitization behavior, and origin reporting can evolve. Always verify property names and response details against the Spring Boot version actually running.

In containers and cloud platforms, environment-variable naming is especially important. Kubernetes-style environment injection, mounted secrets, config trees, command-line arguments, and platform-specific configuration services can all participate in property precedence. Inspect the runtime process environment and deployment manifest rather than relying only on local files.

A separate management port can simplify network policy, but it is not a security boundary by itself. Apply firewall or security-group rules, TLS, authentication, authorization, and monitoring to that port as well.

Exam-relevant notes

• configprops reports registered @ConfigurationProperties beans, not the complete environment.
• Endpoint enablement and HTTP exposure are separate concepts.
• Relaxed binding permits equivalent naming forms, including environment-variable forms.
• A missing bean is different from a bean containing an unexpected value.
• Use env to investigate property sources and precedence; use configprops to inspect the effective typed object.
• Sanitization reduces value disclosure but does not replace authentication, authorization, network restriction, or secret management.
• Management base paths and management ports can change the URL used to access the endpoint.