Local SSO Testing with Keycloak

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

Prerequisites

• Docker installed and running
• Local PostgreSQL database (make db)
• Backend running with SSO environment variables

Quick Start

# 1. Start PostgreSQL (if not already running)
make db

# 2. Start Keycloak
make keycloak

# 3. Set up SSO environment variables
cp .envrc.example .envrc
source .envrc

# 4. Seed SSO test data
make seed-sso

# 5. Start backend and frontend
make dev-backend   # Terminal 1
make dev-frontend  # Terminal 2

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 environment variables are set:

source .envrc
make dev-backend

“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