Central SSO & Keycloak Authentication
I delegate user authentication and identity federation to Keycloak, a battle-tested open-source Identity and Access Management (IAM) system. A single Keycloak instance serves the entire cluster, but it hosts two separate realms with distinct security boundaries.
Two Realms, One Identity Provider
Keycloak manages two realms that serve fundamentally different audiences:
| Realm | Purpose | Consumers |
|---|---|---|
borrowd | End-user authentication for the Borrowd platform | Borrowd web app, custom Keycloak theme (login, account, email templates) |
dslan | OIDC for self-hosted infrastructure services | Grafana, Kaneo, Penpot |
The borrowd realm is the user-facing identity layer — it handles registration, login, MFA, and session management for the Borrowd application. I built a fully custom Keycloak theme for this realm so that login, account management, and transactional emails match the application's brand.
The dslan realm covers everything else. Services like Grafana (observability dashboards), Kaneo (project management), and Penpot (design tool) each authenticate via OIDC against this realm. This separation keeps the Borrowd user pool isolated from my infrastructure tooling, so internal admin users and public application users never share a client configuration, token audience, or session scope.
Why Keycloak?
- Offloaded Security Risk: Writing custom authentication from scratch introduces vulnerabilities. Keycloak handles user registration, password hashing, Multi-Factor Authentication (MFA), and session revocation out of the box.
- Stateless JWT Verification: The Ktor backend verifies JWT tokens statelessly using public-key cryptography (JWKS). API calls do not require per-request database lookups or HTTP calls back to Keycloak, ensuring high throughput.
- Unified SSO Across Infrastructure: Both Keycloak realms provide SSO authentication — the
borrowdrealm for the application itself, and thedslanrealm for Grafana, Kaneo, Penpot, and administrative dashboards protected by OAuth2 Proxy.
Because my API server verifies JWT tokens cryptographically using a cached public key (JWKS), the authentication layer is virtually instantaneous. This eliminates network roundtrips to Keycloak and avoids database hits for session validation on every API request.