11 Securing Management and Health Services

Protect administrative listeners, invocation targets, Reporter resources, health mutators, and connector discovery.

Inventory Management over REST, JMX/RMI, JMXMP, health, and metrics as separate surfaces. Limit their interfaces and network reachability to the required administrators or monitoring systems. Configure authentication and TLS appropriate to each listener; a secured cache client does not secure an independently exposed management endpoint.

Use Management Authentication and Compatibility for profile-aware defaults and explicit overrides, Securing JMX Connectors and Reporter for non-HTTP paths, and Securing Health Administration for route-local health mutation policy. Metrics retains its own chapter and scraper recipe.

Administrative dispatch policy

Management REST permits only the supported JFR diagnostic operations jfrStart, jfrStop, jfrDump, and jfrCheck. Unsupported names are invalid route input and return 400 before diagnostic invocation. Wrapped JMX retains its documented compatibility operation for pre-JDK-11 JFR workflows; this is not a general-purpose command interface.

Management invocation checks restrict product function classes, concrete MBean targets, arguments, descriptors, readable/writable attributes, and supported operations. A wildcard ObjectName query is a selection pattern, not authority to invoke every result. Concrete results are validated before use. Direct JMX/TCMP routes converge on the relevant sink policy; REST pre-validation alone does not replace it.

Operational verification

Test each actual path used by administrators, including Reporter scheduled execution and external JMX tools. A harmless HTTP GET does not exercise mutation, diagnostic, file-output, or TCMP invocation policy. Collect the dedicated management/Reporter warnings as well as serialization/executable signals.

Management Authentication and Compatibility

Configure explicit management and metrics authentication and account for compatibility-sensitive administrative behavior.

Management security follows the same two-axis contract. coherence.mode=dev|prod remains the runtime/license choice. Starting with Coherence 26.1.0.0, an unset coherence.security.mode selects hardened and enforces the compatibility-sensitive management gates. Explicit coherence.security.mode=compatibility preserves the older behavior and emits bounded shadow warnings where available. Several management floors apply in both profiles.

Property Owner and default Override, signal, and rolling-upgrade note
coherence.management.http.auth Security mode owns the shipped management HTTP default: none in compatibility and basic in hardened mode. Runtime DEV/PROD does not change that choice. Set an explicit supported HTTP auth method, including basic, cert, cert+basic, or the compatibility escape none. A resolved none emits a startup WARN. Apply the same explicit setting and credentials to each endpoint before changing the security profile during a rolling restart.
coherence.metrics.http.auth Security mode owns the shipped metrics HTTP default: none in compatibility and basic in hardened mode. Runtime DEV/PROD does not change that choice. Set an explicit supported HTTP auth method. Explicit none remains available and emits a startup WARN. Update scrapers and every metrics endpoint before a hardened rolling restart so mixed members do not alternate between open and authenticated scrape behavior.
coherence.health.http.mutators.enabled Explicit and mode-independent; default false. Only PUT /suspend* and PUT /resume* are mutators. Read-only health probes remain unauthenticated. Set true on each member that must expose mutators. Disabled requests are rejected with a bounded WARN. There is no security-mode default flip, so stage enablement per member during a rolling restart.
coherence.health.http.auth Explicit and mode-independent. Once mutators are enabled, an absent or blank value defaults to basic; supported values are basic, cert, and cert+basic. Configure credentials or TLS peer identity before enabling mutators. none, unknown values, and missing required identity fail closed and log only bounded rejection information. Configure authentication on every enabled member; this gate authenticates administrative access but does not add role-based authorization.
coherence.management.report.remote.allowed Security mode owns unapproved remote Reporter sources. Compatibility permits them with a structured result=would_reject WARN; hardened mode rejects them. The property is unset by default. Set a comma-separated list of exact http or https scheme/host authorities, including a port when non-default. Approved sources are accepted without a less-secure warning. Use one allowlist across Reporter members before enabling hardened mode; otherwise the same report can succeed on one member and fail on another.
coherence.reporter.output.directory Explicit root with mode-sensitive enforcement; default is the process working directory. Compatibility can allow an existing output path outside the root with a structured result=would_reject WARN, while hardened mode rejects it. Traversal and final-file root escape remain hard failures. Set a canonical approved output directory and move existing report targets under it. Use a path valid on every Reporter member before a rolling security profile change. Normal in-root writes emit no policy warning.
coherence.jmxmp.host Explicit and mode-independent; default 127.0.0.1. Set a deliberate non-loopback address only when remote JMXMP access is required. A wider bind has no dedicated policy warning, so protect it with network controls and the mandatory authenticator. Configure each member before exposing its listener.
coherence.jmxmp.port Explicit and mode-independent; default 9000. Set the required listener port on each JMXMP member. The port does not weaken authentication or serial-filter requirements and has no less-secure warning.
coherence.jmxmp.authenticator Explicit and mode-independent; no default. JMXMP startup fails closed when neither this property nor the remote-management fallback names a valid JMXAuthenticator. Set a JMXAuthenticator implementation class. Configure it before enabling or widening JMXMP on each member. Startup failure, rather than a compatibility shadow, is the missing-authenticator signal.
coherence.management.remote.authenticator Explicit and mode-independent; no default. It configures JMX RMI authentication and is the fallback authenticator for JMXMP. Set a JMXAuthenticator implementation class on every remote-management member. JMX RMI has no absent-authenticator policy WARN; an invalid class logs an error and does not produce authenticated connector attributes. JMXMP still fails closed if the fallback is absent or unusable.
coherence.management.remote.registryport Explicit remediation for management JMX publication. When absent, the cluster management connector can produce a dynamic /stub/... URL. Compatibility permits that URL with a bounded result=would_reject warning; hardened mode rejects its publication. Runtime DEV/PROD does not change the decision. Set a registry port, commonly 9000, before hardened rollout so publication uses a static /jndi/rmi://.../server URL. Configure all publishing members before changing the security profile; otherwise hardened members can reject URLs still produced by compatibility-profile members.

Verifying Compatibility Shadows

Before enabling hardened security mode, keep the intended runtime coherence.mode unchanged and exercise management TCMP, Reporter, management HTTP, metrics, health administration, and JMX publication in compatibility security mode. Inspect two separate signal families:

  • coh.executable.policy_check{result=would_reject,...} is emitted only by paths that call DefaultRemoteExecutablePolicy.enforce(...). It identifies unclassified remote executable classes; it is not a complete management hardening audit.

  • ManagementInvocationPolicy and ReporterSecurity emit separate bounded structured WARN lines with result=would_reject. These warnings cover management invocation and Reporter policy decisions and do not increment the executable-policy counter. Dynamic JMX /stub/... publication also emits its own bounded compatibility warning.

Classify legitimate remote executables, approve Reporter sources and output roots, set a static RMI registry port, and configure endpoint authentication. Then rerun the full workflow with coherence.security.mode=hardened in pre-production. During a rolling change, keep members serving the same external endpoint on one security profile where practical; mixed profiles can accept and reject the same request differently.

Parent topic: Securing Management and Health Services

Securing JMX Connectors and Reporter

Configure authenticated connectors and deliberate report-source, output, and MBean-target boundaries.

JMXMP

The product JMXMP server defaults to 127.0.0.1:9000. A non-loopback bind is an explicit exposure decision. The connector requires a usable JMXAuthenticator, configured with coherence.jmxmp.authenticator or the supported coherence.management.remote.authenticator fallback. Missing or invalid authentication configuration prevents safe connector startup. 

-Dcoherence.management.serverfactory=com.tangosol.net.management.JmxmpServer
-Dcoherence.jmxmp.host=127.0.0.1
-Dcoherence.jmxmp.port=9000
-Dcoherence.jmxmp.authenticator=com.example.security.AdminAuthenticator

AdminAuthenticator is an application javax.management.remote.JMXAuthenticator implementation that validates credentials using the approved identity service and returns a verified subject. Configure the provider-specific TLS/SASL profile supported by the installed JMXMP implementation before exposing it remotely. An authenticator supplies authentication; it does not itself encrypt the connection or implement a complete MBean role policy.

Before creating the connector, Coherence uses an existing JVM-wide ObjectInputFilter or installs a constrained fallback and verifies its presence. The fallback affects the JVM, not only a single connector. Review it with other libraries, their required serializable values, and the supported JDK filter policy. It is inaccurate to assume that an absent preconfigured filter always causes failure; inability to install or observe a filter does fail startup.

JMX/RMI and discovery

Configure the supported remote authenticator and a deliberate registry port. In hardened mode, dynamic /stub/... management connector publication is rejected; configure coherence.management.remote.registryport so publication uses a static /jndi/rmi://.../server form. Apply the configuration on all publishing members before profile activation. Restrict registry and connector network access and use the supported provider's transport security.

Reporter inputs and output

Use approved local report configuration and a dedicated canonical output root. coherence.reporter.output.directory defaults to the working directory. Move output under the approved root before enabling hardened enforcement. Traversal, invalid output protocols, and final-file escapes remain hard failures where documented.

Approve necessary remote HTTP(S) report authorities with coherence.management.report.remote.allowed, using exact scheme/host authorities and a non-default port when needed. Approval controls source policy; protect transport, remote content, and redirects independently according to supported Reporter behavior. Avoid approving a broad network merely to silence a warning.

Report queries, concrete ObjectNames, method-column provenance, and custom column classes have their own policy checks. Broad patterns do not bypass concrete target validation. Validate the scheduled report through the same JMX/TCMP path used in production, and confirm an unapproved source and outside-root output are rejected under hardened policy.

Parent topic: Securing Management and Health Services

Securing Health Administration

Keep read-only probes available while enabling authenticated suspend/resume routes only where needed.

Health mutators are disabled by default in both security profiles. Only the supported PUT /suspend* and PUT /resume* routes are mutators; ordinary read-only health probes remain unauthenticated. Apply network controls appropriate to even read-only operational information. 

-Dcoherence.health.http.mutators.enabled=true
-Dcoherence.health.http.auth=basic

Enable mutators only on the intended members, with TLS and valid credentials already configured. Once enabled, absent/blank auth defaults to basic; supported methods are basic, cert, and cert+basic. none, unknown methods, and missing required identity fail closed. A disabled mutator is rejected with a bounded warning.

This route policy authenticates administrative access; it does not create a new role-based health authorization model. If only a subset of authenticated identities may administer health state, enforce the required restriction in the approved identity/ingress architecture and verify it explicitly.

Test readiness/liveness requests without credentials, a disabled mutator, enabled mutators without/with incorrect credentials, and an authorized suspend/resume pair on an isolated member. Keep the member available for recovery if the test intentionally suspends a service. Coordinate monitoring and load balancers with the resulting state changes.

Parent topic: Securing Management and Health Services

About Securing Oracle Coherence HTTP Management Server

Select management HTTP authentication explicitly and match its security-profile default to the deployment.

Starting with Coherence 26.1.0.0.0, the default hardened profile makes the shipped management HTTP authentication default basic. Explicit compatibility mode uses none. Set coherence.management.http.auth deliberately during migration. A successful login does not replace authorization for the administrative operation. See Management Authentication and Compatibility.

Coherence HTTP Management Server authentication support includes: HTTP basic, client-side SSL certificate, and client-side SSL certificate together with HTTP basic.

See Accessing Management Information Using REST in Managing Oracle Coherence.

Parent topic: Securing Management and Health Services

Basic Authentication for Coherence HTTP Management Server HTTP Acceptor

You can configure an HTTP acceptor to provide authentication for Coherence HTTP Management Server.

HTTP basic authentication provides authentication using credentials (user name and password) that are encoded and sent in the HTTP authorization request header.

This section includes the following topics:

Parent topic: Securing Management and Health Services

Specify the Basic Authentication for Coherence HTTP Management Server HTTP Acceptor

The default management-http-config.xml is in coherence-management.jar.

To specify basic authentication for an HTTP Management Acceptor, set the coherence.management.http.auth system property to the value basic or override the default management-http-config.xml and specify <auth-method> child xml element to the value basic.

Parent topic: Basic Authentication for Coherence HTTP Management Server HTTP Acceptor

Specify a Coherence HTTP Management Server Login Module

Configure and verify the JAAS identity path used by the management HTTP server.

For the standard Coherence HTTP server's Basic path, configure the CoherenceREST JAAS entry with the module that validates administrator credentials. The entry name follows the actual HTTP identity asserter; it is not inferred from the management endpoint's display name. A custom provider can define another contract.

Deploy the module and dependencies through the supported runtime classpath/module path and select the protected JAAS file with java.security.auth.login.config. Use the provided keystore module only where a provisioned keystore identity is appropriate. Current JDKs do not use the former JRE extension-directory installation mechanism.

Configure management TLS, network placement, and the intended authorization restrictions separately. Verify missing/invalid credentials and a legitimate administrative request. Review Management Authentication and Compatibility before changing profile-sensitive defaults.

Parent topic: Basic Authentication for Coherence HTTP Management Server HTTP Acceptor

Using SSL Authentication With Oracle Coherence HTTP Management Server

You can use SSL to provide authentication for Coherence HTTP Management Server. SSL provides an authentication mechanism that relies on digital certificates and encryption keys to establish both identity and trust. See Overview of SSL/TLS.

Client-side SSL certificates are passed to the HTTP acceptor to authenticate the client. SSL requires an SSL-based socket provider to be configured for the HTTP acceptor.

This section includes the following topics:

Parent topic: Securing Management and Health Services

Configure a Coherence HTTP Management Acceptor SSL Socket Provider

Configure an SSL socket provider for an HTTP acceptor when using SSL for authentication. To configure SSL for an HTTP acceptor, explicitly add an SSL socket provider definition or reference an SSL socket provider definition that is in the operational override file.

Explicitly Defining an SSL Socket Provider

To explicitly configure an SSL socket provider for an HTTP acceptor, add a <socket-provider> element within the <http-acceptor> element of each <proxy-scheme> definition. See socket-provider in Developing Applications with Oracle Coherence. You can override the default values by extracting management-http-config.xml from coherence.jar, modifying the file and then placing it before coherence.jar on the class path. You can also specify the socket provider by using the override -Dcoherence.management.http.provider=your-socket-provider.

Example 12-1 demonstrates configuring an SSL socket provider that uses the default values for the <protocol> and <algorithm> element (TLS and SunX509, respectively). These are shown for completeness but may be left out when using the default values.

Example 12-1 configures both an identity keystore (server.jks) and a trust keystore (trust.jks). This is typical of two-way SSL authentication, in which both the client and proxy must exchange digital certificates and confirm each other's identity. For one-way SSL authentication, the proxy server configuration must include an identity keystore but need not include a trust keystore.

Example 11-1 Sample HTTP Acceptor SSL Configuration

<proxy-scheme>
   <service-name>ManagementHttpProxy</service-name>
   <acceptor-config>
      <http-acceptor>
         ...
        <socket-provider>
	   <ssl>
            <protocol>TLS</protocol>
            <identity-manager>
              <algorithm>SunX509</algorithm>
              <provider system-property="coherence.management.http.security.keystore.provider"/>
              <key-store>
                <url system-property="coherence.management.http.security.keystore">file:server.jks</url>
                <password system-property="coherence.management.http.security.keystore.password"/> 
                <type>JKS</type>
              </key-store>
              <password system-property="coherence.management.http.security.identitymanager.password”/> 
            </identity-manager>
            <trust-manager>
              <algorithm>SunX509</algorithm>
              <provider system-property="coherence.management.http.security.truststore.provider"/>
              <key-store>
                <url system-property="coherence.management.http.security.truststore">file:truststore.jks</url>
                <password system-property="coherence.management.http.security.truststore.password"/>
                <type>JKS</type>
              </key-store>
            </trust-manager>
          </ssl>
        </socket-provider>
         ...
        <auth-method>cert</auth-method>
      </http-acceptor>
   </acceptor-config>
   <autostart>true</autostart>
</proxy-scheme>

Referencing an SSL Socket Provider Definition Using Coherence HTTP Management Over REST

The following example references an SSL socket provider configuration that is defined in the <socket-providers> element of the operational deployment descriptor by specifying the id attribute (ssl) of the configuration. See socket-providers in Developing Applications with Oracle Coherence.

Note:

A predefined SSL socket provider is included in the operational deployment descriptor and is named ssl. The predefined SSL socket provider is configured for two-way SSL connections and is based on peer trust, in which every trusted peer resides within a single JKS keystore. See Coherence PeerX509 Algorithm. To configure a different SSL socket provider, use an operational override file to modify the predefined SSL socket provider or to create a socket provider configuration as required. 

<proxy-scheme>
  <service-name>ManagementHttpProxy</service-name>
  <acceptor-config>
        <http-acceptor>
           ...
           <socket-provider>ssl</socket-provider>
           ...
           <auth-method>cert</auth-method>
        </http-acceptor>
   </acceptor-config>
   <autostart>true</autostart>
</proxy-scheme>

For configuring HTTP client access, see Access Secured REST Services.

Parent topic: Using SSL Authentication With Oracle Coherence HTTP Management Server