Sharang Parnerkar
7e12d1433a
Co-authored-by: Sharang Parnerkar <parnerkarsharang@gmail.com> Reviewed-on: #4
105 lines
3.3 KiB
Markdown
105 lines
3.3 KiB
Markdown
# 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.
|