compliance-scanner-agent/docs/deployment/keycloak.md

Keycloak Authentication

Compliance Scanner supports Keycloak for SSO authentication. When configured, all dashboard access requires signing in through Keycloak, and all API endpoints are protected.

How It Works

Dashboard (OAuth2/OIDC)

The dashboard implements a standard OAuth2 Authorization Code flow with PKCE:

1. User visits the dashboard
2. If not authenticated, a login page shows with a "Sign in with Keycloak" button
3. User is redirected to Keycloak's login page
4. After authentication, Keycloak redirects back with an authorization code
5. The dashboard exchanges the code for tokens and creates a session
6. All subsequent /api/ server function calls require a valid session

Agent API (JWT)

The agent API validates JWT Bearer tokens from Keycloak:

1. Dashboard (or other clients) include the access token in requests: Authorization: Bearer <token>
2. The agent fetches Keycloak's JWKS (JSON Web Key Set) to validate the token signature
3. Token expiry and claims are verified
4. The health endpoint (/api/v1/health) is always public

If KEYCLOAK_URL and KEYCLOAK_REALM are not set on the agent, JWT validation is disabled and all endpoints are open.

Keycloak Setup

1. Create a Realm

In the Keycloak admin console:

1. Create a new realm (e.g. compliance)
2. Note the realm name — you'll need it for KEYCLOAK_REALM

2. Create a Client

1. Go to Clients > Create client
2. Set:
   • Client ID: compliance-dashboard
   • Client type: OpenID Connect
   • Client authentication: Off (public client)
3. Under Settings:
   • Valid redirect URIs: http://localhost:8080/auth/callback (adjust for your domain)
   • Valid post logout redirect URIs: http://localhost:8080
   • Web origins: http://localhost:8080

3. Create Users

1. Go to Users > Create user
2. Set username, email, first name, last name
3. Under Credentials, set a password

Environment Variables

# Keycloak server URL (no trailing slash)
KEYCLOAK_URL=http://localhost:8080

# Realm name
KEYCLOAK_REALM=compliance

# Client ID (must match the client created above)
KEYCLOAK_CLIENT_ID=compliance-dashboard

# OAuth callback URL (must match valid redirect URI in Keycloak)
REDIRECT_URI=http://localhost:8080/auth/callback

# Application root URL (used for post-logout redirect)
APP_URL=http://localhost:8080

Dashboard Features

When authenticated, the dashboard shows:

• User avatar in the sidebar (from Keycloak profile picture, or initials)
• User name from Keycloak profile
• Logout link that clears the session and redirects through Keycloak's logout flow

Session Configuration

Sessions use signed cookies with these defaults:

• Expiry: 24 hours of inactivity
• SameSite: Lax (required for Keycloak redirect flow)
• Secure: Disabled by default (enable behind HTTPS)
• Storage: In-memory (resets on server restart)

::: tip For production, consider persisting sessions to Redis or a database so they survive server restarts. :::

Running Without Keycloak

If no Keycloak variables are set:

• The dashboard serves without authentication (all pages accessible)
• The agent API accepts all requests without token validation
• A warning is logged: Keycloak not configured - API endpoints are unprotected

This is suitable for local development and testing.