Keycloak SSO Setup: Realm Config, LDAP Integration & OIDC Guide

Keycloak is an open-source Identity and Access Management solution that provides Single Sign-On, OIDC, SAML 2.0, LDAP federation, and fine-grained authorization — all self-hosted with no per-MAU fees. This guide covers Docker quickstart, realm and client configuration, Active Directory integration, and production deployment patterns.

What is Keycloak and When to Use It?

Keycloak is backed by Red Hat (now part of IBM) and is the upstream project for Red Hat Single Sign-On (RH-SSO). It handles user authentication, token issuance, consent flows, and identity federation entirely within your infrastructure. Organizations choose Keycloak over cloud identity providers primarily for data sovereignty (GDPR, HIPAA, FedRAMP), on-premises Active Directory integration, or to avoid the cost scaling of per-MAU pricing at tens of thousands of users.

Keycloak is not the easiest solution to operate — it requires a database, clustering for HA, and regular upgrades. It's most appropriate for enterprise environments with a dedicated DevOps team or for regulated industries where cloud identity providers are not permitted.

Docker Quickstart

# Start Keycloak in development mode (NOT for production)
docker run -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:24.0.3 \
  start-dev

# Access admin console at http://localhost:8080
# Login with admin / admin

# Production-ready Docker with Postgres
docker run -p 8443:8443 \
  -e KC_DB=postgres \
  -e KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak \
  -e KC_DB_USERNAME=keycloak \
  -e KC_DB_PASSWORD=secret \
  -e KC_HOSTNAME=auth.yourcompany.com \
  -e KC_PROXY=edge \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=StrongPassword123! \
  quay.io/keycloak/keycloak:24.0.3 \
  start

Realm and Client Configuration

After login, create a new realm (avoid using the 'master' realm for applications — it's for Keycloak administration only). Within your realm, create clients for each application:

# Create realm and client via Keycloak Admin CLI
# (kcadm.sh is bundled in the Docker image)

# Authenticate
/opt/keycloak/bin/kcadm.sh config credentials \
  --server http://localhost:8080 \
  --realm master \
  --user admin --password admin

# Create realm
/opt/keycloak/bin/kcadm.sh create realms \
  -s realm=myapp \
  -s enabled=true

# Create OIDC client
/opt/keycloak/bin/kcadm.sh create clients -r myapp \
  -s clientId=myapp-frontend \
  -s publicClient=true \
  -s 'redirectUris=["https://app.yourcompany.com/*"]' \
  -s 'webOrigins=["https://app.yourcompany.com"]'

User Federation with LDAP / Active Directory

Navigate to User Federation > Add ldap provider. Key settings for Active Directory:

OIDC Flow Setup and Token Inspection

# OIDC Discovery endpoint (provides all config automatically)
curl https://auth.yourcompany.com/realms/myapp/.well-known/openid-configuration

# Token endpoint — exchange authorization code for tokens
curl -X POST https://auth.yourcompany.com/realms/myapp/protocol/openid-connect/token \
  -d grant_type=authorization_code \
  -d code=AUTH_CODE \
  -d redirect_uri=https://app.yourcompany.com/callback \
  -d client_id=myapp-frontend

# Introspect a token
curl -X POST https://auth.yourcompany.com/realms/myapp/protocol/openid-connect/token/introspect \
  -d token=ACCESS_TOKEN \
  -u myapp-backend:client_secret

Protecting a Node.js API

// npm install keycloak-connect express-session
const Keycloak = require('keycloak-connect');
const session = require('express-session');

const memoryStore = new session.MemoryStore();
app.use(session({
  secret: 'some secret',
  resave: false,
  saveUninitialized: true,
  store: memoryStore
}));

const keycloak = new Keycloak({ store: memoryStore }, {
  realm: 'myapp',
  'auth-server-url': 'https://auth.yourcompany.com',
  'ssl-required': 'external',
  resource: 'myapp-backend',
  credentials: { secret: 'your-client-secret' }
});

app.use(keycloak.middleware());

// Protect route — requires authentication
app.get('/api/protected', keycloak.protect(), (req, res) => {
  res.json({ message: 'Authenticated!', user: req.kauth.grant.access_token.content });
});

// Protect route — requires role
app.get('/api/admin', keycloak.protect('realm:admin'), (req, res) => {
  res.json({ message: 'Admin access granted' });
});

Keycloak vs Auth0 vs Authentik