Keycloak

intermediate

Open source identity and access management.

Overview

Keycloak is an open-source identity and access management solution originally developed by Red Hat that provides enterprise-grade authentication and authorization services. Born from the need to simplify complex identity management across distributed applications, Keycloak supports modern protocols like OpenID Connect, OAuth 2.0, and SAML 2.0, making it a cornerstone for implementing single sign-on (SSO) and centralized user management in modern architectures. This stack combines Keycloak with PostgreSQL to create a robust identity management platform where PostgreSQL serves as the production-grade database backend for storing user credentials, sessions, and configuration data. Unlike Keycloak's default H2 database which is suitable only for development, PostgreSQL provides the reliability, performance, and scalability needed for production identity workloads with proper ACID compliance and concurrent user support. This combination is ideal for organizations transitioning from development to production identity management, enterprises implementing SSO across multiple applications, and development teams building microservices that require centralized authentication. The PostgreSQL backend ensures data integrity for critical identity data while Keycloak's flexible realm and client model allows you to manage multiple applications and user groups from a single control plane.

Key Features

Multi-realm architecture for tenant isolation and organizational boundaries
OpenID Connect and OAuth 2.0 support for modern application integration
Social login integration with Google, Facebook, GitHub, and other providers
User federation with LDAP and Active Directory for enterprise environments
Fine-grained role-based access control with custom attributes and policies
Customizable login themes and user registration flows
PostgreSQL backend with ACID compliance for reliable identity data storage
Built-in admin console for realm management and user administration

Common Use Cases

1Enterprise SSO implementation across internal web applications and services
2Microservices authentication with JWT token validation and user context
3Customer identity management for SaaS platforms with multi-tenant requirements
4API security with OAuth 2.0 client credentials and access token validation
5Legacy application modernization by adding OIDC authentication layers
6Development environment identity services for testing authentication flows
7Homelab central authentication for self-hosted services like Grafana and GitLab

Prerequisites

Minimum 1.5GB RAM available (1GB for Keycloak, 512MB for PostgreSQL)
Port 8080 available for Keycloak web interface and API access
Basic understanding of OAuth 2.0/OIDC concepts and token-based authentication
Familiarity with realm and client configuration in identity management systems
Docker Compose environment with persistent volume support for database storage

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

docker-compose.yml

1services: 
2  keycloak: 
3    image: quay.io/keycloak/keycloak:latest
4    container_name: keycloak
5    command: start-dev
6    environment: 
7      KC_DB: postgres
8      KC_DB_URL: jdbc:postgresql://postgres:5432/${DB_NAME}
9      KC_DB_USERNAME: ${DB_USER}
10      KC_DB_PASSWORD: ${DB_PASSWORD}
11      KEYCLOAK_ADMIN: ${ADMIN_USER}
12      KEYCLOAK_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
13    ports: 
14      - "8080:8080"
15    depends_on: 
16      - postgres
17    networks: 
18      - keycloak
19
20  postgres: 
21    image: postgres:16-alpine
22    container_name: keycloak-postgres
23    environment: 
24      POSTGRES_DB: ${DB_NAME}
25      POSTGRES_USER: ${DB_USER}
26      POSTGRES_PASSWORD: ${DB_PASSWORD}
27    volumes: 
28      - postgres_data:/var/lib/postgresql/data
29    networks: 
30      - keycloak
31
32volumes: 
33  postgres_data: 
34
35networks: 
36  keycloak: 
37    driver: bridge

.env Template

.env

1DB_NAME=keycloak
2DB_USER=keycloak
3DB_PASSWORD=changeme
4ADMIN_USER=admin
5ADMIN_PASSWORD=changeme

Usage Notes

1Docs: https://www.keycloak.org/documentation
2Admin console at http://localhost:8080/admin
3Create realm for each app/org, then clients within realms
4For production: use 'start' instead of 'start-dev', add KC_HOSTNAME
5OIDC endpoint: /realms/{realm}/.well-known/openid-configuration
6Export realm: docker exec keycloak /opt/keycloak/bin/kc.sh export

Individual Services(2 services)

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

keycloak

keycloak:
  image: quay.io/keycloak/keycloak:latest
  container_name: keycloak
  command: start-dev
  environment:
    KC_DB: postgres
    KC_DB_URL: jdbc:postgresql://postgres:5432/${DB_NAME}
    KC_DB_USERNAME: ${DB_USER}
    KC_DB_PASSWORD: ${DB_PASSWORD}
    KEYCLOAK_ADMIN: ${ADMIN_USER}
    KEYCLOAK_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
  ports:
    - "8080:8080"
  depends_on:
    - postgres
  networks:
    - keycloak

postgres

postgres:
  image: postgres:16-alpine
  container_name: keycloak-postgres
  environment:
    POSTGRES_DB: ${DB_NAME}
    POSTGRES_USER: ${DB_USER}
    POSTGRES_PASSWORD: ${DB_PASSWORD}
  volumes:
    - postgres_data:/var/lib/postgresql/data
  networks:
    - keycloak

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  keycloak:
5    image: quay.io/keycloak/keycloak:latest
6    container_name: keycloak
7    command: start-dev
8    environment:
9      KC_DB: postgres
10      KC_DB_URL: jdbc:postgresql://postgres:5432/${DB_NAME}
11      KC_DB_USERNAME: ${DB_USER}
12      KC_DB_PASSWORD: ${DB_PASSWORD}
13      KEYCLOAK_ADMIN: ${ADMIN_USER}
14      KEYCLOAK_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
15    ports:
16      - "8080:8080"
17    depends_on:
18      - postgres
19    networks:
20      - keycloak
21
22  postgres:
23    image: postgres:16-alpine
24    container_name: keycloak-postgres
25    environment:
26      POSTGRES_DB: ${DB_NAME}
27      POSTGRES_USER: ${DB_USER}
28      POSTGRES_PASSWORD: ${DB_PASSWORD}
29    volumes:
30      - postgres_data:/var/lib/postgresql/data
31    networks:
32      - keycloak
33
34volumes:
35  postgres_data:
36
37networks:
38  keycloak:
39    driver: bridge
40EOF
41
42# 2. Create the .env file
43cat > .env << 'EOF'
44DB_NAME=keycloak
45DB_USER=keycloak
46DB_PASSWORD=changeme
47ADMIN_USER=admin
48ADMIN_PASSWORD=changeme
49EOF
50
51# 3. Start the services
52docker compose up -d
53
54# 4. View logs
55docker 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/run | bash

Troubleshooting

Keycloak fails to start with database connection errors: Verify PostgreSQL container is healthy and database credentials match between services
Admin console shows 'Invalid credentials' after setup: Check KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD environment variables are properly set
Applications can't reach OIDC endpoints: Ensure Keycloak is accessible at the hostname configured in your client applications, not just localhost
User sessions not persisting after container restart: Verify postgres_data volume is properly mounted and PostgreSQL is storing session data
High memory usage and slow performance: Increase Keycloak container memory limit and tune PostgreSQL shared_buffers for your user load
Realm export/import fails with permission errors: Run export commands with proper user permissions inside the container using docker exec

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

keycloakpostgres

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download