TL;DR — Quick Summary

Deploy Keycloak for centralized Single Sign-On. Configure realms, OIDC clients, user federation with LDAP, and troubleshoot login and token errors.

Why Keycloak?

Managing user authentication across multiple applications is complex. Keycloak provides a centralized identity layer:

  • SSO: Users log in once, gain access to all registered apps.
  • Protocol support: OIDC (OpenID Connect), OAuth 2.0, SAML 2.0.
  • User federation: Connect to existing LDAP or Active Directory.
  • Built-in MFA: TOTP, WebAuthn, and email verification out of the box.
  • Social login: Google, GitHub, Facebook, Microsoft with zero code.

Prerequisites

  • Docker or a Java 17+ server.
  • At least 2 GB RAM for Keycloak.
  • A web application to integrate (any framework/language).

Step 1: Deploy Keycloak

Docker (Development Mode)

docker run -d --name keycloak -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest start-dev

Access the Admin Console at http://localhost:8080.

Production Mode

For production, use a PostgreSQL database backend and reverse proxy with TLS:

docker run -d --name keycloak -p 8080:8080 \
  -e KC_DB=postgres \
  -e KC_DB_URL=jdbc:postgresql://db-host:5432/keycloak \
  -e KC_DB_USERNAME=keycloak \
  -e KC_DB_PASSWORD=secret \
  -e KC_HOSTNAME=auth.yourdomain.com \
  -e KC_PROXY=edge \
  quay.io/keycloak/keycloak:latest start

Step 2: Create a Realm and Client

Create a Realm

  1. Log into the Admin Console → click the dropdown (top-left, “master”) → Create Realm.
  2. Name it (e.g., my-company). A realm isolates users, roles, and clients.

Register an OIDC Client

  1. Go to Clients → Create Client.
  2. Client ID: my-web-app
  3. Root URL: http://localhost:3000
  4. Valid Redirect URIs: http://localhost:3000/callback
  5. Access Type: confidential (for server-to-server) or public (for SPAs).

Copy the Client Secret from the Credentials tab — your app will need it to exchange authorization codes for tokens.

Step 3: Integrate Your Application

OIDC Flow (Authorization Code)

Your application redirects the user to:

http://keycloak:8080/realms/my-company/protocol/openid-connect/auth
  ?client_id=my-web-app
  &redirect_uri=http://localhost:3000/callback
  &response_type=code
  &scope=openid profile email

After login, Keycloak redirects back with a code. Your backend exchanges the code for tokens:

curl -X POST http://keycloak:8080/realms/my-company/protocol/openid-connect/token \
  -d "grant_type=authorization_code" \
  -d "code=THE_AUTH_CODE" \
  -d "client_id=my-web-app" \
  -d "client_secret=YOUR_SECRET" \
  -d "redirect_uri=http://localhost:3000/callback"

Step 4: User Federation (LDAP/AD)

  1. Go to User Federation → Add Provider → LDAP.
  2. Connection URL: ldap://ad-server:389
  3. Bind DN: cn=admin,dc=company,dc=com
  4. Users DN: ou=Users,dc=company,dc=com
  5. Click Test Connection and Test Authentication.
  6. Click Sync All Users to import from AD.

Troubleshooting

Problem Solution
“Invalid redirect_uri” Add the exact URI (with protocol/port/path) in Client → Valid Redirect URIs
Token expired immediately Check Access Token Lifespan in Realm Settings → Tokens (default 5 min may be too short)
LDAP users can’t login Verify Bind DN credentials, user search base, and test connection in User Federation
“Client not found” error Ensure client ID matches exactly (case-sensitive) and is in the correct realm
CORS errors from SPA Add your app’s origin to Client → Web Origins (e.g., http://localhost:3000)

Summary

  • Use Realms to isolate tenants and Clients to register applications.
  • Use confidential access type for server-side apps, public for SPAs.
  • Connect to LDAP/AD via User Federation for enterprise directories.
  • Always set exact Valid Redirect URIs to avoid authentication errors.