docs: added vite-press docs (#4)

Co-authored-by: Sharang Parnerkar <parnerkarsharang@gmail.com>
Reviewed-on: #4

docs/deployment/keycloak.md

@@ -0,0 +1,104 @@
+# 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
+
+```bash
+# 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.