This page covers common configuration steps for Keycloak deployments.
Keycloak supports multiple configuration approaches depending on your deployment:
For container deployments, use environment variables prefixed with KC_:
# Example environment variables
KC_DB=postgres
KC_DB_URL=jdbc:postgresql://localhost:5432/keycloak
KC_DB_USERNAME=keycloak
KC_DB_PASSWORD=password
KC_HTTP_ENABLED=true
KC_PROXY=reverse
KC_HOSTNAME_STRICT=false
KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=change-me
For traditional deployments, use command-line arguments:
# Example command line
bin/kc.sh start --db=postgres --db-url=jdbc:postgresql://localhost:5432/keycloak --hostname=your-domain.com --proxy=reve
Configure your database connection:
# PostgreSQL
KC_DB=postgres
KC_DB_URL=jdbc:postgresql://localhost:5432/keycloak
KC_DB_SCHEMA=public
KC_DB_USERNAME=keycloak
KC_DB_PASSWORD=password
# MySQL
KC_DB=mysql
KC_DB_URL=jdbc:mysql://localhost:3306/keycloak
KC_DB_USERNAME=keycloak
KC_DB_PASSWORD=password
Configure network settings:
# Hostname and HTTPS
--hostname=your-domain.com
--https-certificate-file=path/to/cert.pem
--https-certificate-key-file=path/to/key.pem
# Behind reverse proxy
KC_PROXY=reverse
KC_PROXY-ADDRESS-FORWARDED=true
KC_HTTP_RELATIVE_PATH=/auth
Configure authentication flows:
# Enable specific authentication methods
KC_SPI_THEME_DEFAULT=crypto
KC_FEATURES=token-exchange,admin-fine-grained-authz,scripts-impl-kotlin
Optimize caching for performance:
# Cache configuration
KC_CACHE=ispn
KC_CACHE_STACK=kubernetes
KC_CLUSTER=enabled
# Build and start with production settings
bin/kc.sh build --db=postgres --db-url=jdbc:postgresql://localhost:5432/keycloak --db-username=keycloak --db-password=password
bin/kc.sh start --hostname=your-domain.com --https-certificate-file=path/to/cert.pem --https-certificate-key-file=path/to/key.pem --proxy=reve
# docker-compose.yml
version: '3.8'
services:
keycloak:
image: quay.io/keycloak/keycloak:26.5.3
command: start
environment:
KC_DB: postgres
KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
KC_DB_USERNAME: keycloak
KC_DB_PASSWORD: password
KC_HTTP_ENABLED: true
KC_PROXY: reverse
KC_HOSTNAME_STRICT: false
KEYCLOAK_ADMIN: admin
KEYCLOAK_ADMIN_PASSWORD: change-me
ports:
- "8080:8080"
bin/kc.sh build)Run these checks to confirm configuration is valid:
# Health check
curl -v http://localhost:8080/health/ready
# Admin console access
# Navigate to https://your-domain.com/auth/admin
# Test authentication flow
# Try logging in through the account console
For clustered Keycloak behind a reverse proxy:
upstream keycloak_backend {
ip_hash; # Enable sticky sessions
server keycloak1:8080;
server keycloak2:8080;
}
server {
listen 443 ssl;
server_name sso.example.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://keycloak_backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
}
}
# Enable clustering
KC_CACHE=ispn
KC_CACHE_STACK=tcp
KC_CLUSTER=enabled
# Set log level
KC_LOG_LEVEL=INFO,WARN,org.keycloak:DEBUG
# Log format
KC_LOG_FILE_FORMATTER=json
Keycloak exposes metrics via JMX and Prometheus endpoints when configured.
Running Keycloak in regulated environments? We assist with:
Secure your deployment: office@linux-server-admin.com | Contact Page