Keycloak (Docker) Setup Guide

This guide stands up Keycloak in Docker as an OpenID Connect identity provider and wires it into FreeITSM. Keycloak is free and open-source, and it's the quickest way to try FreeITSM's single sign-on support – but the FreeITSM steps are identical for Entra, Okta, Google and others.

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

---

Step 1: Run Keycloak in Docker

Create a folder for the stack 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

volumes:
  keycloak_data:

Start it (the first run pulls the image, ~400 MB):

docker compose up -d        # start
docker compose logs -f      # watch it boot (optional)
docker compose down         # stop (keeps your data)
docker compose down -v      # stop AND wipe realm/users/clients

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

---

Step 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. Click Create

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

---

Step 3: Create the OIDC Client

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

General settings

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

Capability config

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

Login settings

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

Open the client's Credentials tab and copy the Client secret – you'll paste it into FreeITSM in Step 5.

---

Step 4: Create a Test User

1. Users → Add user
2. Username: alice
3. Email: alice@example.com  (needn't be real – no email is sent; it's used to identify the analyst)
4. Email verified: On, add a name, then Create
5. On the Credentials tab → Set password, enter a password, toggle Temporary off, Save

---

Step 5: Configure the Provider in FreeITSM

In FreeITSM, go to System → Single Sign-On (see the SSO Setup Guide for full detail):

1. 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: the value from Keycloak's Credentials tab
   • Auto-create users (JIT): on – simplest for testing
3. Click Save

---

Step 6: Test the Login

1. Log out of FreeITSM (or use a private/incognito window) to reach the login page
2. Type alice@example.com and click Continue, or click the Sign in with Keycloak button
3. Sign in at Keycloak as alice with the password you set
4. Keycloak redirects back and FreeITSM logs you in – with JIT on, Alice's analyst account is created and linked automatically

---

Troubleshooting

• "Invalid parameter: redirect_uri" at Keycloak – the client's Valid redirect URIs doesn't exactly match FreeITSM's callback. Copy it verbatim from the Single Sign-On page.
• "Security check failed (state mismatch)" – the session was lost or an old login tab was reused. Start the sign-in again from the login page.
• "Token exchange failed: invalid_client" – wrong or blank client secret, or Client authentication wasn't On. Re-copy the secret and re-save the provider.
• "ID token issuer/audience mismatch" – the issuer URL or client ID is wrong. Re-run Test on the issuer URL.
• "Your email is not verified" – set Email verified: On for the user in Keycloak.
• No "Sign in with Keycloak" button – SSO isn't enabled, or the provider isn't enabled. Hard-refresh the login page (Ctrl+F5).

---

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 and a strong password
• Use HTTPS URLs for the FreeITSM redirect URI, and run FreeITSM behind TLS too
• Lean on Keycloak's own MFA, brute-force detection and session policies – with SSO the identity provider owns authentication

← Back to SSO Setup