Skip to content

Environment Set Up

Purpose

This stage prepares your local environment for deploying the Management Node. You will:

  • Confirm platform and tooling requirements
  • Clone the Management Node repository
  • Generate Mutual TLS (MTLS) certificates
  • Create keystores and truststores required for secure communication
Prerequisites

Configured certificates are required. See the certificate setup guide here:

https://github.com/National-Digital-Twin/management-node/#certificate-setup

Platform

Linux or WSL2 for Windows.

Required tools
  • Java 21
  • Maven 3.9+
  • Docker and Docker Compose
  • OpenSSL (for certificate generation)
  • Keycloak (for authentication and authorisation)
  • Keytool
Operational notes

OpenSSL certificate generation and Keycloak setup are described in Stage 2 and Stage 3 respectively.

Stage 1 – Clone the Management Node repository

How to complete this stage

Clone the Management Node repository.

git clone https://github.com/National-Digital-Twin/management-node.git

Note the folder structure. In the next stage, certificates will be created and placed in the docker subfolder.

Stage 2 – Generate OpenSSL certificates

How to complete this stage

You will:

  • Create a Root CA certificate
  • Create a host certificate
  • Create a PKCS12 keystore
  • Create a Java keystore (JKS)
  • Create a Java Truststore
  • Generate a client certificate for MTLS

Approach and rationale

The Management Node implements a zero-trust security architecture using Mutual TLS (MTLS) for secure communication between all components. Certificates are used to mediate service-to-service authentication.
They provide a secure mechanism for services to verify each other's identity without relying on passwords or API keys. These certificates will be made available to the Management Node during runtime.

2.1 Create a Root CA certificate

Create the Root CA certificate (valid for ten years):

openssl req -x509 -sha256 -days 3650 -newkey rsa:4096 -keyout rootCA.key -out rootCA.crt

2.2 Generate a host certificate

openssl req -new -newkey rsa:4096 -keyout localhost.key -out localhost.csr -nodes

2.3 Sign the host certificate with the Root CA

Sign the certificate (valid for 365 days):

openssl x509 -req -CA rootCA.crt -CAkey rootCA.key -in localhost.csr -out localhost.crt -days 365 -CAcreateserial -extfile localhost.ext

2.4 Validate the certificate

Ensure the contents of localhost.ext match:

authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
subjectAltName = @alt_names
[alt_names]
DNS.1 = localhost
DNS.2 = keycloak

2.5 Create a PKCS12 keystore for the server

Bundle the host certificate and private key into PKCS12 format:

openssl pkcs12 -export -out localhost.p12 -name "localhost" -inkey localhost.key -in localhost.crt

2.6 Create a PEM file for Linux keystore

Extract the certificate (without the private key) in PEM format:

openssl pkcs12 -in localhost.p12 -clcerts -nokeys -out localhost.pem

2.7 Add the Root CA to the Trust Store

keytool -importcert -file rootCA.crt -alias clientca -keystore localhost.p12 -storetype PKCS12 -storepass changeit

2.8 Generate a client certificate

Create a private key and CSR for the client:

openssl req -new -newkey rsa:4096 -nodes -keyout client.key -out client.csr

2.9 Sign the client certificate with the Root CA

openssl x509 -req -CA rootCA.crt -CAkey rootCA.key -in client.csr -out client.crt -days 365 -CAcreateserial

2.10 Create a PKCS12 keystore for the client

openssl pkcs12 -export -out client.p12 -name "client" -inkey client.key -in client.crt

2.11 Create a Java keystore (JKS)

Convert the PKCS12 keystore to a Java KeyStore format:

keytool -importkeystore -destkeystore keystore.jks -srckeystore localhost.p12 -srcstoretype PKCS12 -alias "localhost"

2.12 Create a Java Truststore

Create a Truststore containing the Root CA certificate:

keytool -import -trustcacerts -noprompt -alias ca -ext san=dns:localhost,ip:127.0.0.1 -file rootCA.crt -keystore truststore.jks

2.13 Import the Root CA into the Truststore

keytool -importcert -file rootCA.crt -alias rootCA -keystore truststore.jks -storetype JKS

2.14 Verify the Truststore

keytool -list -keystore truststore.jks -storetype PKCS12 -storepass changeit

2.15 Checkpoint

At the end of this stage:

  • The Management Node repository has been cloned.
  • A Root CA certificate exists.
  • Host and client certificates have been generated.
  • PKCS12 keystores have been created.
  • Java keystore and truststore files exist.
  • Certificates are ready to be referenced by the Management Node application.

If any certificate commands fail, resolve issues before continuing.

Next Steps

Identity Set Up