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

ProblemSolution
”Invalid redirect_uri”Add the exact URI (with protocol/port/path) in Client → Valid Redirect URIs
Token expired immediatelyCheck Access Token Lifespan in Realm Settings → Tokens (default 5 min may be too short)
LDAP users can’t loginVerify Bind DN credentials, user search base, and test connection in User Federation
”Client not found” errorEnsure client ID matches exactly (case-sensitive) and is in the correct realm
CORS errors from SPAAdd 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.