Files

Jean-Luc Makiola 82eb9e7286 docs(15-02): complete OIDC auth integration plan

- Add 15-02-SUMMARY.md with execution results
- Update STATE.md with position, decisions, session info
- Update ROADMAP.md with plan progress
- Mark AUTH-01, AUTH-02, AUTH-03 requirements complete

2026-04-04 20:48:04 +02:00

4.4 KiB

Raw Permalink Blame History

phase: 15-external-authentication plan: 02 subsystem: auth tags: [oidc, hono, logto, @hono/oidc-auth, jose, mcp-oauth] # Dependency graph requires: - phase: 15-external-authentication (plan 01) provides: Docker Compose with Logto service, env vars, schema without users/sessions tables provides: - Three-way auth middleware (API key, MCP Bearer, OIDC session) - OIDC login/callback/logout routes at root level - Auth service stripped to API key CRUD only - MCP OAuth authorize using OIDC session instead of password affects: [15-external-authentication plan 03, client-side login page, e2e tests] # Tech tracking tech-stack: added: ["@hono/oidc-auth@1.8.1", "jose@6.2.2"] patterns: [three-way-auth-middleware, oidc-session-validation, consent-form-pattern] key-files: created: [] modified: - src/server/middleware/auth.ts - src/server/services/auth.service.ts - src/server/routes/auth.ts - src/server/routes/oauth.ts - src/server/mcp/index.ts - src/server/index.ts - package.json key-decisions: - "OIDC routes (/login, /callback, /logout) placed at root level in index.ts, not under /api/auth" - "MCP OAuth authorize uses consent-only form (no credentials) backed by OIDC session" - "Three-way auth order: API key first, Bearer token second, OIDC session third" patterns-established: - "Three-way auth: requireAuth checks API key -> MCP Bearer -> OIDC session in order" - "OIDC routes at root level, API routes under /api/auth" - "Consent form pattern: MCP OAuth shows authorize button only (no credential fields)" requirements-completed: [AUTH-01, AUTH-02, AUTH-03] # Metrics duration: 4min completed: 2026-04-04

Phase 15 Plan 02: OIDC Auth Integration Summary

Three-way auth middleware with @hono/oidc-auth for browser sessions, API keys for programmatic access, and MCP OAuth consent flow

Performance

Duration: 4 min
Started: 2026-04-04T18:42:20Z
Completed: 2026-04-04T18:46:35Z
Tasks: 3
Files modified: 8

Accomplishments

Replaced custom cookie-session auth with OIDC via @hono/oidc-auth in requireAuth middleware
Stripped auth service to API key functions only (removed all user/session management)
Added /login, /callback, /logout OIDC routes at root level for browser auth flow
Updated MCP OAuth to use OIDC session for authorization consent instead of password verification
Removed getUserCount bypass from MCP auth middleware

Task Commits

Each task was committed atomically:

Task 1: Install OIDC dependencies and rewrite auth middleware + service - 259dc2b (feat)
Task 2: Rewrite auth routes for OIDC login/callback/logout + API key CRUD - 1b6a65b (feat)
Task 3: Update MCP OAuth authorize and MCP auth middleware for OIDC - c0e6db5 (feat)

Files Created/Modified

package.json - Added @hono/oidc-auth and jose dependencies
src/server/middleware/auth.ts - Three-way auth: API key, MCP Bearer, OIDC session
src/server/services/auth.service.ts - API key CRUD only (user/session functions removed)
src/server/routes/auth.ts - GET /me with OIDC claims, API key CRUD routes
src/server/routes/oauth.ts - Consent form replaces login form, getAuth replaces verifyPassword
src/server/mcp/index.ts - Removed getUserCount import and bypass logic
src/server/index.ts - Added root-level /login, /callback, /logout OIDC routes

Decisions Made

Placed OIDC browser auth routes (/login, /callback, /logout) at root level in index.ts rather than under /api/auth, keeping API key management at /api/auth/keys
Auth check order in middleware: API key first (fast path for programmatic), Bearer token second (MCP), OIDC session third (browser)
MCP OAuth authorize shows consent-only form when user has OIDC session, redirects to /login otherwise

Deviations from Plan

None - plan executed exactly as written.

Known Stubs

None - all data paths are wired to real implementations.

Issues Encountered

None.

User Setup Required

None - OIDC provider (Logto) configuration was handled in plan 15-01.

Next Phase Readiness

Server-side OIDC integration complete
Client-side login page needs updating (plan 15-03) to redirect to /login instead of showing credential form
E2E tests will need API key auth strategy (bypassing Logto)

Self-Check: PASSED

All 6 modified files verified on disk. All 3 task commits verified in git log.

Phase: 15-external-authentication Completed: 2026-04-04

4.4 KiB Raw Permalink Blame History