13 Securing Cluster Peers and Federation

Protect member admission, discovery, advertised topology, federation participants, and authenticated metadata.

Cluster transport and peer identity are foundational trust decisions. Members host trusted code and participate in distributed state changes; a cluster name, role label, host allowlist, or self-advertised proxy address is not cryptographic proof of authority. Restrict membership and deploy appropriate TLS/mTLS or equivalent authenticated peer identity.

Coherence validates relevant pre-trust federation, NameService, membership, and metadata shapes before treating them as operational state. Those controls reduce unsafe materialization and spoofed-state paths, but they do not turn an intentionally unauthenticated deployment into an automatically authenticated cluster.

Discovery and federation

NameService lookup/bind policy constrains resource types and management connector data. Use approved discovery endpoints, expected cluster/service names, and the same network/trust boundaries as the service ultimately contacted. Validate returned proxy/service endpoints; do not treat self-advertised metadata as independent authority.

Federation uses configured participant and endpoint policy. Hardened direct-connect validation rejects an endpoint that cannot be verified against the configured participant contract; compatibility can retain a bounded would-reject path. Keep participant names, expected addresses, identity, and routing consistent on both sides before enabling a stricter policy.

Management discovery has its own safe URL rules. Configure a static management registry URL rather than depending on dynamic serialized RMI stubs in hardened operation. These checks do not replace TLS or credentials on the connector itself.

Subject and senior metadata proofs

Request-subject proofs bind propagated identity to an authorized authority. Senior/topology proofs protect a different authority and recipient relationship. Use Configuring Peer Proof Prerequisites for their configuration, lifecycle, and compatibility boundaries. Required proof without a usable compatible provider fails closed.

Federation replay authorization and proof of a live peer are distinct from cryptographic authentication of stored journal bytes. Do not infer an authenticated snapshot/journal format from these protocol controls.

Configuring Peer Proof Prerequisites

Stage a compatible production proof provider and verify all required producers and recipients before requiring proofs.

Proofs remain opt-in. Hardened mode enforces request-subject proof on a configured authorizer route only when that route requests it. Explicit coherence.security.peer.senior-metadata-proof.required=true fails closed in both security profiles. Neither policy is selected by runtime coherence.mode=prod.

Use only a production provider/profile supported for the deployed release. The bounded X.509 profile described here requires per-member signing identities, separate subject/senior authority sets, stable member binding, and a complete readiness/rotation procedure. Deterministic test providers are not production cryptography. Confirm the supported provider and publication/deployment prerequisites before enabling required policy.

Provider material

The x509-signature-v1 implementation uses protected per-member signing identities and separate subject and senior authorities. Provider enablement and provisioning instructions require a supported, release-qualified operator procedure. Confirm that procedure before configuring the provider or making proof required.

The profile requires RSA keys of at least 2048 bits with SHA-256, non-CA digital-signature leaves, role-specific authority and member binding, certificate-fingerprint key IDs, five-minute proof validity, and two-minute proof/certificate skew. A generic TLS leaf is not automatically a suitable proof authority. Member URI SANs use the profile's exact injective UTF-16-code-unit encoding under urn:coherence:member:utf16be:; use the matching provisioning/profile contract rather than inventing a URI spelling. Duplicate live member identities fail readiness.

The restricted credential loader accepts absolute local regular-file paths or authority-free file: URIs, and rejects symlinks, directories, remote URLs, classpath/JAR resources, and arbitrary handlers. Its bounded profile includes a one-MiB object ceiling, 16 aliases/role leaves, a four-certificate identity chain, 1024 password characters, bounded KDF work, and bounded credential/close operations. Use the approved JCA/backend/password-provider combination; these limits do not authorize arbitrary custom implementations.

Readiness and rollout

  1. Deploy compatible code/configuration to every relevant sender and physical recipient. Include storage-disabled application members that legitimately issue subjects, all relevant service seniors, and ownership-enabled recipients.

  2. Stage the provider while proofs are optional. Verify identities, role authority, expiry, refresh, duplicate detection, and the exact service membership used by the proof workflow.

  3. Use the supported all-member readiness observation for one stable topology epoch. Local provider status alone cannot establish cluster readiness. Joins, leaves, ownership/seniority changes, missing responses, and even a change restored during collection invalidate the observation.

  4. A supported rollout procedure must establish readiness before requiring the desired subject route or senior metadata policy. An absent provider, incompatible peer, or incomplete required initial material must fail closed rather than downgrade.

An authorizer definition requests subject proof with subject-proof-required="true"; the route must also have a configured storage authorizer and the hardened security profile for this enforcement. Senior metadata has its separate required property. Do not publish either setting as a standalone switch that supplies keys or trust automatically.

Rotation and rollback

Add new authority material before activating a new signer, retain the overlap needed by live producers/recipients, verify cluster readiness for add/activate/overlap/retire, and then remove retired authority. Refresh publishes an atomic complete generation; a failed optional staged load may remain unavailable or retain usable last-known-good state according to its lifecycle, while required initial policy fails closed.

A rollback must explicitly address both required policies and compatibility with already active producers/recipients. Changing the runtime mode, or inventing a legacy runtime value, does not disable proof requirements. Preserve protected backups of configuration and key material and test the recovery path before retirement.

Parent topic: Securing Cluster Peers and Federation