docker.recipes

Keycloak Identity Server

advanced

Keycloak identity and access management with PostgreSQL backend for enterprise SSO.

Overview

Keycloak is an open-source identity and access management solution developed by Red Hat that provides single sign-on (SSO), identity brokering, and user federation capabilities for modern applications. Originally created to simplify authentication and authorization in enterprise environments, Keycloak supports industry-standard protocols like OpenID Connect, OAuth 2.0, and SAML 2.0, making it a comprehensive solution for securing web applications, REST services, and microservices architectures. This stack combines Keycloak with PostgreSQL as the backend database, creating a robust and scalable identity management platform. PostgreSQL's ACID compliance and advanced transaction support ensure data integrity for user credentials, roles, and session information, while its JSON support enables flexible storage of user attributes and configuration data. The combination provides enterprise-grade reliability with PostgreSQL handling high-concurrency authentication requests and Keycloak managing complex authorization policies across multiple applications and services. This configuration is ideal for organizations implementing centralized authentication, software teams building microservices that need unified user management, and enterprises modernizing legacy applications with modern SSO capabilities. The PostgreSQL backend makes this setup production-ready for high-availability deployments, supporting thousands of concurrent users while maintaining the flexibility to integrate with existing LDAP directories, Active Directory, or social identity providers like Google and GitHub.

Key Features

  • Single Sign-On (SSO) across multiple applications with session management
  • OpenID Connect, OAuth 2.0, and SAML 2.0 protocol support for modern and legacy integrations
  • Identity brokering with social logins (Google, Facebook, GitHub) and enterprise providers
  • User federation with LDAP and Active Directory integration
  • Multi-tenant realm support for organization separation and branding
  • Fine-grained role-based access control (RBAC) and attribute-based policies
  • PostgreSQL backend for enterprise-grade data persistence and ACID compliance
  • Customizable login themes and user registration flows

Common Use Cases

  • 1Enterprise SSO implementation for employees accessing multiple internal applications
  • 2Microservices authentication with centralized user management and JWT token validation
  • 3SaaS application user management with multi-tenant organization support
  • 4Legacy application modernization by adding OAuth2/OIDC authentication layers
  • 5API gateway authentication for REST services and third-party integrations
  • 6Developer portal authentication with GitHub/GitLab integration for code repositories
  • 7Customer identity and access management (CIAM) for e-commerce and web applications

Prerequisites

  • Minimum 1.5GB RAM for both Keycloak (1GB) and PostgreSQL (512MB) containers
  • Port 8080 available for Keycloak admin console and authentication endpoints
  • Basic understanding of OAuth2/OpenID Connect flows and JWT tokens
  • Knowledge of realm configuration and client application setup in Keycloak
  • Understanding of PostgreSQL connection management for production scaling
  • SSL/TLS certificates for production deployment (development uses HTTP)

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

docker-compose.yml

docker-compose.yml
1services: 
2  keycloak: 
3    image: quay.io/keycloak/keycloak:23.0
4    container_name: keycloak
5    command: start-dev
6    environment: 
7      - KC_DB=postgres
8      - KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak
9      - KC_DB_USERNAME=${KEYCLOAK_DB_USER}
10      - KC_DB_PASSWORD=${KEYCLOAK_DB_PASSWORD}
11      - KEYCLOAK_ADMIN=${KEYCLOAK_ADMIN}
12      - KEYCLOAK_ADMIN_PASSWORD=${KEYCLOAK_ADMIN_PASSWORD}
13      - KC_HOSTNAME_STRICT=false
14      - KC_HTTP_ENABLED=true
15    ports: 
16      - "8080:8080"
17    depends_on: 
18      postgres: 
19        condition: service_healthy
20    networks: 
21      - keycloak-network
22
23  postgres: 
24    image: postgres:16-alpine
25    container_name: keycloak-db
26    environment: 
27      - POSTGRES_DB=keycloak
28      - POSTGRES_USER=${KEYCLOAK_DB_USER}
29      - POSTGRES_PASSWORD=${KEYCLOAK_DB_PASSWORD}
30    volumes: 
31      - postgres_data:/var/lib/postgresql/data
32    healthcheck: 
33      test: ["CMD-SHELL", "pg_isready -U ${KEYCLOAK_DB_USER} -d keycloak"]
34      interval: 10s
35      timeout: 5s
36      retries: 5
37    networks: 
38      - keycloak-network
39
40volumes: 
41  postgres_data: 
42
43networks: 
44  keycloak-network: 
45    driver: bridge

.env Template

.env
1# Keycloak Identity Server
2KEYCLOAK_ADMIN=admin
3KEYCLOAK_ADMIN_PASSWORD=changeme123
4KEYCLOAK_DB_USER=keycloak
5KEYCLOAK_DB_PASSWORD=keycloak_secure_password

Usage Notes

  1. 1Admin console at http://localhost:8080
  2. 2Use 'start' instead of 'start-dev' for production
  3. 3Configure KC_HOSTNAME for production
  4. 4Supports LDAP, SAML, OIDC protocols
  5. 5Create realms for multi-tenant setup

Individual Services(2 services)

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

keycloak
keycloak:
  image: quay.io/keycloak/keycloak:23.0
  container_name: keycloak
  command: start-dev
  environment:
    - KC_DB=postgres
    - KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak
    - KC_DB_USERNAME=${KEYCLOAK_DB_USER}
    - KC_DB_PASSWORD=${KEYCLOAK_DB_PASSWORD}
    - KEYCLOAK_ADMIN=${KEYCLOAK_ADMIN}
    - KEYCLOAK_ADMIN_PASSWORD=${KEYCLOAK_ADMIN_PASSWORD}
    - KC_HOSTNAME_STRICT=false
    - KC_HTTP_ENABLED=true
  ports:
    - "8080:8080"
  depends_on:
    postgres:
      condition: service_healthy
  networks:
    - keycloak-network
postgres
postgres:
  image: postgres:16-alpine
  container_name: keycloak-db
  environment:
    - POSTGRES_DB=keycloak
    - POSTGRES_USER=${KEYCLOAK_DB_USER}
    - POSTGRES_PASSWORD=${KEYCLOAK_DB_PASSWORD}
  volumes:
    - postgres_data:/var/lib/postgresql/data
  healthcheck:
    test:
      - CMD-SHELL
      - pg_isready -U ${KEYCLOAK_DB_USER} -d keycloak
    interval: 10s
    timeout: 5s
    retries: 5
  networks:
    - keycloak-network

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  keycloak:
5    image: quay.io/keycloak/keycloak:23.0
6    container_name: keycloak
7    command: start-dev
8    environment:
9      - KC_DB=postgres
10      - KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak
11      - KC_DB_USERNAME=${KEYCLOAK_DB_USER}
12      - KC_DB_PASSWORD=${KEYCLOAK_DB_PASSWORD}
13      - KEYCLOAK_ADMIN=${KEYCLOAK_ADMIN}
14      - KEYCLOAK_ADMIN_PASSWORD=${KEYCLOAK_ADMIN_PASSWORD}
15      - KC_HOSTNAME_STRICT=false
16      - KC_HTTP_ENABLED=true
17    ports:
18      - "8080:8080"
19    depends_on:
20      postgres:
21        condition: service_healthy
22    networks:
23      - keycloak-network
24
25  postgres:
26    image: postgres:16-alpine
27    container_name: keycloak-db
28    environment:
29      - POSTGRES_DB=keycloak
30      - POSTGRES_USER=${KEYCLOAK_DB_USER}
31      - POSTGRES_PASSWORD=${KEYCLOAK_DB_PASSWORD}
32    volumes:
33      - postgres_data:/var/lib/postgresql/data
34    healthcheck:
35      test: ["CMD-SHELL", "pg_isready -U ${KEYCLOAK_DB_USER} -d keycloak"]
36      interval: 10s
37      timeout: 5s
38      retries: 5
39    networks:
40      - keycloak-network
41
42volumes:
43  postgres_data:
44
45networks:
46  keycloak-network:
47    driver: bridge
48EOF
49
50# 2. Create the .env file
51cat > .env << 'EOF'
52# Keycloak Identity Server
53KEYCLOAK_ADMIN=admin
54KEYCLOAK_ADMIN_PASSWORD=changeme123
55KEYCLOAK_DB_USER=keycloak
56KEYCLOAK_DB_PASSWORD=keycloak_secure_password
57EOF
58
59# 3. Start the services
60docker compose up -d
61
62# 4. View logs
63docker 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-postgres-ha/run | bash

Troubleshooting

  • Keycloak fails to start with database connection errors: Ensure PostgreSQL container is fully initialized before Keycloak starts using the healthcheck dependency
  • Admin console shows 'invalid_request' errors: Set KC_HOSTNAME to match your domain or use KC_HOSTNAME_STRICT=false for development
  • PostgreSQL connection pool exhausted: Increase max_connections in PostgreSQL configuration or tune Keycloak's database pool settings
  • Keycloak performance issues with many users: Enable PostgreSQL connection pooling and increase shared_buffers memory allocation
  • SSL/HTTPS errors in production: Configure KC_HOSTNAME_URL and KC_HOSTNAME_ADMIN_URL with proper HTTPS URLs and disable KC_HTTP_ENABLED
  • User sessions not persisting: Verify PostgreSQL data volume is properly mounted and check for database connection interruptions

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

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

Components

keycloakpostgres

Tags

#keycloak#sso#identity#oauth#oidc#authentication

Category

Security & Networking

Related Recipes

Ad Space