Implement Keycloak integration for authentication and authorization

- Update environment variables for Keycloak configuration in .env.example
- Modify Docker Compose files to include Keycloak service and database setup
- Add database initialization script for Keycloak and People API
- Enhance application security with OAuth2 and JWT support in Spring configuration
- Update application.yml for Keycloak OAuth2 client settings
- Add example secret files for Keycloak and API database passwords

Author: mcqueide

.env.example

@@ -1,18 +1,32 @@
 # ----------------------------------------------------------------------------
 # GENERAL
 # ----------------------------------------------------------------------------
-COMPOSE_PROJECT_NAME=people-api
+COMPOSE_PROJECT_NAME=people
 ENVIRONMENT=production
 
 # ----------------------------------------------------------------------------
-# DB
+# API DB
 # ----------------------------------------------------------------------------
 POSTGRES_DB=people
-POSTGRES_USER_FILE=/run/secrets/db-user
+POSTGRES_USER=postgres
 POSTGRES_PASSWORD_FILE=/run/secrets/db-password
 PGDATA=/var/lib/postgresql/data/pgdata
 POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=C --lc-ctype=C
 
+# ----------------------------------------------------------------------------
+# KEYCLOAK ADMIN (Web UI credentials)
+# ----------------------------------------------------------------------------
+KC_DB=postgres
+KC_DB_URL=jdbc:postgresql://db:5432/keycloak
+KC_DB_USERNAME=keycloak
+KC_DB_PASSWORD=keycloak
+KC_HOSTNAME=keycloak.example.com
+KC_PROXY_HEADERS=xforwarded
+KC_BOOTSTRAP_ADMIN_USERNAME=username
+KC_BOOTSTRAP_ADMIN_PASSWORD=password
+KC_HEALTH_ENABLED=true
+KC_METRICS_ENABLED=true
+
 # ----------------------------------------------------------------------------
 # SPRING
 # ----------------------------------------------------------------------------
@@ -22,6 +36,8 @@ SPRING_DATASOURCE_USERNAME=username
 SPRING_DATASOURCE_PASSWORD=password
 #JAVA_OPTS="-XX:+UseG1GC -Xms256m -Xmx512m"
 JAVA_OPTS="-XX:+UseG1GC -XX:MaxRAMPercentage=75"
+KEYCLOAK_ISSUER_URI=http://keycloak.example.com/realms/people-realm
+KEYCLOAK_JWK_SET_URI=http://keycloak.example.com/realms/people-realm/protocol/openid-connect/certs
 
 # ----------------------------------------------------------------------------
 # NGINX

compose-dev.yaml

@@ -1,41 +1,83 @@
+name: people-dev
+
+networks:
+  backend:
+    driver: bridge
+
 services:
   db:
     image: postgres:18-alpine3.22
-    container_name: db
     restart: always
     user: postgres
     secrets:
-      - db-user
       - db-password
+      - keycloak-db-password
+      - api-db-password
     volumes:
       - db-data:/var/lib/postgresql/data
-    env_file:
-      - .env
+      - ./postgres/init:/docker-entrypoint-initdb.d:ro  # Initialization scripts
+    environment:
+      POSTGRES_DB: postgres
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
     ports:
       - "5432:5432"
     healthcheck:
-      test: [ "CMD", "pg_isready" ]
+      test: [ "CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}" ]
       interval: 10s
       timeout: 5s
+      retries: 3
+    networks:
+      - backend
+
+  keycloak:
+    image: quay.io/keycloak/keycloak:26.4
+    command: start-dev
+    depends_on:
+      db:
+        condition: service_healthy
+    ports:
+      - "8080:8080"
+      - "9000:9000"  # Admin health endpoint
+    environment:
+      KC_DB: postgres
+      KC_DB_URL: jdbc:postgresql://db:5432/keycloak
+      KC_DB_USERNAME: keycloak
+      KC_DB_PASSWORD: keycloak
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: admin
+      KC_HOSTNAME: localhost
+      KC_PROXY_HEADERS: xforwarded
+      KC_HEALTH_ENABLED: true
+      KC_METRICS_ENABLED: true
+    healthcheck:
+      test: ["CMD-SHELL", "exec 3<>/dev/tcp/keycloak/9000 && echo -e 'GET /health/ready HTTP/1.1\r\nHost: keycloak\r\nConnection: close\r\n\r\n' >&3 && cat <&3 | grep -q '200 OK'"]
+      interval: 30s
+      timeout: 10s
       retries: 5
+      start_period: 90s  # Keycloak takes time to initialize
+    networks:
+      - backend
 
-  app:
+  api:
     build:
       context: .
       dockerfile: Dockerfile-dev
     working_dir: /app
     #command: .mvnw -q spring-boot:run
-    container_name: people-api-dev
     depends_on:
       db:
         condition: service_healthy
+      keycloak:
+        condition: service_healthy
     environment:
-      SPRING_PROFILES_ACTIVE: docker
       MAVEN_OPTS: -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
-    env_file:
-      - .env
+      SPRING_DATASOURCE_URL: jdbc:postgresql://db:5432/people
+      SPRING_DATASOURCE_USERNAME: people
+      SPRING_DATASOURCE_PASSWORD: people
+      KEYCLOAK_ISSUER_URI: http://keycloak:8080/realms/people-realm
     ports:
-      - "8080:8080"
+      - "8081:8080"
       - "5005:5005"
     volumes:
 #      - ./:/app
@@ -46,11 +88,15 @@ services:
           path: .
           target: /app
     tty: true
+    networks:
+      - backend
 
 volumes:
   db-data:
 secrets:
   db-password:
-    file: secrets/db-password.txt
-  db-user:
-    file: ./secrets/db-user.txt
+    file: ./secrets/db-password.txt
+  api-db-password:
+    file: ./secrets/api-db-password.txt
+  keycloak-db-password:
+    file: ./secrets/keycloak-db-password.txt

compose.yaml

@@ -146,8 +146,12 @@ volumes:
 secrets:
   db-password:
     file: ./secrets/db-password.txt
-  db-user:
-    file: ./secrets/db-user.txt
+  api-db-password:
+    file: ./secrets/api-db-password.txt
+  keycloak-db-password:
+    file: ./secrets/keycloak-db-password.txt
+  keycloak-admin-password:
+    file: ./secrets/keycloak-admin-password.txt
 
 # ============================================================================
 # CONFIGURATION
@@ -266,7 +270,7 @@ services:
 
     # Ports: DO NOT expose externally in production
     # ports:
-    #   - "8080:8080"  # ❌ For debug only, remove in production
+    #   - "8081:8080"  # ❌ For debug only, remove in production
 
     # Ports (not externally exposed, only through nginx)
     expose:
@@ -277,8 +281,7 @@ services:
       - .env
 
     secrets:
-      - db-password
-      - db-user
+      - api-db-password
 
     # Volumes
     volumes:
@@ -288,6 +291,8 @@ services:
     depends_on:
       db:
         condition: service_healthy
+      keycloak:
+        condition: service_healthy
 
     # Resource limits
     deploy:
@@ -368,11 +373,13 @@ services:
     # Secrets
     secrets:
       - db-password
-      - db-user
+      - keycloak-db-password
+      - api-db-password
 
     # Persistent volumes
     volumes:
       - db-data:/var/lib/postgresql/data
+      - ./postgres/init:/docker-entrypoint-initdb.d:ro  # Initialization scripts
 
     # Not required, docker uses .env by default
     env_file:
@@ -386,7 +393,7 @@ services:
 
     # Healthcheck
     healthcheck:
-      test: [ "CMD-SHELL", "pg_isready -U $$(cat /run/secrets/db-user) -d ${POSTGRES_DB:-people}" ]
+      test: [ "CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}" ]
       interval: 10s
       timeout: 5s
       retries: 5
@@ -418,6 +425,71 @@ services:
     # Shared memory size (important for PostgreSQL)
     shm_size: 256mb
 
+  # ==========================================================================
+  # KEYCLOAK - Identity and Access Management
+  # ==========================================================================
+  keycloak:
+    image: quay.io/keycloak/keycloak:26.4
+    container_name: keycloak
+    
+    cap_drop:
+      - ALL
+    
+    security_opt:
+      - no-new-privileges:true
+    
+    restart: unless-stopped
+    
+    networks:
+      - backend
+    
+    expose:
+      - "8080"
+
+    # Ports: DO NOT expose externally in production
+    # ports:
+    #   - "8080:8080"  # ❌ For debug only, remove in production
+    
+    secrets:
+      - keycloak-db-password
+      - keycloak-admin-password
+
+    env_file:
+      - .env
+    
+    command: start-dev
+    
+    depends_on:
+      db:
+        condition: service_healthy
+    
+    healthcheck:
+      test: ["CMD-SHELL", "exec 3<>/dev/tcp/keycloak/9000 && echo -e 'GET /health/ready HTTP/1.1\r\nHost: keycloak\r\nConnection: close\r\n\r\n' >&3 && cat <&3 | grep -q '200 OK'"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 90s  # Keycloak takes time to initialize
+    
+    deploy:
+      resources:
+        limits:
+          cpus: '0.5'
+          memory: 512M
+        reservations:
+          cpus: '0.25'
+          memory: 256M
+    
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "50m"
+        max-file: "3"
+    
+    labels:
+      service: "keycloak"
+      tier: "backend"
+      environment: "${ENVIRONMENT:-production}"
+
 # ============================================================================
 # INITIALIZATION
 # ============================================================================

pom.xml

@@ -119,6 +119,24 @@
             <artifactId>commons-lang3</artifactId>
             <version>3.20.0</version>
         </dependency>
+
+        <!-- Spring Security OAuth2 Resource Server - validates tokens -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
+        </dependency>
+
+        <!-- OAuth2 Client - for Swagger and login flows -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-oauth2-client</artifactId>
+        </dependency>
+
+        <!-- JWT Support -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-security</artifactId>
+        </dependency>
     </dependencies>
 
     <build>

postgres/init/00-init-databases.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+set -e
+
+# Read passwords from Docker secrets
+KEYCLOAK_DB_PASSWORD=$(cat /run/secrets/keycloak-db-password)
+API_DB_PASSWORD=$(cat /run/secrets/api-db-password)
+
+# Execute SQL with environment variables
+psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" <<-EOSQL
+    -- ============================================================================
+    -- PostgreSQL Initialization Script
+    -- Creates separate databases and users for each application
+    -- ============================================================================
+
+    -- Create database and user for Keycloak
+    CREATE DATABASE keycloak;
+    CREATE USER keycloak WITH PASSWORD '$KEYCLOAK_DB_PASSWORD';
+    ALTER DATABASE keycloak OWNER TO keycloak;
+
+    -- Connect to keycloak database
+    \c keycloak
+
+    -- Grant usage and create privileges on public schema
+    GRANT ALL PRIVILEGES ON SCHEMA public TO keycloak;
+    GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO keycloak;
+    GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO keycloak;
+    
+    -- Grant default privileges for future objects
+    ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO keycloak;
+    ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO keycloak;
+
+    ----------------------------------------------------------------------------
+
+    -- Create database and user for People API
+    \c postgres
+    CREATE DATABASE people;
+    CREATE USER people WITH PASSWORD '$API_DB_PASSWORD';
+    ALTER DATABASE people OWNER TO people;
+
+    -- Connect to keycloak database
+    \c people
+    
+    -- Grant usage and create privileges on public schema
+    GRANT ALL PRIVILEGES ON SCHEMA public TO people;
+    GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO people;
+    GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO people;
+    
+    -- Grant default privileges for future objects
+    ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO people;
+    ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO people;
+
+    -- Return to postgres database
+    \c postgres
+EOSQL
+
+echo "Database initialization completed successfully!"

secrets/db-user.txt.example secrets/api-db-password.txt.examplesecrets/db-user.txt.example renamed to secrets/api-db-password.txt.example

@@ -1 +1 @@
-people
+postgres

secrets/db-password.txt.example

@@ -0,0 +1 @@
+admin

secrets/keycloak-admin-password.txt.example

@@ -0,0 +1 @@
+keycloak