OpenBankProject · constantine2nd · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026
diff --git a/.gitignore b/.gitignore
@@ -24,6 +24,11 @@ obp-api/src/main/resources/*
 obp-api/src/test/resources/**
 !obp-api/src/test/resources/frozen_type_meta_data
 !obp-api/src/test/resources/logback-test.xml
+# The development certificate set (scripts/generate_dev_certs.sh) is a test fixture and belongs in
+# the repository. Without these two lines a regenerated set is silently untracked and the tests
+# that depend on it fail everywhere except the machine that ran the script.
+!obp-api/src/test/resources/cert/
+!obp-api/src/test/resources/cert/**
 *.iml
 obp-api/src/main/resources/log4j.properties
 obp-api/src/main/scripts/kafka/kafka_*

diff --git a/docs/MTLS_DEV_MODE.md b/docs/MTLS_DEV_MODE.md
diff --git a/docs/MTLS_TOPOLOGIES.md b/docs/MTLS_TOPOLOGIES.md
diff --git a/flushall_build_and_run.sh b/flushall_build_and_run.sh
@@ -11,6 +11,7 @@
 #   ./build_and_run.sh              - Build and run with Redis flush
 #   ./build_and_run.sh --no-flush   - Build and run without Redis flush
 #   ./build_and_run.sh --background - Run server in background
+#   ./build_and_run.sh --mtls       - Serve HTTPS with mutual TLS (dev only)
 #
 # The HTTP4S server runs on the port configured in your props file
 # (default: 8080 for dev.port, or 8086 for hostname port)
@@ -21,6 +22,7 @@
 # Parse arguments
 FLUSH_REDIS=true
 RUN_BACKGROUND=false
+USE_MTLS=false
 
 for arg in "$@"; do
     case $arg in
@@ -32,9 +34,16 @@
             RUN_BACKGROUND=true
             echo ">>> Server will run in background"
             ;;
+        --mtls)
+            USE_MTLS=true
+            echo ">>> mTLS mode requested (in-process TLS termination)"
+            ;;
     esac
 done
 
+# Select a JDK >= 17 before any Maven work (the build compiles with -release 17).
+. "$(dirname "${BASH_SOURCE[0]}")/scripts/java_env.sh"
+
 ################################################################################
 # FLUSH REDIS CACHE (OPTIONAL)
 ################################################################################
@@ -109,8 +118,12 @@
 # Show last 3 lines of build output in real-time
 tail -n 3 -f build.log &
 TAIL_PID=$!
+# set +e: this script runs under `set -e`, which would abort at a failing build
+# before the BUILD_EXIT check below could print the log tail.
+set +e
 mvn -pl obp-api -am clean package -DskipTests=true -Dmaven.test.skip=true -T 4 > build.log 2>&1
 BUILD_EXIT=$?
+set -e
 kill $TAIL_PID 2>/dev/null || true
 wait $TAIL_PID 2>/dev/null || true
 
@@ -132,6 +145,12 @@
 # RUN HTTP4S SERVER
 ################################################################################
 
+# Applied after the build so it only affects the running server, never compilation.
+if [ "$USE_MTLS" = true ]; then
+    . "$(dirname "${BASH_SOURCE[0]}")/scripts/mtls_env.sh"
+    echo ""
+fi
+
 echo "=========================================="
 if [ "$RUN_BACKGROUND" = true ]; then
     echo "Starting HTTP4S server (background)..."

diff --git a/flushall_fast_build_and_run.sh b/flushall_fast_build_and_run.sh
@@ -17,6 +17,7 @@
 #   ./fast_build_and_run.sh --online       - Check remote repositories
 #   ./fast_build_and_run.sh --no-flush     - Skip Redis flush
 #   ./fast_build_and_run.sh --background   - Run server in background
+#   ./fast_build_and_run.sh --mtls         - Serve HTTPS with mutual TLS (dev only)
 #
 # Typical speedup: 2-5x faster than regular build for incremental changes
 ################################################################################
@@ -28,6 +29,7 @@
 OFFLINE_FLAG="-o"  # Default to offline mode for faster builds
 FLUSH_REDIS=true
 RUN_BACKGROUND=false
+USE_MTLS=false
 
 for arg in "$@"; do
     case $arg in
@@ -47,9 +49,16 @@
             RUN_BACKGROUND=true
             echo ">>> Server will run in background"
             ;;
+        --mtls)
+            USE_MTLS=true
+            echo ">>> mTLS mode requested (in-process TLS termination)"
+            ;;
     esac
 done
 
+# Select a JDK >= 17 before any Maven work (the build compiles with -release 17).
+. "$(dirname "${BASH_SOURCE[0]}")/scripts/java_env.sh"
+
 # Show offline mode status if not explicitly set
 if [ "$OFFLINE_FLAG" = "-o" ]; then
     echo ">>> Using offline mode (default) - use --online to check remote repos"
@@ -165,6 +174,10 @@
 } > fast_build.log
 
 # Run Maven build and append to log
+# set +e around the build: this script runs under `set -e`, which would abort here
+# on a failing build and make BUILD_EXIT_CODE — and the auto-retry-with-clean block
+# below — unreachable. We want to inspect the failure, not die at it.
+set +e
 mvn -pl obp-api -am \
     $DO_CLEAN \
     package \
@@ -175,8 +188,8 @@
     -Dcheckstyle.skip=true \
     -Dspotbugs.skip=true \
     -Dpmd.skip=true >> fast_build.log 2>&1
-
 BUILD_EXIT_CODE=$?
+set -e
 
 # Record build end time and calculate duration
 if command -v gdate &> /dev/null; then
@@ -237,7 +250,8 @@
             echo ""
         } > fast_build.log
 
-        # Run clean build
+        # Run clean build (set +e for the same reason as the first invocation)
+        set +e
         mvn -pl obp-api -am \
             clean \
             package \
@@ -248,8 +262,8 @@
             -Dcheckstyle.skip=true \
             -Dspotbugs.skip=true \
             -Dpmd.skip=true >> fast_build.log 2>&1
-
         BUILD_EXIT_CODE=$?
+        set -e
 
         # Record retry end time and calculate duration
         if command -v gdate &> /dev/null; then
@@ -300,6 +314,12 @@
 # RUN HTTP4S SERVER
 ################################################################################
 
+# Applied after the build so it only affects the running server, never compilation.
+if [ "$USE_MTLS" = true ]; then
+    . "$(dirname "${BASH_SOURCE[0]}")/scripts/mtls_env.sh"
+    echo ""
+fi
+
 echo "=========================================="
 if [ "$RUN_BACKGROUND" = true ]; then
     echo "Starting HTTP4S server (background)..."

diff --git a/obp-api/src/main/resources/props/sample.props.template b/obp-api/src/main/resources/props/sample.props.template
@@ -166,7 +166,18 @@ jwt.use.ssl=false
 ## that forwards the verified client certificate as the PSD2-CERT request header.
 ## When enabled, dev.port serves HTTPS with mutual TLS and the verified client certificate is
 ## injected as the PSD2-CERT header (any client-supplied PSD2-CERT header is stripped).
-## The paths below point at the JKS pair checked into the repo for local development.
+## Only mtls.enabled is required: the four store props below default to exactly these values,
+## the JKS pair checked into the repo for local development. Set them to use your own certificates.
+## Easiest switch is not to edit this file at all: ./flushall_fast_build_and_run.sh --mtls
+##
+## Honoured in every run mode; a Production server refuses to boot on the dev pair below.
+## If a reverse proxy terminates mTLS and forwards the client certificate as PSD2-CERT, name it
+## here so its own handshake certificate is not mistaken for the caller's (see docs/MTLS_TOPOLOGIES.md):
+# mtls.trusted_proxy.1.issuer=CN=Your Internal CA,O=Your Org,C=DE
+# mtls.trusted_proxy.1.subject=CN=nginx-prod-1,O=Your Org,C=DE
+## Whether a forwarded PSD2-CERT is trusted when the sender presented no client certificate.
+## True is the long-standing behaviour of a plain proxy hop; set false once the proxy uses mTLS.
+# mtls.trust_forwarded_header_without_tls=true
 # mtls.enabled=true
 # mtls.keystore.path=obp-api/src/test/resources/cert/server.jks
 # mtls.keystore.password=123456