Docs/SSO/Keycloak

SSO with Keycloak

Useful for dev environments, air-gapped deployments, or when you want a self-hosted IdP. Setup is faster than commercial IdPs because you control everything.

1. Run Keycloak (skip if you already have one)

Quickest path with Docker or Podman:

podman run -d --name keycloak -p 8081:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:26.0 start-dev

Wait ~15 seconds, then sign in to http://localhost:8081 with admin / admin. Don't run this in production with default credentials.

2. Create a realm

  1. Click the realm dropdown (top left) → Create realm.
  2. Realm name: your-company (or any name — this becomes part of your issuer URL).
  3. Click Create.

3. Create an OIDC client

  1. Sidebar → Clients → Create client.
  2. Client type: OpenID Connect. Client ID: repowarden. Click Next.
  3. Capability config:
    • Client authentication: ON
    • Authorization: OFF
    • Auth flow: ✅ Standard flow (auth code)
    Click Next.
  4. Login settings:
    • Valid redirect URIs: get this from Team settings → SSO after creating the connection in RepoWarden. Format: https://api.repowarden.dev/api/auth/sso/callback/<providerId>
    • Web origins: + (allows redirect URIs' origins)
  5. Click Save.
  6. Switch to the Credentials tab and copy the Client Secret.

4. Create a test user

  1. Sidebar → Users → Create new user.
  2. Username + email (e.g. [email protected]). Email verified: ON. Enabled: ON.
  3. Save.
  4. On the user's Credentials tab → Set password. Set "Temporary" to OFF.

5. Note your issuer URL

Keycloak's issuer follows the pattern:

https://<keycloak-host>/realms/<realm-name>

Verify the discovery document loads:

curl <issuer>/.well-known/openid-configuration

6. Register the connection in RepoWarden

  1. Go to Team settings → SSO.
  2. Click Add SSO connection. Identity provider: Keycloak.
  3. Display name: e.g. "Acme Keycloak". Issuer URL: from step 5. Email domain: e.g. your-company.com.
  4. Client ID: repowarden. Client secret: from step 3.
  5. Click Test discovery → should show ✓.
  6. Click Save connection.

7. Update the Keycloak redirect URI

Copy the Provider ID shown on the connection card in RepoWarden, then go back to Keycloak's client settings and replace the placeholder redirect URI with the exact URL.

Production checklist