This guide covers installing and configuring Keycloak for the DDEC Web Application.
Keycloak is an open-source Identity and Access Management (IAM) solution that provides:
Download Keycloak from the official site:
# Extract to /opt/app
tar xvzf keycloak-20.0.1.tar.gz -C /opt/app/
# Set permissions
chmod 755 /opt/app/keycloak-20.0.1
Keycloak requires an admin user to be created before first startup.
Option A: Environment Variables
Add to /etc/profile.d/keycloak.sh:
export KEYCLOAK_ADMIN=admin
export KEYCLOAK_ADMIN_PASSWORD=<your-secure-password>
Then source the profile:
source /etc/profile.d/keycloak.sh
Option B: Web Interface
bin/kc.sh start-devImportant: Change the admin password after first login in production!
Edit /opt/app/keycloak-20.0.1/conf/keycloak.conf:
# Database Configuration
db=mssql
db-username=DDEC_APPL
db-password=<your-database-password>
db-url=jdbc:sqlserver://<SERVER_IP>:1433;databaseName=DDEC-KEYCLOAK;encrypt=true;trustServerCertificate=true;
db-driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
transaction-xa-enabled=false
Replace:
<SERVER_IP> - Your SQL Server hostname or IP<your-database-password> - Database user passwordFor production, Keycloak must run with HTTPS.
# SSL Certificate Configuration
https-certificate-file=/opt/app/keycloak-20.0.1/conf/<your-server>.crt
https-certificate-key-file=/opt/app/keycloak-20.0.1/conf/server.key
Certificate Requirements:
# Hostname Configuration
hostname=<your-keycloak-hostname>
# =============================================================================
# DDEC Keycloak Production Configuration
# =============================================================================
# Database - SQL Server
db=mssql
db-username=DDEC_APPL
db-password=YOUR_PASSWORD_HERE
db-url=jdbc:sqlserver://STNABDDCW1960.us590.corpintra.net:1433;databaseName=DDEC-KEYCLOAK;encrypt=true;trustServerCertificate=true;
db-driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
transaction-xa-enabled=false
# HTTPS Configuration
https-certificate-file=/opt/app/keycloak-20.0.1/conf/STNAADDCL1629.us590.corpintra.net.crt
https-certificate-key-file=/opt/app/keycloak-20.0.1/conf/server.key
# Hostname
hostname=stnaaddcl1629.us590.corpintra.net
# Optional: Health and Metrics
# health-enabled=true
# metrics-enabled=true
# Optional: Proxy Configuration (if behind reverse proxy)
# proxy=reencrypt
# spi-sticky-session-encoder-infinispan-should-attach-route=false
cd /opt/app/keycloak-20.0.1
bin/kc.sh start-dev
Access at: http://localhost:8080
cd /opt/app/keycloak-20.0.1
bin/kc.sh start
Access at: https://:8443
Create /etc/systemd/system/keycloak.service:
[Unit]
Description=Keycloak Server
After=network.target
[Service]
Type=simple
User=keycloak
Group=keycloak
Environment=KEYCLOAK_ADMIN=admin
Environment=KEYCLOAK_ADMIN_PASSWORD=initial-password
ExecStart=/opt/app/keycloak-20.0.1/bin/kc.sh start
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
Enable and start:
sudo systemctl daemon-reload
sudo systemctl enable keycloak
sudo systemctl start keycloak
A realm in Keycloak is an isolated security domain that manages:
Note: The
masterrealm is for Keycloak administration only. Always create a separate realm for applications.
DDECWEBDDECWEB realmSet Password:
DDECWEB realmddecweb-clienthttps://<ddec-server>:8080/*https://<ddec-server>:8080| Role Name | Description |
|---|---|
admin |
Full administrative access |
ddecuser |
Standard DDEC user access |
Guest |
Read-only access |
IOSCHD |
Batch job scheduling |
Configure the DDEC application to use Keycloak by updating application.yml:
keycloak:
realm: DDECWEB
resource: ddecweb-client
auth-server-url: https://<keycloak-hostname>:8443/auth
ssl-required: external
public-client: true
principal-attribute: preferred_username
use-resource-role-mappings: true
Environment-specific settings in ddec-{env}.properties:
# Development
keycloak.auth-server-url=https://localhost:8443/auth
# Production
keycloak.auth-server-url=https://stnaaddcl1629.us590.corpintra.net:8443/auth
| Issue | Cause | Solution |
|---|---|---|
| Can't access admin console | Admin user not created | Set KEYCLOAK_ADMIN environment variables and restart |
| Database connection failed | Wrong credentials or server unreachable | Verify db-url and credentials in keycloak.conf |
| SSL certificate error | Certificate doesn't match hostname | Ensure certificate CN matches server hostname |
| Redirect URI mismatch | Valid redirect URIs not configured | Add correct URI in client settings |
| User can't log in | Password not set or temporary | Set password with Temporary=Off |
/opt/app/keycloak-20.0.1/data/log/journalctl -u keycloak)# Check Keycloak status
systemctl status keycloak
# View logs
journalctl -u keycloak -f
# Restart Keycloak
systemctl restart keycloak
# Build optimized Keycloak (production)
bin/kc.sh build
# Export realm configuration
bin/kc.sh export --dir /tmp/export --realm DDECWEB
Since Keycloak stores all data in SQL Server, regular database backups are essential:
BACKUP DATABASE [DDEC-KEYCLOAK]
TO DISK = '/backup/DDEC-KEYCLOAK.bak'
WITH FORMAT, COMPRESSION;
Export realm configuration for disaster recovery:
bin/kc.sh export --dir /backup/keycloak --realm DDECWEB
Restore realm from backup:
bin/kc.sh import --dir /backup/keycloak