Keycloak — Open Source Identity & Access Management

What Keycloak Does

• Single Sign-On (SSO): One login for all your applications via OIDC and SAML
• Identity Brokering: Federate with external identity providers (Google, GitHub, Facebook, SAML IdPs)
• User Federation: Connect LDAP/Active Directory for centralized user management
• Multi-Factor Auth: TOTP, WebAuthn/FIDO2, SMS OTP, and email verification
• User Self-Service: Self-registration, password reset, profile management, and account linking
• Fine-Grained Authorization: Resource-based, role-based, and attribute-based access control
• Admin Console: Web-based admin UI for managing realms, clients, users, and roles
• Account Console: End-user portal for managing profile, sessions, and linked accounts
• Client Adapters: SDKs for Java, JavaScript, Node.js, Python, and more

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Applications│────▶│  Keycloak    │────▶│  PostgreSQL /│
│  (OIDC/SAML) │     │  Server      │     │  MySQL /     │
└──────────────┘     │  (Java/Quarkus)│   │  MariaDB     │
                     └──────┬───────┘     └──────────────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
       ┌──────┴──┐   ┌─────┴───┐   ┌─────┴───┐
       │  LDAP / │   │ Social  │   │ SAML    │
       │  AD     │   │ Login   │   │ IdPs    │
       └─────────┘   └─────────┘   └─────────┘

Self-Hosting

Docker Compose (Production)

services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    command: start
    ports:
      - "8080:8080"
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: keycloak
      KC_HOSTNAME: auth.yourdomain.com
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: your-admin-password
      KC_PROXY_HEADERS: xforwarded
    depends_on:
      - postgres

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: keycloak
      POSTGRES_DB: keycloak
    volumes:
      - pg-data:/var/lib/postgresql/data

volumes:
  pg-data:

Core Concepts

Realms

Keycloak Instance
├── Master Realm (admin only)
├── Company Realm
│   ├── Users & Groups
│   ├── Clients (Applications)
│   ├── Roles
│   ├── Identity Providers
│   └── Authentication Flows
└── Partner Realm
    ├── Users & Groups
    └── Clients

Each realm is an isolated identity namespace with its own users, clients, and settings.

Client Registration

{
  "clientId": "my-web-app",
  "protocol": "openid-connect",
  "rootUrl": "https://myapp.com",
  "redirectUris": ["https://myapp.com/callback"],
  "webOrigins": ["+"],
  "publicClient": true
}

Integration Example (Node.js)

const Keycloak = require('keycloak-connect');
const express = require('express');

const app = express();
const keycloak = new Keycloak({}, {
  realm: 'my-realm',
  'auth-server-url': 'http://localhost:8080',
  resource: 'my-web-app',
  'public-client': true,
});

app.use(keycloak.middleware());

// Protected route
app.get('/api/data', keycloak.protect(), (req, res) => {
  res.json({ user: req.kauth.grant.access_token.content });
});

// Role-based access
app.get('/api/admin', keycloak.protect('realm:admin'), (req, res) => {
  res.json({ message: 'Admin area' });
});

Custom Authentication Flows

Browser Login Flow:
  1. Cookie (check existing session)
  2. Identity Provider Redirector (SSO)
  3. Username/Password Form
  4. OTP Form (if MFA enabled)
  5. Conditional: WebAuthn (if passkey registered)

Keycloak vs Alternatives

FAQ

Q: Is Keycloak resource-heavy? A: Keycloak is built on Java/Quarkus and needs at least 512 MB RAM (1–2 GB recommended). It's heavier than Go alternatives (Zitadel uses ~200 MB) but significantly leaner than the old WildFly-era versions (~2 GB).

Q: How many users can it handle? A: A single instance can serve hundreds of thousands of users. For millions of users, use a clustered deployment (Keycloak supports Infinispan cluster caching). Large-enterprise deployments have been proven at tens of millions of users.

Q: Is migrating from Auth0 to Keycloak hard? A: Both support the OIDC standard, so application-level migration mostly means swapping SDK configuration. User data migration can be handled via Keycloak's User Storage SPI or bulk import API. Social login configurations need to be redone.

Sources & Credits

• GitHub: keycloak/keycloak — 33.8K+ ⭐ | Apache-2.0
• Website: keycloak.org