Skip to content

Reference: Management Node

Scope

This document describes the components, configuration surface, runtime interfaces, security model, and operational characteristics of a Management Node within the Integration Architecture (IA).

It is intended to be used alongside:

  • How-to: Deploy a Management Node
  • Explanation: Integration Architecture Overview

This document does not provide step-by-step instructions or architectural rationale.

It is a reference surface for configuration, inspection, and troubleshooting.

1. Components

Component Purpose
Management Node (Spring Boot) Governs trust domains and provides APIs for Federators
Keycloak Authentication and authorisation provider
PostgreSQL (via Docker Compose) Keycloak persistence
OpenSSL Certificates Service-to-service identity via Mutual TLS (MTLS)
Java Keystore (JKS / PKCS12) TLS certificate storage
Java Truststore Certificate authority validation

2. Runtime Services and Default Ports

Service Default Port Notes
Management Node (HTTPS) 8443 (typical) TLS-enabled Spring Boot application
Keycloak 8080 Identity provider
PostgreSQL 5432 Keycloak database

Ports may be overridden via configuration or Docker settings.

3. Security Model

The Management Node implements a zero-trust security architecture.

Security is enforced through:

  • Mutual TLS (MTLS) for service-to-service communication
  • Certificate-based trust validation
  • Keycloak-issued tokens for identity and authorisation
  • Spring Security integration

All incoming requests from Federators must:

  • Present a valid client certificate
  • Be validated against the configured truststore
  • Be authenticated via Keycloak

No unsecured communication paths are permitted.

4. TLS and Certificate Artifacts

Artifact Purpose
rootCA.crt Root certificate authority
localhost.crt Server certificate
localhost.key Server private key
localhost.p12 Server PKCS12 keystore
keystore.jks Java keystore
truststore.jks Java truststore
client.crt Client certificate for MTLS
client.p12 Client PKCS12 keystore

Certificates are typically valid for:

  • Root CA: 10 years
  • Host/Client certificates: 365 days

5. Environment Variables

Spring Profiles

Variable Required Description
SPRING_PROFILES_ACTIVE No Active Spring profile (e.g. local)

SSL Configuration

Property Required Description
server.ssl.key-store Yes Path to keystore
server.ssl.key-store-password Yes Keystore password
server.ssl.key-store-type Yes PKCS12 or JKS
server.ssl.trust-store Yes Path to truststore
server.ssl.trust-store-password Yes Truststore password

Keycloak Configuration

Property Required Description
spring.security.oauth2.resourceserver.jwt.issuer-uri Yes Keycloak issuer URL
spring.security.oauth2.resourceserver.jwt.jwk-set-uri Yes JWKS endpoint
keycloak.realm Yes Keycloak realm name
keycloak.resource Yes Client ID
keycloak.auth-server-url Yes Base URL of Keycloak

6. Configuration Files

File Purpose
application.yml Default Spring Boot configuration
application-.yml Profile-specific configuration
docker-compose.yml Keycloak + PostgreSQL orchestration
keycloak.conf Keycloak runtime configuration

Configuration is profile-driven.

Environment-specific settings should not be committed to version control.

7. HTTP APIs

The Management Node exposes HTTPS endpoints secured via MTLS and token validation.

Exact endpoint paths depend on application configuration.

All endpoints require:

  • Valid client certificate (MTLS)
  • Valid authentication token (if configured)

Example base URL:

https://localhost:8443

8. Operational Characteristics

  • Certificates must be valid and trusted on both client and server sides.
  • Keystore and truststore are loaded at application startup.
  • Spring profiles determine configuration scope.
  • Keycloak must be available before the application starts.
  • MTLS handshake failure prevents application communication.
  • Environment variables are read at startup.

Restart is required after:

  • Changing certificates
  • Updating configuration
  • Changing active Spring profile

9. Common Failure Modes

Symptom Likely Cause
Application fails to start Incorrect keystore/truststore path
SSLHandshakeException Certificate mismatch or truststore issue
401 Unauthorized Keycloak misconfiguration
Invalid JWT Incorrect issuer or JWKS URL
Port already in use Conflicting service
Keycloak connection refused Keycloak not running
MTLS failure Client certificate missing or untrusted

10. Compatibility

Component Version Notes
Java 21 required
Maven 3.9+
Keycloak 26.5.0 recommended (supports Java 21)
OpenSSL Required for certificate generation

Earlier Keycloak versions (e.g. 21.x) may not support Java 21.