feat(vault): implement advanced secret management with hashicorp vault (#19)

apenlor · web-flow · commit 6bfffce45a54 · 2025-09-09T17:20:49.000+02:00
* infra(vault): add hashicorp vault to docker compose stack

* feat(all): integrate spring cloud vault dependencies

* feat(all): configure vault bootstrap connection

* refactor(all): source all application secrets from vault

* refactor(security): source actuator role from configuration

* fix(security): override nimbus-jose-jwt to patch transitive vulnerability

* docs(readme): update main README for phase 8 completion

* fix(ci): adapt dast scan script for vault integration
diff --git a/.env.ci b/.env.ci
@@ -5,10 +5,9 @@
 # scan's subset of services (postgres, keycloak, resource-server) to initialize.
 # ===================================================================
 
-# Actuator basic auth configuration
-ACTUATOR_USERNAME=actuator
-ACTUATOR_PASSWORD=actuator-password
-ACTUATOR_ROLES=ACTUATOR_ADMIN
+# Prometheus Scrape Credentials
+PROMETHEUS_SCRAP_USER=actuator
+PROMETHEUS_SCRAP_PASSWORD=actuator-password
 
 # Keycloak Admin Credentials
 KC_BOOTSTRAP_ADMIN_USERNAME=admin
diff --git a/.env.example b/.env.example
@@ -7,10 +7,9 @@
 # These variables will be used by docker-compose.yml to configure the services.
 # ===================================================================
 
-# Actuator basic auth configuration
-ACTUATOR_USERNAME=actuator
-ACTUATOR_PASSWORD=actuator-password
-ACTUATOR_ROLES=ACTUATOR_ADMIN
+# Prometheus Scrape Credentials
+PROMETHEUS_SCRAP_USER=actuator
+PROMETHEUS_SCRAP_PASSWORD=actuator-password
 
 # Keycloak Admin Credentials
 KC_BOOTSTRAP_ADMIN_USERNAME=admin
@@ -19,7 +18,4 @@ KC_BOOTSTRAP_ADMIN_PASSWORD=admin
 # PostgreSQL Credentials for Keycloak
 POSTGRES_DB=keycloak
 POSTGRES_USER=keycloak
-POSTGRES_PASSWORD=keycloak-password
-
-# Keycloak Web Client Credentials
-WEB_CLIENT_SECRET=replace-with-web-app-client-secret-from-keycloak
+POSTGRES_PASSWORD=keycloak-password
diff --git a/.gitignore b/.gitignore
@@ -46,6 +46,7 @@ Desktop.ini
 ### Lab Specific ###
 # Local environment variables
 .env
+.secrets.env
 
 # Persistent data volumes
 /data/
diff --git a/.secrets.env.ci b/.secrets.env.ci
@@ -0,0 +1,15 @@
+# ===================================================================
+# CI/CD APPLICATION SECRETS FOR VAULT
+# ===================================================================
+# This file contains dummy/test secrets for populating Vault during CI/CD runs.
+# These values are used by the `vault-setup` init container.
+# This file is committed to Git, so DO NOT put real secrets here.
+# ===================================================================
+
+# Actuator basic auth credentials for Spring Boot applications
+ACTUATOR_USERNAME=ci-actuator
+ACTUATOR_PASSWORD=ci-actuator-password
+ACTUATOR_ROLES=CI_ACTUATOR_ADMIN
+
+# Keycloak Web Client Credentials
+WEB_CLIENT_SECRET=ci-web-client-secret-value
diff --git a/.secrets.env.example b/.secrets.env.example
@@ -0,0 +1,17 @@
+# ===================================================================
+# APPLICATION SECRETS FOR VAULT
+# ===================================================================
+# Copy this file to .secrets.env and populate it.
+# This file contains the secrets that will be written into HashiCorp Vault
+# by the `scripts/populate-vault.sh` script.
+#
+# The .secrets.env file is ignored by Git and should NEVER be committed.
+# ===================================================================
+
+# Actuator basic auth credentials for Spring Boot applications
+ACTUATOR_USERNAME=actuator
+ACTUATOR_PASSWORD=actuator-password
+ACTUATOR_ROLES=ACTUATOR_ADMIN
+
+# Keycloak Web Client Credentials
+WEB_CLIENT_SECRET=a-very-strong-and-long-secret-for-the-web-client
diff --git a/README.md b/README.md
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -30,8 +30,12 @@ services:
       retries: 10
       start_period: 20s
     depends_on:
+      vault-setup:
+        condition: service_completed_successfully
       keycloak:
         condition: service_healthy
+      vault:
+        condition: service_healthy
       alloy:
         condition: service_started
     networks:
@@ -61,10 +65,14 @@ services:
       # Mount the agent JAR into a known location in the container.
       - ./config/otel/opentelemetry-javaagent.jar:/app/opentelemetry-javaagent.jar:ro
     depends_on:
+      vault-setup:
+        condition: service_completed_successfully
       keycloak:
         condition: service_healthy
       resource-server:
         condition: service_healthy
+      vault:
+        condition: service_healthy
       alloy:
         condition: service_started
     networks:
@@ -142,6 +150,55 @@ services:
     networks:
       - lab-net
 
+  # --------------------------------------------------------------------------
+  # Secrets Management Service: HashiCorp Vault
+  # --------------------------------------------------------------------------
+  vault:
+    image: "hashicorp/vault:1.20.3"
+    container_name: vault
+    ports:
+      - "8200:8200"
+    environment:
+      # Root token for the dev server
+      VAULT_DEV_ROOT_TOKEN_ID: "dev-root-token"
+      # Target address for the vault CLI tool inside the container
+      VAULT_ADDR: "http://127.0.0.1:8200"
+      # Auth token for the vault CLI, enabling `docker exec` commands
+      VAULT_TOKEN: "dev-root-token"
+    cap_add:
+      # Grants mlock capability to prevent secrets from being swapped to disk
+      - IPC_LOCK
+    command: "server -dev"
+    healthcheck:
+      test: ["CMD-SHELL", "wget -q --spider http://127.0.0.1:8200/v1/sys/health || exit 1"]
+      interval: 5s
+      timeout: 2s
+      retries: 5
+      start_period: 5s
+    networks:
+      - lab-net
+
+  # --------------------------------------------------------------------------
+  # Vault Setup Service
+  # --------------------------------------------------------------------------
+  vault-setup:
+    image: "hashicorp/vault:1.20.3"
+    container_name: vault-setup
+    volumes:
+      # Mount the script into the container to be executed
+      - ./scripts/populate-vault.sh:/usr/local/bin/populate-vault.sh:ro
+    environment:
+      - VAULT_ADDR=http://vault:8200
+      - VAULT_TOKEN=dev-root-token
+    env_file:
+      - .secrets.env
+    command: "sh /usr/local/bin/populate-vault.sh"
+    depends_on:
+      vault:
+        condition: service_healthy
+    networks:
+      - lab-net
+
   # --------------------------------------------------------------------------
   # Prometheus Service: For metrics collection.
   # --------------------------------------------------------------------------
@@ -266,9 +323,9 @@ services:
 
 secrets:
   actuator_username:
-    environment: "ACTUATOR_USERNAME"
+    environment: "PROMETHEUS_SCRAP_USER"
   actuator_password:
-    environment: "ACTUATOR_PASSWORD"
+    environment: "PROMETHEUS_SCRAP_PASSWORD"
 
 volumes:
   grafana-data:
diff --git a/pom.xml b/pom.xml
@@ -21,12 +21,17 @@
     <properties>
         <java.version>21</java.version>
         <spring-boot.version>3.5.5</spring-boot.version>
+        <spring-cloud.version>2025.0.0</spring-cloud.version>
         <!--
         Explicitly overriding Netty version to mitigate CVE-2025-58056.
         https://nvd.nist.gov/vuln/detail/CVE-2025-58056
-        This forces all transitive Netty dependencies to use a patched version.
         -->
         <netty.version>4.1.126.Final</netty.version>
+        <!--
+        Explicitly overriding Netty version to mitigate CVE-2025-53864.
+        https://nvd.nist.gov/vuln/detail/CVE-2025-53864
+        -->
+        <nimbus-jose-jwt.version>9.37.4</nimbus-jose-jwt.version>
         <logstash-logback-encoder.version>8.1</logstash-logback-encoder.version>
         <lombok.version>1.18.38</lombok.version>
         <maven-compiler-plugin.version>3.14.0</maven-compiler-plugin.version>
@@ -46,13 +51,28 @@
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>
+            <!--
+            SECURITY REMEDIATION (CVE-2025-53864)
+            -->
+            <dependency>
+                <groupId>com.nimbusds</groupId>
+                <artifactId>nimbus-jose-jwt</artifactId>
+                <version>${nimbus-jose-jwt.version}</version>
+            </dependency>
             <dependency>
                 <groupId>org.springframework.boot</groupId>
                 <artifactId>spring-boot-dependencies</artifactId>
                 <version>${spring-boot.version}</version>
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>
+            <dependency>
+                <groupId>org.springframework.cloud</groupId>
+                <artifactId>spring-cloud-dependencies</artifactId>
+                <version>${spring-cloud.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
 
             <!-- Other managed dependencies -->
             <dependency>
diff --git a/resource-server/pom.xml b/resource-server/pom.xml
@@ -28,6 +28,12 @@
             <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
         </dependency>
 
+        <!-- Vault integration -->
+        <dependency>
+            <groupId>org.springframework.cloud</groupId>
+            <artifactId>spring-cloud-starter-vault-config</artifactId>
+        </dependency>
+
         <!-- API Documentation -->
         <dependency>
             <groupId>org.springdoc</groupId>
diff --git a/resource-server/src/main/java/com/apenlor/lab/resourceserver/config/SecurityConfig.java b/resource-server/src/main/java/com/apenlor/lab/resourceserver/config/SecurityConfig.java
@@ -1,6 +1,7 @@
 package com.apenlor.lab.resourceserver.config;
 
 import com.apenlor.lab.resourceserver.auth.KeycloakRoleConverter;
+import org.springframework.beans.factory.annotation.Value;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.core.annotation.Order;
@@ -33,6 +34,9 @@ public class SecurityConfig {
             "/swagger-ui.html"
     };
 
+    @Value("${actuator.roles}")
+    private String actuatorAdminRole;
+
     /**
      * Configures the security filter chain for the management endpoints (Actuator).
      * <p>
@@ -51,7 +55,7 @@ public SecurityFilterChain actuatorSecurityFilterChain(HttpSecurity http) throws
                 .authorizeHttpRequests(authorize -> authorize
                         // Allow anonymous access to health and info endpoints.
                         .requestMatchers("/actuator/health", "/actuator/info").permitAll()
-                        .anyRequest().hasRole("ACTUATOR_ADMIN")
+                        .anyRequest().hasRole(actuatorAdminRole)
                 )
                 .httpBasic(Customizer.withDefaults())
                 .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
diff --git a/resource-server/src/main/resources/application.properties b/resource-server/src/main/resources/application.properties
@@ -30,13 +30,10 @@ management.info.env.enabled=true
 # ===================================================================
 # MANAGEMENT & ACTUATOR SECURITY
 # ===================================================================
-# By defining these standard properties, Spring Boot's autoconfiguration
-# will create a secure in-memory user, perfect for protecting the actuator
-# endpoints with Basic Authentication. This is simpler than our previous
-# custom AuthenticationProvider.
-spring.security.user.name=${ACTUATOR_USERNAME}
-spring.security.user.password=${ACTUATOR_PASSWORD}
-spring.security.user.roles=${ACTUATOR_ROLES}
+# These properties are sourced from Vault at startup. The keys must match what is written by populate-vault.sh.
+spring.security.user.name=${actuator.username}
+spring.security.user.password=${actuator.password}
+spring.security.user.roles=${actuator.roles}
 
 # ===================================================================
 # SPRING SECURITY OAUTH2 RESOURCE SERVER
@@ -58,4 +55,29 @@ spring.security.oauth2.resourceserver.jwt.issuer-uri=http://keycloak.local/realm
 # The "@" symbols are automatically replaced by Maven during the build process via resource filtering.
 info.app.name=@project.name@
 info.app.description=@project.description@
-info.app.version=@project.version@
+info.app.version=@project.version@
+
+# ===================================================================
+# SPRING CLOUD VAULT CONFIGURATION
+# ===================================================================
+spring.config.import=vault://
+
+# The configuration below uses a static, long-lived root token for authentication
+# This is INSECURE and suitable ONLY for a simplified lab environment
+#
+# In a real-world production scenario, the recommended approach is to use the
+# Vault AppRole authentication method. This involves:
+# 1. Baking a non-sensitive "RoleID" into the application's configuration
+# 2. Having a trusted orchestrator (like Kubernetes) securely generate and inject
+#    a short-lived, single-use "SecretID" at application startup
+#
+# This solves the "first secret" problem without ever hardcoding long-lived
+# credentials in the application's configuration
+spring.cloud.vault.uri=http://vault:8200
+spring.cloud.vault.token=dev-root-token
+
+# Configuration for the Key-Value (KV) secrets engine.
+spring.cloud.vault.kv.enabled=true
+spring.cloud.vault.kv.backend=secret
+# This uses the application name to look for secrets at the path "secret/resource-server"
+spring.cloud.vault.kv.application-name=${spring.application.name}
diff --git a/resource-server/src/test/resources/application-test.properties b/resource-server/src/test/resources/application-test.properties
@@ -3,7 +3,17 @@
 # ===================================================================
 # This file provides properties required for the test suite to run.
 
-# In-memory user credentials for securing actuator endpoints during tests.
-spring.security.user.name=test-actuator
-spring.security.user.password=test-password
-spring.security.user.roles=ACTUATOR_ADMIN
+# ===================================================================
+# Vault & External Config Overrides
+# ===================================================================
+# 1. Disable the Vault import
+spring.config.import=
+# 2. Disable the Vault Health Indicator
+management.health.vault.enabled=false
+
+# 3. Provide mock values for actuator credentials.
+# Since the Vault import is disabled, we must provide mock values for any
+# properties that would normally be fetched from Vault.
+actuator.username=test-actuator
+actuator.password=test-password
+actuator.roles=TEST_ACTUATOR_ROLE
diff --git a/scripts/populate-vault.sh b/scripts/populate-vault.sh
@@ -0,0 +1,37 @@
+#!/bin/sh
+set -e
+
+# ==============================================================================
+# POPULATE VAULT SCRIPT
+# ==============================================================================
+# This script runs inside a container on the same Docker network as the Vault
+# server. It uses the vault CLI to populate secrets over the network.
+# ==============================================================================
+
+# --- Helper Functions ---
+check_env_vars() {
+  required_vars="VAULT_ADDR VAULT_TOKEN ACTUATOR_USERNAME ACTUATOR_PASSWORD ACTUATOR_ROLES WEB_CLIENT_SECRET"
+  for var in ${required_vars}; do
+    if [ -z "$(eval echo \"\$$var\")" ]; then
+      echo "ERROR: Required environment variable ${var} is not set."
+      exit 1
+    fi
+  done
+}
+
+# --- Main Execution ---
+check_env_vars
+
+echo "--- Populating Vault with application secrets ---"
+vault kv put secret/resource-server \
+  actuator.username="${ACTUATOR_USERNAME}" \
+  actuator.password="${ACTUATOR_PASSWORD}" \
+  actuator.roles="${ACTUATOR_ROLES}"
+
+vault kv put secret/web-client \
+  client-secret="${WEB_CLIENT_SECRET}" \
+  actuator.username="${ACTUATOR_USERNAME}" \
+  actuator.password="${ACTUATOR_PASSWORD}" \
+  actuator.roles="${ACTUATOR_ROLES}"
+
+echo "✅ Vault population complete."
diff --git a/scripts/run-zap-scan.sh b/scripts/run-zap-scan.sh
diff --git a/web-client/pom.xml b/web-client/pom.xml
diff --git a/web-client/src/main/java/com/apenlor/lab/webclient/config/SecurityConfig.java b/web-client/src/main/java/com/apenlor/lab/webclient/config/SecurityConfig.java
diff --git a/web-client/src/main/resources/application.properties b/web-client/src/main/resources/application.properties
diff --git a/web-client/src/test/resources/application-test.properties b/web-client/src/test/resources/application-test.properties
