Skip to main content

Keycloak SSO Setup

OpenCLM uses Keycloak for authentication. Keycloak provides:

  • Single Sign-On (SSO) with SAML 2.0 and OpenID Connect
  • LDAP and Active Directory federation
  • Multi-factor authentication (TOTP, WebAuthn)
  • Social login (Google, Microsoft, GitHub, etc.)

Step 1 — Start Keycloak​

Keycloak is included in the Docker Compose stack and starts automatically. Access the admin console at:

http://localhost:8080/admin

Log in with KC_ADMIN_USER / KC_ADMIN_PASSWORD from your .env.

Step 2 — Create the OpenCLM Realm​

  1. In the Keycloak admin console, click Create Realm.
  2. Set Realm Name to openclm (or your preferred name — update .env accordingly).
  3. Enable the realm and click Create.

Step 3 — Create the OpenCLM Client​

  1. In the openclm realm, go to Clients → Create client.
  2. Set:
    • Client type: OpenID Connect
    • Client ID: openclm-app
  3. Click Next.
  4. Enable Standard flow and Direct access grants.
  5. Set Valid redirect URIs: https://openclm.yourdomain.com/*
  6. Set Web origins: https://openclm.yourdomain.com
  7. Click Save.
  8. In the Credentials tab, copy the Client Secret.

Step 4 — Update .env​

KEYCLOAK_URL=https://openclm.yourdomain.com/auth
KEYCLOAK_REALM=openclm
KEYCLOAK_CLIENT_ID=openclm-app
KEYCLOAK_CLIENT_SECRET=<the-client-secret-you-copied>

Step 5 — Restart the API​

docker compose restart api

Connecting LDAP / Active Directory​

  1. In Keycloak admin → openclm realm → User Federation → Add LDAP provider.
  2. Configure:
    • Edit mode: READ_ONLY (or WRITABLE if you want Keycloak to write back to AD)
    • Connection URL: ldap://your-ad-server:389
    • Bind DN: cn=keycloak-service,ou=service-accounts,dc=yourcompany,dc=com
    • Bind Credential: service account password
    • Users DN: ou=users,dc=yourcompany,dc=com
  3. Click Test Connection and Test Authentication.
  4. Click Save then Synchronise all users.

LDAP users can now log into OpenCLM using their company credentials.

Enabling MFA​

  1. In Keycloak admin → openclm realm → Authentication → Flows.
  2. Select the Browser flow.
  3. Set OTP Form to Required.
  4. Click Save.

Users will be prompted to set up a TOTP app (Google Authenticator, Authy, etc.) on next login.

Social Login (Google, Microsoft)​

  1. In Keycloak admin → openclm realm → Identity Providers → Add provider.
  2. Select Google (or Microsoft, GitHub, etc.).
  3. Enter the OAuth Client ID and Secret from your Google Cloud Console.
  4. Click Save.

Users can now sign in with "Continue with Google" on the OpenCLM login page.

Keycloak in Production​

For production Keycloak deployments:

  • Use a dedicated PostgreSQL database for Keycloak (separate from the OpenCLM database).
  • Enable cluster mode for high availability.
  • Configure a TLS-terminating reverse proxy in front of Keycloak.
  • Back up the Keycloak database regularly.

See the Keycloak production guide for comprehensive production hardening.