Self-Host Keycloak: Enterprise-Grade SSO in 15 Minutes

Introduction

Managing user authentication across multiple applications is a nightmare. You have credentials scattered everywhere, users forgetting passwords, and zero centralized control. Keycloak solves this by providing enterprise-grade Single Sign-On (SSO), identity brokering, and user federation — all open-source and self-hosted.

Why self-host Keycloak instead of using Auth0 or Okta? No per-user pricing, full data sovereignty, and no vendor lock-in. You control your identity infrastructure. Let's get it running.

Prerequisites

• A VPS with at least 2 CPU cores, 4GB RAM (Keycloak is Java-based and memory-hungry)
• Docker & Docker Compose installed
• A domain/subdomain pointing to your server (e.g., auth.yourdomain.com)
• Reverse proxy (Traefik/Nginx) handling SSL termination (recommended)

Step-by-Step Setup

1. Create the Docker Compose File

Create a directory and docker-compose.yml:

mkdir -p ~/keycloak && cd ~/keycloak

version: '3.8'

services:
  keycloak-db:
    image: postgres:15-alpine
    container_name: keycloak-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: your-secure-db-password
    volumes:
      - keycloak-db-data:/var/lib/postgresql/data
    networks:
      - keycloak-net

  keycloak:
    image: quay.io/keycloak/keycloak:24.0
    container_name: keycloak
    restart: unless-stopped
    command: start --optimized
    environment:
      KC_HOSTNAME: auth.yourdomain.com
      KC_PROXY: edge
      KC_HTTP_ENABLED: "true"
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://keycloak-db:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: your-secure-db-password
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: your-secure-admin-password
      KC_HEALTH_ENABLED: "true"
      KC_METRICS_ENABLED: "true"
    ports:
      - "8080:8080"
    depends_on:
      - keycloak-db
    networks:
      - keycloak-net

volumes:
  keycloak-db-data:

networks:
  keycloak-net:
    driver: bridge

Key changes for production:

• Replace auth.yourdomain.com with your actual domain
• Change both password values to strong, unique passwords
• KC_PROXY: edge tells Keycloak it's behind a reverse proxy handling SSL

2. Launch Keycloak

docker compose up -d

Wait 30-60 seconds for the database to initialize and Keycloak to start.

3. Verify It's Running

curl http://localhost:8080/health/ready

Should return {"status": "up"}.

Access the admin console at https://auth.yourdomain.com/admin and log in with the admin credentials from your compose file.

4. Configure Your First Realm

1. Create a realm: Click the realm dropdown → "Create realm"
   • Name it after your organization (e.g., sysbrix)
2. Create a client for your application:
   • Go to Clients → Create client
   • Client ID: my-app
   • Client authentication: ON
   • Authentication flow: Standard flow (checked)
   • Valid redirect URIs: https://app.yourdomain.com/*
   • Web origins: https://app.yourdomain.com
3. Create a test user:
   • Users → Add user
   • Set username, email, first/last name
   • Credentials tab → Set password → Temporary OFF

5. Integrate SSO Into Your App

Keycloak supports OpenID Connect (OIDC) and SAML 2.0. Here's a minimal OIDC redirect example:

Authorization URL:
https://auth.yourdomain.com/realms/sysbrix/protocol/openid-connect/auth
?client_id=my-app
&redirect_uri=https://app.yourdomain.com/callback
&response_type=code
&scope=openid profile email

Most frameworks have Keycloak adapters: NextAuth.js, Passport.js, Spring Security, Django OAuth Toolkit, etc.

Verification Checklist

• [ ] Admin console loads at https://auth.yourdomain.com/admin
• [ ] Health endpoint returns {"status": "up"}
• [ ] Can create realms, clients, and users
• [ ] Test login flow works with a sample application
• [ ] Database persists across container restarts

Next Steps

• Enable 2FA: Go to Authentication → Required Actions → Configure OTP
• Add LDAP/AD federation: User Federation → Add provider → ldap
• Set up social logins: Identity Providers → Add provider → Google/GitHub
• Configure brute-force protection: Realm settings → Security defenses
• Back up your database: docker exec keycloak-db pg_dump -U keycloak keycloak > backup.sql

Related Guides

• Self-Host Authelia: Lightweight SSO for Homelab
• Self-Host Traefik: The Ultimate Reverse Proxy
• Self-Host Grafana: Monitor Your Infrastructure

Keycloak gives you Auth0-level identity management without the Auth0 bill. Your users (and your wallet) will thank you.