Architecture: Auth (ISS)
Authentication and authorization architecture for the Intelligence Staffing Systems app.
Diagram
Components
| Component |
Role |
Location |
| Keycloak |
Identity provider, OIDC, self-registration, email verification |
Self-hosted, ISS realm |
| OmniAuth |
OIDC client, token exchange |
<code>config/initializers/omniauth.rb</code> |
| SessionsController |
Callback handler, session lifecycle |
<code>app/controllers/sessions_controller.rb</code> |
| ApplicationController |
<code>authenticate_user!</code>, <code>current_user</code>, role helpers |
<code>app/controllers/application_controller.rb</code> |
| SessionHelper |
Session management utilities |
<code>app/helpers/session_helper.rb</code> |
Key Decisions
- Keycloak over Devise: Multi-tenant SSO across all ISS client apps. One login, all dashboards.
- Realm roles over client roles: Simpler mapping — admin/client/lead are realm-level, not per-client.
- CSS-only theme: Minimal Keycloak customization.
register.ftl is the first FreeMarker override (planned for self-registration).
- Session cookie over JWT: Rails handles session state server-side. Keycloak token is consumed once at callback, not passed to the client.
- Keycloak SMTP independent of Rails Postmark: Email verification is realm-level config, not tied to the Rails mailer integration (#16).
Roles
| Role |
Source |
Access |
| admin |
Keycloak realm role |
All tabs including CRM, all threads, user management |
| client |
Keycloak realm role (promoted from lead) |
Catalog, Projects, Communications, Account |
| lead |
Default on registration |
Catalog, Communications, Account |
arch-frontend-iss — frontend architecture (tab bar, Turbo, Stimulus)docs/security.md — security posture and attack surfacedocs/keycloak-setup.md — realm config details