12 Securing Oracle Coherence Metrics

Authenticate scrapers, protect metric transport, and coordinate endpoint policy across members.

Metrics exposes operational information on its own HTTP endpoint. Restrict its bind/network placement to the intended scrapers and operators. Configure TLS and the required Basic, client-certificate, or combined authentication supported by the acceptor.

Starting with Coherence 26.1.0.0, the default hardened profile makes the shipped metrics HTTP authentication default basic. Explicit compatibility mode uses none, subject to operator XML/property configuration. An explicit none override remains available and emits a warning. Configure credentials and scraper behavior before upgrading; a load-balanced scrape must not alternate unexpectedly between open and authenticated members.

Use Configuring an Authenticated TLS Metrics Scrape. The retained endpoint and client topics provide HTTP acceptor placement. Read-only metrics, management mutation, and health administration remain different surfaces with different controls.

• Configuring an Authenticated TLS Metrics Scrape
  Use CA-verified HTTPS and a protected credential source for the metrics scraper.
• About Securing Oracle Coherence Metrics
  Select metrics authentication explicitly and account for shipped profile-sensitive defaults.
• Basic Authentication for Coherence Metrics Http Acceptor
  You can configure an HTTP acceptor to provide authentication for Coherence Metrics.
• Using SSL Authentication With Oracle Coherence Metrics
  You can use SSL to provide authentication for Coherence Metrics. SSL provides an authentication mechanism that relies on digital certificates and encryption keys to establish both identity and trust.

Configuring an Authenticated TLS Metrics Scrape

Use CA-verified HTTPS and a protected credential source for the metrics scraper.

Configure the metrics HTTP acceptor with the chosen named TLS socket provider and coherence.metrics.http.auth=basic for this recipe. Provide a working CoherenceREST JAAS entry for the standard HTTP server's Basic path, or configure the supported replacement identity integration. Choose a least-privilege scraper identity and the actual member/service DNS names.

The following Prometheus fragment uses HTTPS, CA verification, and a mounted password file. Replace the example target/port with the endpoint configured in this deployment and verify the Prometheus version's configuration syntax.

scrape_configs:
  - job_name: coherence
    scheme: https
    static_configs:
      - targets: ["metrics.example.com:9612"]
    basic_auth:
      username: coherence-scraper
      password_file: /run/secrets/coherence-metrics-password
    tls_config:
      ca_file: /run/coherence/metrics-ca.pem

For certificate authentication, configure the scraper's client certificate and key and the acceptor's corresponding trust/identity mapping. Do not disable certificate verification or reuse an administrator's credential merely to make scraping work.

Verify a successful scrape, missing/wrong credentials, an unrelated CA, and a server-name mismatch. Repeat through any load balancer and across all endpoints during rolling restart. Rotate the credential/certificate with the scraper's supported reload lifecycle, verify fresh requests, and retire old material after the overlap required by the endpoint fleet.

About Securing Oracle Coherence Metrics

Select metrics authentication explicitly and account for shipped profile-sensitive defaults.

Use a secured listener and a deliberately configured scraper identity for operational metrics. Supported HTTP acceptor methods include Basic, certificate, and combined authentication. The shipped profile-sensitive default is basic under the hardened profile, which is the default starting with Coherence 26.1.0.0; explicit compatibility mode uses none. Operator configuration can override that default.

Set coherence.metrics.http.auth explicitly when the deployment requires a stable endpoint policy across rolling changes. Configure the corresponding JAAS or certificate identity path and TLS provider. Verify the authenticated client and a denied unauthenticated request with Configuring an Authenticated TLS Metrics Scrape.

Basic Authentication for Coherence Metrics Http Acceptor

You can configure an HTTP acceptor to provide authentication for Coherence Metrics. 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:

• Specify Basic Authentication for Coherence Metrics HTTP Acceptor
  
• Specify a Coherence Metrics Login Module
  Configure the JAAS entry used by the standard metrics HTTP Basic authentication path.
• Specify Basic Authentication for a Coherence Metrics HTTP Client
  

Specify Basic Authentication for Coherence Metrics HTTP Acceptor

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

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

Specify a Coherence Metrics Login Module

Configure the JAAS entry used by the standard metrics HTTP Basic authentication path.

The standard Coherence HTTP server's Basic identity asserter uses the CoherenceREST JAAS entry. Configure a module that validates the scraper's credentials and deploy its runtime dependencies through the supported classpath/module path. Verify another entry name only when using a custom HTTP integration that actually selects it.

Protect the JAAS file and secret sources. Current JDKs do not support the former JRE extension-directory mechanism for installing login modules. Set explicit metrics authentication and TLS, and configure the scraper using Configuring an Authenticated TLS Metrics Scrape. Verify wrong/missing credentials and member-by-member rollout behavior.

Specify Basic Authentication for a Coherence Metrics HTTP Client

Prometheus is an HTTP client metrics gathering system that can be configured to scrape metrics data from a Coherence metrics endpoint.

See Prometheus <scrape_config> configuration for parameters on configuring scheme to https, basic_auth with username and password.

Using SSL Authentication With Oracle Coherence Metrics

You can use SSL to provide authentication for Coherence Metrics. 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:

• Configure a Coherence Metrics HTTP Acceptor SSL Socket Provider
  

Configure a Coherence Metrics HTTP 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 metrics-http-config.xml by making a copy of it and placing the revised metrics-http-config.xml in classpath before coherence-metrics.jar occurs.

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 12-1 Sample HTTP Acceptor SSL Configuration

<proxy-scheme>
   <service-name>MetricsHttpProxyService</service-name>
   <acceptor-config>
      <http-acceptor>
         ...
        <socket-provider>
	   <ssl>
            <protocol>TLS</protocol>
            <identity-manager>
              <algorithm>SunX509</algorithm>
              <provider system-property="coherence.metrics.security.keystore.provider"/>
              <key-store>
                <url system-property="coherence.metrics.security.keystore">file:server.jks</url>
                <password system-property="coherence.metrics.security.keystore.password"/> 
                <type>JKS</type>
              </key-store>
              <password system-property="coherence.metrics.security.identitymanager.password”/> 
            </identity-manager>
            <trust-manager>
              <algorithm>SunX509</algorithm>
              <provider system-property="coherence.metrics.security.truststore.provider"/>
              <key-store>
                <url system-property="coherence.metrics.security.truststore">file:truststore.jks</url>
                <password system-property="coherence.metrics.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 Metrics

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>MetricsHttpProxy</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>

Configuring HTTP Client-Side in Prometheus Configuration

Prometheus is an HTTP client metrics gathering system that is used to scrape the Coherence Metrics endpoints. See Prometheus <scrape_config> configuration for parameters to configure scheme to https and basic_auth with username and password. See Prometheus <tls_config> configuration to configure TLS connections.