Setting up SSO with Keycloak

Setting up SSO with Keycloak (Docker)

A complete, copy-paste walkthrough for standing up Keycloak in Docker as an OpenID Connect identity provider and wiring it into FreeITSM. Keycloak is free, open-source, and the easiest way to evaluate FreeITSM's SSO / OIDC support — but the same FreeITSM steps apply to Entra, Okta, Google, etc.

This guide uses Keycloak's development mode (plain HTTP, throwaway settings). It's perfect for local evaluation but not for production — see Going to production at the end.

Prerequisites

• Docker installed and running (Docker Desktop on Windows/Mac).
• FreeITSM running and reachable in a browser (this guide assumes http://localhost/freeitsm-app/).
• Port 8080 free (Keycloak's default; FreeITSM stays on your web server's own port).

1. Run Keycloak in Docker

Create a folder for the stack (keep it outside your web root — it isn't part of FreeITSM), e.g. C:\Users\<you>\docker\keycloak\, and add a docker-compose.yml:

services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    container_name: keycloak
    command: start-dev          # dev mode: plain HTTP, no TLS certs needed
    environment:
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
    ports:
      - "8080:8080"
    volumes:
      - keycloak_data:/opt/keycloak/data   # persists realm/clients/users across restarts

volumes:
  keycloak_data:

Start it:

docker compose up -d        # first run pulls the image (~400 MB)
docker compose logs -f      # watch it boot (optional)

When it's up, open http://localhost:8080 → Administration Console and log in with admin / admin.

Useful commands later:

docker compose down         # stop (keeps your data)
docker compose down -v      # stop AND wipe the realm/users/clients

Tip — a proper admin: the admin/admin account is a temporary bootstrap account. For anything beyond a quick test, create a permanent admin: in the master realm → Users → add a user → set a password (toggle Temporary off) → Role mapping → assign the admin realm role.

2. Create a realm

A realm is an isolated space for your application's users and clients (keep them out of the master admin realm).

1. Top-left realm dropdown → Create realm
2. Realm name: freeitsm
3. Create

The dropdown should now show freeitsm — everything below happens inside this realm.

3. Create the OIDC client

The client represents FreeITSM inside Keycloak. Clients → Create client.

Step 1 – General settings

• Client type: OpenID Connect
• Client ID: freeitsm-app (this is the Client ID you'll enter in FreeITSM)
• Name: FreeITSM
• Next

Step 2 – Capability config

• Client authentication: On (makes it a confidential client → it gets a secret)
• Authorization: Off
• Authentication flow: tick Standard flow only
• Next

Step 3 – Login settings

• Root URL: http://localhost/freeitsm-app/
• Home URL: /
• Valid redirect URIs: http://localhost/freeitsm-app/api/auth/oidc_callback.php (this is the redirect URI shown on FreeITSM's System → Single Sign-On page — copy the exact value from there)
• Valid post logout redirect URIs: http://localhost/freeitsm-app/
• Web origins: http://localhost
• Save

Now open the client's Credentials tab and copy the Client secret — you'll paste it into FreeITSM in step 5.

4. Create a test user

Users → Add user:

• Username: alice
• Email: alice@example.com (needn't be real — no email is sent; it's used to match/identify the analyst)
• Email verified: On
• First / last name: anything
• Create

Then Credentials → Set password, enter a password, toggle Temporary off, Save.

5. Configure the provider in FreeITSM

In FreeITSM go to System → Single Sign-On:

1. In Global settings, turn Enable single sign-on on and Save.
2. Under Identity providers click Add and enter:
   • Display name: Sign in with Keycloak
   • Issuer URL: http://localhost:8080/realms/freeitsm → click Test (should report Discovery OK)
   • Client ID: freeitsm-app
   • Client secret: (paste the value from Keycloak's Credentials tab)
   • Scopes: leave as openid email profile
   • Enabled: on
   • Auto-create users (JIT): on (simplest for testing — auto-creates the analyst on first login; leave Default module access blank only if you're happy the user gets full access)
3. Save.

6. Test the login

1. Log out of FreeITSM (or use a private/incognito window) to reach the login page.
2. Either type alice@example.com and click Continue, or click the Sign in with Keycloak button.
3. You're redirected to Keycloak — sign in as alice / (the password you set).
4. Keycloak redirects back and FreeITSM logs you in. With JIT on, an analyst for Alice is created and linked automatically.

That's a full OIDC round-trip working end to end. 🎉

Troubleshooting

Symptom	Likely cause / fix
"Invalid parameter: redirect_uri" at Keycloak	The Valid redirect URIs in the client doesn't exactly match FreeITSM's callback. Copy the URI from System → Single Sign-On verbatim (scheme, host, path).
"Security check failed (state mismatch)"	Session/cookie was lost mid-flow, or you reused an old login tab. Start the sign-in again from the login page.
"ID token nonce/issuer/audience mismatch"	Issuer URL is wrong (must be http://localhost:8080/realms/freeitsm, no trailing slash needed) or the client ID doesn't match. Re-run Test.
"Token exchange failed: invalid_client"	Wrong/blank client secret, or Client authentication wasn't On. Re-copy the secret from Keycloak's Credentials tab and re-save the provider.
"Your email is not verified…"	Set Email verified: On for the user in Keycloak.
No "Sign in with Keycloak" button	Enable single sign-on is off, or the provider isn't Enabled. Hard-refresh the login page (Ctrl+F5).
Clock-skew / expiry errors	The token validator allows 60s of leeway; make sure the host clock and the container clock are roughly in sync.

Going to production

Development mode (start-dev, HTTP, the in-container database) is for evaluation only. For a real deployment:

• Run Keycloak in production mode (start) behind HTTPS with a valid certificate, and set KC_HOSTNAME.
• Use an external database (PostgreSQL) rather than the dev store.
• Replace the bootstrap admin/admin with a real admin account and a strong password.
• Use HTTPS URLs for the FreeITSM redirect URI, and configure FreeITSM behind TLS too.
• Consider Keycloak's own MFA, brute-force detection and session policies — with SSO, the IdP owns authentication and MFA.

Related

• Single Sign-On (SSO / OIDC) — the feature reference (configuration, account mapping, break-glass, other providers)
• Security — wider authentication and encryption details