Local SSO Testing with Keycloak

This guide explains how to test OIDC and SAML authentication locally using Keycloak.

Prerequisites

• Docker installed and running

Quick Start

# 1. Seed SSO test data
make seed-sso

# 2. Start dev environment with SSO + Keycloak
make dev-sso

make dev-sso starts the database, Keycloak (via Docker Compose sso profile), and the backend with SSO environment variables — all in one command.

Test Credentials

Testing OIDC Flow

1. Go to http://localhost:5173/auth/login
2. Enter alice@oidc-test.local
3. Click “Continue”
4. You’ll be redirected to Keycloak
5. Log in with password123
6. You’ll be redirected back to the app, logged in

Testing SAML Flow

1. Go to http://localhost:5173/auth/login
2. Enter bob@saml-test.local
3. Click “Continue”
4. You’ll be redirected to Keycloak
5. Log in with password123
6. You’ll be redirected back to the app, logged in

Keycloak Admin Console

• URL: http://localhost:8180
• Username: admin
• Password: admin

Use this to: - View/edit test users - Check client configurations - Debug SSO issues

Troubleshooting

“OIDC SSO handler registered” not in logs

Ensure you started with make dev-sso (not make dev-up).

“SAML SSO handler registered” not in logs

Ensure SP_CERT and SP_KEY are set and the cert files exist:

ls docker/keycloak/sp-*.pem
cat docker/keycloak/sp-cert.pem | head -1  # Should show BEGIN CERTIFICATE

Keycloak not starting

Check Docker logs:

make keycloak-logs

“institution not found” error

Ensure SSO data is seeded:

make seed-sso

Redirect loop or callback errors

1. Check Keycloak is running: curl http://localhost:8180/health/ready
2. Check redirect URIs match in Keycloak admin console
3. Check SSO_ROOT_URL is http://localhost:8080

Makefile Commands