Keycloak Identity Management

intermediate

Open-source identity and access management with SSO, OAuth2, OIDC, and SAML support. PostgreSQL backend for production reliability.

Overview

Keycloak is an open-source identity and access management solution developed by Red Hat that provides comprehensive authentication and authorization services for modern applications. Originally created to simplify single sign-on (SSO) implementation, Keycloak has evolved into a full-featured identity provider supporting industry-standard protocols including OAuth 2.0, OpenID Connect (OIDC), and SAML 2.0, making it essential for securing microservices architectures and enterprise applications. This deployment consists of two services: a PostgreSQL 15 Alpine database (keycloak-db) for persistent storage and the Keycloak application server itself. The PostgreSQL backend provides production-grade data persistence for user accounts, roles, sessions, and configuration data, replacing Keycloak's default H2 embedded database. The setup includes health checks for reliable startup sequencing and exposes metrics endpoints for monitoring. This configuration is ideal for organizations requiring self-hosted identity management with enterprise-grade database backing. Development teams building microservices, IT departments implementing SSO across multiple applications, and organizations with compliance requirements will benefit from this combination of Keycloak's flexible identity features and PostgreSQL's ACID-compliant data storage.

Key Features

Single Sign-On (SSO) with support for OAuth 2.0, OpenID Connect, and SAML 2.0 protocols
Multi-tenant realm architecture for isolating different applications and user groups
Identity brokering with social login providers (Google, Facebook, GitHub) and enterprise directories
User federation capabilities for LDAP and Active Directory integration
Fine-grained authorization policies with role-based and attribute-based access control
Customizable login pages and authentication flows with theme support
Built-in admin console with REST API for programmatic management
PostgreSQL backend ensuring ACID compliance and reliable data persistence

Common Use Cases

1Enterprise single sign-on implementation across web applications and services
2Microservices authentication with centralized token management and validation
3API gateway security with OAuth 2.0 token introspection and validation
4Legacy application modernization by adding modern authentication protocols
5Multi-tenant SaaS platforms requiring isolated user management per customer
6Development environments needing realistic identity management for testing
7Organizations migrating from proprietary identity solutions to open-source alternatives

Prerequisites

Docker and Docker Compose installed with minimum 1.5GB available RAM
Environment variables configured: DB_PASSWORD, ADMIN_USER, ADMIN_PASSWORD
Port 8080 available for Keycloak web interface (customizable via KC_PORT)
Basic understanding of OAuth 2.0/OIDC concepts for realm and client configuration
Knowledge of PostgreSQL for database maintenance and backup procedures
Understanding of identity management concepts like realms, roles, and scopes

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  keycloak-db: 
3    image: postgres:15-alpine
4    container_name: keycloak-db
5    restart: unless-stopped
6    environment: 
7      - POSTGRES_USER=keycloak
8      - POSTGRES_PASSWORD=${DB_PASSWORD}
9      - POSTGRES_DB=keycloak
10    volumes: 
11      - keycloak_db_data:/var/lib/postgresql/data
12    healthcheck: 
13      test: ["CMD-SHELL", "pg_isready -U keycloak"]
14      interval: 10s
15      timeout: 5s
16      retries: 5
17
18  keycloak: 
19    image: quay.io/keycloak/keycloak:latest
20    container_name: keycloak
21    restart: unless-stopped
22    ports: 
23      - "${KC_PORT:-8080}:8080"
24    environment: 
25      - KC_DB=postgres
26      - KC_DB_URL=jdbc:postgresql://keycloak-db:5432/keycloak
27      - KC_DB_USERNAME=keycloak
28      - KC_DB_PASSWORD=${DB_PASSWORD}
29      - KEYCLOAK_ADMIN=${ADMIN_USER}
30      - KEYCLOAK_ADMIN_PASSWORD=${ADMIN_PASSWORD}
31      - KC_HEALTH_ENABLED=true
32      - KC_METRICS_ENABLED=true
33    command: start-dev
34    depends_on: 
35      keycloak-db: 
36        condition: service_healthy
37
38volumes: 
39  keycloak_db_data:

.env Template

.env

1# Keycloak Configuration
2KC_PORT=8080
3ADMIN_USER=admin
4ADMIN_PASSWORD=change_this_admin_password
5
6# Database
7DB_PASSWORD=keycloak_db_password

Usage Notes

1Access Keycloak at http://localhost:8080
2Admin console at http://localhost:8080/admin
3Create realms to isolate different applications
4For production, use 'start' instead of 'start-dev' and configure hostname
5Supports OAuth2, OIDC, SAML 2.0 protocols
6Health endpoint at /health, metrics at /metrics

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

keycloak-db

keycloak-db:
  image: postgres:15-alpine
  container_name: keycloak-db
  restart: unless-stopped
  environment:
    - POSTGRES_USER=keycloak
    - POSTGRES_PASSWORD=${DB_PASSWORD}
    - POSTGRES_DB=keycloak
  volumes:
    - keycloak_db_data:/var/lib/postgresql/data
  healthcheck:
    test:
      - CMD-SHELL
      - pg_isready -U keycloak
    interval: 10s
    timeout: 5s
    retries: 5

keycloak

keycloak:
  image: quay.io/keycloak/keycloak:latest
  container_name: keycloak
  restart: unless-stopped
  ports:
    - ${KC_PORT:-8080}:8080
  environment:
    - KC_DB=postgres
    - KC_DB_URL=jdbc:postgresql://keycloak-db:5432/keycloak
    - KC_DB_USERNAME=keycloak
    - KC_DB_PASSWORD=${DB_PASSWORD}
    - KEYCLOAK_ADMIN=${ADMIN_USER}
    - KEYCLOAK_ADMIN_PASSWORD=${ADMIN_PASSWORD}
    - KC_HEALTH_ENABLED=true
    - KC_METRICS_ENABLED=true
  command: start-dev
  depends_on:
    keycloak-db:
      condition: service_healthy

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  keycloak-db:
5    image: postgres:15-alpine
6    container_name: keycloak-db
7    restart: unless-stopped
8    environment:
9      - POSTGRES_USER=keycloak
10      - POSTGRES_PASSWORD=${DB_PASSWORD}
11      - POSTGRES_DB=keycloak
12    volumes:
13      - keycloak_db_data:/var/lib/postgresql/data
14    healthcheck:
15      test: ["CMD-SHELL", "pg_isready -U keycloak"]
16      interval: 10s
17      timeout: 5s
18      retries: 5
19
20  keycloak:
21    image: quay.io/keycloak/keycloak:latest
22    container_name: keycloak
23    restart: unless-stopped
24    ports:
25      - "${KC_PORT:-8080}:8080"
26    environment:
27      - KC_DB=postgres
28      - KC_DB_URL=jdbc:postgresql://keycloak-db:5432/keycloak
29      - KC_DB_USERNAME=keycloak
30      - KC_DB_PASSWORD=${DB_PASSWORD}
31      - KEYCLOAK_ADMIN=${ADMIN_USER}
32      - KEYCLOAK_ADMIN_PASSWORD=${ADMIN_PASSWORD}
33      - KC_HEALTH_ENABLED=true
34      - KC_METRICS_ENABLED=true
35    command: start-dev
36    depends_on:
37      keycloak-db:
38        condition: service_healthy
39
40volumes:
41  keycloak_db_data:
42EOF
43
44# 2. Create the .env file
45cat > .env << 'EOF'
46# Keycloak Configuration
47KC_PORT=8080
48ADMIN_USER=admin
49ADMIN_PASSWORD=change_this_admin_password
50
51# Database
52DB_PASSWORD=keycloak_db_password
53EOF
54
55# 3. Start the services
56docker compose up -d
57
58# 4. View logs
59docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/keycloak-identity-stack/run | bash

Troubleshooting

keycloak container fails to start: Ensure DB_PASSWORD environment variable is set and matches between both services
Database connection errors in keycloak logs: Verify keycloak-db service is healthy and PostgreSQL accepts connections on port 5432
Admin console login fails: Check ADMIN_USER and ADMIN_PASSWORD environment variables are properly configured
Slow startup times: Increase PostgreSQL shared_buffers and effective_cache_size, or allocate more RAM to containers
Health check failures on keycloak-db: Ensure PostgreSQL service has sufficient time to initialize, increase healthcheck timeout if needed
Memory issues during realm import: Increase container memory limits and consider using production mode with 'start' command instead of 'start-dev'

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

keycloakpostgresql

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download