Phase 3: Keycloak OIDC authentication

forgejo_admin commented

2026-05-09 02:46:43 +00:00

Contributor

Type

Feature

Lineage

Decomposed from #1 — Phase 3 of 4. Depends on #2 (scaffold).

Repo

forgejo_admin/pal-enterprises

User Story

As a user with a Keycloak account, I want to log in via SSO so that I'm authenticated across all pal-e platform tools.

Context

Integrate Keycloak OIDC using the omniauth-openid-connect gem. Register a new client pal-enterprises in the pal-e Keycloak realm (follow sop-keycloak-client-creation). Handle login, callback, and logout flows. Store minimal session data (sub, name, email) — no local user table.

This is the SSO gateway: once authenticated here, the user's Keycloak session applies across all pal-e realm apps.

File Targets

Files to create/modify:

Gemfile — add omniauth, omniauth-openid-connect, omniauth-rails_csrf_protection
config/initializers/omniauth.rb — Keycloak provider config
app/controllers/sessions_controller.rb — create (callback), destroy (logout)
config/routes.rb — add /auth/keycloak/callback, /logout

Files to modify:

app/views/pages/home.html.erb — wire "Sign In" button to /auth/keycloak
app/views/layouts/application.html.erb — show user name + logout when authenticated
k8s/dev.yaml — add KEYCLOAK_* env vars to secret

Acceptance Criteria

Keycloak client pal-enterprises registered in pal-e realm
"Sign In" redirects to Keycloak login page
Successful login redirects to /dashboard (or / until Phase 4)
Session stores Keycloak sub, display name, and email
"Sign Out" destroys local session and redirects to landing page
Callback URL: https://pal-enterprises.tail5b443a.ts.net/auth/keycloak/callback

Test Expectations

Unit test: SessionsController#create sets session from auth hash
Unit test: SessionsController#destroy clears session
Run command: bin/rails test

Constraints

Keycloak realm: pal-e at keycloak.tail5b443a.ts.net
Follow sop-keycloak-client-creation for client registration
No local user model — session-only auth
CSRF protection via omniauth-rails_csrf_protection

Checklist

Keycloak client registered
PR opened
Tests pass
Login flow works end-to-end on cluster
No unrelated changes

pal-enterprises — project
sop-keycloak-client-creation — SOP for client registration

### Type Feature ### Lineage Decomposed from #1 — Phase 3 of 4. Depends on #2 (scaffold). ### Repo `forgejo_admin/pal-enterprises` ### User Story As a user with a Keycloak account, I want to log in via SSO so that I'm authenticated across all pal-e platform tools. ### Context Integrate Keycloak OIDC using the `omniauth-openid-connect` gem. Register a new client `pal-enterprises` in the `pal-e` Keycloak realm (follow `sop-keycloak-client-creation`). Handle login, callback, and logout flows. Store minimal session data (sub, name, email) — no local user table. This is the SSO gateway: once authenticated here, the user's Keycloak session applies across all pal-e realm apps. ### File Targets Files to create/modify: - `Gemfile` — add `omniauth`, `omniauth-openid-connect`, `omniauth-rails_csrf_protection` - `config/initializers/omniauth.rb` — Keycloak provider config - `app/controllers/sessions_controller.rb` — create (callback), destroy (logout) - `config/routes.rb` — add `/auth/keycloak/callback`, `/logout` Files to modify: - `app/views/pages/home.html.erb` — wire "Sign In" button to `/auth/keycloak` - `app/views/layouts/application.html.erb` — show user name + logout when authenticated - `k8s/dev.yaml` — add KEYCLOAK_* env vars to secret ### Acceptance Criteria - [ ] Keycloak client `pal-enterprises` registered in `pal-e` realm - [ ] "Sign In" redirects to Keycloak login page - [ ] Successful login redirects to `/dashboard` (or `/` until Phase 4) - [ ] Session stores Keycloak sub, display name, and email - [ ] "Sign Out" destroys local session and redirects to landing page - [ ] Callback URL: `https://pal-enterprises.tail5b443a.ts.net/auth/keycloak/callback` ### Test Expectations - [ ] Unit test: SessionsController#create sets session from auth hash - [ ] Unit test: SessionsController#destroy clears session - Run command: `bin/rails test` ### Constraints - Keycloak realm: `pal-e` at `keycloak.tail5b443a.ts.net` - Follow `sop-keycloak-client-creation` for client registration - No local user model — session-only auth - CSRF protection via `omniauth-rails_csrf_protection` ### Checklist - [ ] Keycloak client registered - [ ] PR opened - [ ] Tests pass - [ ] Login flow works end-to-end on cluster - [ ] No unrelated changes ### Related - `pal-enterprises` — project - `sop-keycloak-client-creation` — SOP for client registration