SAML SSO Docker Deployment Guide

version: "3.9"

networks:
  ft-network:
    name: ft-shared-network
    driver: bridge

services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    command: start --hostname=https://<DOCKER_HOST>:8500
    volumes:
     - ./<YOUR.crt>.crt:/opt/keycloak/conf/server.crt
     - ./<YOUR.key>.key:/opt/keycloak/conf/server.key
    environment:
      KC_LOG_LEVEL: "INFO,org.keycloak.protocol.saml:DEBUG,org.keycloak.saml:DEBUG,org.keycloak.events:DEBUG"
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
      KC_HTTPS_CERTIFICATE_FILE: /opt/keycloak/conf/server.crt
      KC_HTTPS_CERTIFICATE_KEY_FILE: /opt/keycloak/conf/server.key
    ports:
      - "8500:8443"
    networks:
      - ft-network

# Start the Keycloak stack in detached mode
docker compose -f compose-saml.yml up -d

# Verify container are running and healthy
docker compose -f compose-saml.yml ps

# Check Keycloak startup logs
docker logs keycloak --tail 50

https://localhost:8500/admin

https://portal.example.com/support-portal/login/auth-callback?token=eyJhbG...&sessionHash=BASE64...

# ==========================================================
# SAML Configuration for Docker Deployment
# ==========================================================

SAML_ENABLED=true

# --- SC (Support Center) SP registration ---
SAML_SC_SP_ENTITY_ID=oneiot-sp-sc
SAML_SUCCESS_REDIRECT=https://<DOCKER_HOST>:8843/support-portal/login/auth-callback

# --- MC (Management Console) SP registration ---
SAML_MC_SP_ENTITY_ID=oneiot-sp-mc
SAML_MC_SUCCESS_REDIRECT=https://<DOCKER_HOST>:8843/management-portal/login/auth-callback

# --- IdP (Keycloak running in Docker) ---
# Use the Docker container name as hostname for server-to-server communication
SAML_IDP_ENTITY_ID=https://<DOCKER_HOST>:8500/realms/oneiot
SAML_IDP_SSO_URL=https://<DOCKER_HOST>:8500/realms/oneiot/protocol/saml

# --- Attribute mapping (defaults shown) ---
SAML_ATTR_USERNAME=username
SAML_ATTR_EMAIL=email
SAML_ATTR_CLIENT_TYPE=portal-type
SAML_ATTR_DOMAIN=domain
SAML_ATTR_USER_GROUP=user-group
SAML_ATTR_EXPIRE_DATE=expire-date

-----BEGIN CERTIFICATE-----
MIICnTCCAYUCBgGE... (base64-encoded certificate data)
...
-----END CERTIFICATE-----

# 1. Ensure Keycloak is running and healthy
docker compose -f compose-saml.yml ps
# Expected: keycloak (healthy), if exist: keycloak-db (healthy)

# 2. Verify the shared network exists
docker network ls | grep ft-shared-network

# 3. Start the backend stack with both env files
cd iot-web-app-build/docker
docker compose --env-file .env.mysql --env-file .env.saml up -d

# 4. Verify the backend can reach Keycloak via the shared network
docker exec <backend-container> curl -s http://keycloak:8080/realms/oneiot/.well-known/openid-configuration | head -5

# 5. Verify SAML metadata is published by the backend
curl http://localhost:8880/iot-webservice/saml2/metadata/saml-support-portal

# Check that the shared network exists
docker network inspect saml-shared-network

# List containers connected to the shared network
docker network inspect saml-shared-network --format '{{range .Containers}}{{.Name}} {{end}}'

# Test DNS resolution from the backend container
docker exec <backend-container> ping -c 3 keycloak

# Test Keycloak SAML descriptor endpoint from the backend container
docker exec <backend-container> curl -sf http://keycloak:8080/realms/oneiot/protocol/saml/descriptor | head -5

/usr/local/ft-services/
├── compose-saml.yml                     # Keycloak stack (from this guide)
├── compose.yml                          # OneIoT stack (from iot-web-app-build/docker/)
├── .env.mysql                           # Database env (from iot-web-app-build/docker/)
├── .env.saml                            # SAML env (filled in from template)
├── ui-backend-conf/
│   ├── hazelcast-client.xml             # Main Hazelcast client configuration
│   ├── ftacs.keystore                   # Backend keystore used when HTTPS is enabled
│   ├── logback-spring.xml               # Default external logging configuration
│   ├── interfaceItems.json              # Interface seed data, loaded if present
│   ├── idp.crt                          # Exported from Keycloak after setup
│   ├── sp.key (optional)                # Generated SP private key
│   ├── sp.crt (optional)                # Generated SP certificate
│   ├── customization/
│   │   ├── def/
│   │   ├── mc/
│   │   └── sc/
│   └── ssl/                             # HTTPS certificates for Nginx/portals when configured
└── ft-data/ui-portals/
    ├── backend/logs/
    └── nginx/logs/