Create an implementation roadmap for OIDC authentication with Authentik for Claude Web UI. Purpose: Guide phased implementation of OIDC authentication with clear milestones Input: Current codebase structure, Authentik configuration requirements Output: oidc-auth-plan.md with 4-5 implementation phases Project: Claude Web UI - Web interface for Claude Code CLI URL: https://agents.sneakercloud.de Stack: - Backend: Node.js/Express (server.js) with WebSocket - Frontend: React/Vite with JSX components - Auth Provider: Authentik (https://auth.sneakercloud.de) Current backend structure: - Single file: backend/server.js (~999 lines) - Express app with CORS, WebSocket server - No authentication currently implemented - REST endpoints: /api/hosts, /api/projects, /api/health, /api/browse, /api/upload, /api/history Current frontend structure: - src/App.jsx - Main application - src/contexts/SessionContext.jsx - Session state management - src/hooks/useClaudeSession.js - WebSocket connection hook - src/components/ - UI components (ChatPanel, Sidebar, Header, etc.) Authentication requirements: - OIDC Provider: Authentik - Auth Flow: Redirect Flow (Authorization Code) - Token Storage: httpOnly Cookies (XSS-safe) - Groups: agent-admin (full access), agent-users (standard access) - Session Duration: Configurable, with refresh token support Requirements to address: 1. Authentik OIDC Application setup (Provider + Application) 2. Backend OIDC middleware with session management 3. Frontend AuthContext with login/logout flow 4. Protected routes and API endpoints 5. Group-based access control (admin vs users) 6. httpOnly cookie-based token storage Constraints: - Must work with existing WebSocket architecture - Minimal changes to existing components - Single-file backend (server.js) - consider refactoring into modules - Production-ready security (no localStorage tokens) Success criteria: - Unauthenticated users see login page - Login redirects to Authentik, returns with session - WebSocket connections are authenticated - API endpoints check authentication - Admin users have additional capabilities - Sessions persist across browser refresh Save to: `.prompts/001-oidc-auth-plan/oidc-auth-plan.md` Structure the plan using this XML format: ```xml

{One paragraph overview of the OIDC implementation approach}

Create OIDC Provider and Application in Authentik Create OAuth2/OIDC Provider in Authentik Configure redirect URIs for agents.sneakercloud.de Create Application and bind to Provider Create groups: agent-admin, agent-users Configure group claims in OIDC scope Authentik OIDC app configured Client ID and Secret generated Groups created and mapped Admin access to Authentik Document the exact Authentik configuration steps. Save Client ID/Secret to .env (not committed). Test OIDC endpoints manually before proceeding. Implement OIDC authentication in backend Install dependencies: openid-client, cookie-parser, express-session Create auth module with OIDC client configuration Implement /api/auth/login - redirect to Authentik Implement /api/auth/callback - handle OIDC response Implement /api/auth/logout - clear session Implement /api/auth/me - return current user info Create auth middleware for protected routes Add session validation to WebSocket connections backend/auth.js module Session-based authentication with httpOnly cookies Protected API routes Phase 1 complete (Authentik configured) Use openid-client for OIDC implementation. Store session in memory initially (can add Redis later). Validate ID tokens and extract user info. Pass user context to WebSocket sessions. Implement React authentication context and UI Create AuthContext with user state management Create useAuth hook for components Create LoginPage component Implement protected route wrapper Add login/logout buttons to Header Show user info in UI Add loading state during auth check src/contexts/AuthContext.jsx src/hooks/useAuth.js src/components/LoginPage.jsx src/components/ProtectedRoute.jsx Phase 2 complete (backend auth working) Check /api/auth/me on app load to determine auth state. Redirect to login page if not authenticated. After login, redirect back to original URL. Handle auth errors gracefully. Implement group-based access control Extract groups from OIDC claims in backend Add isAdmin flag to user context Protect admin-only API routes Show admin UI elements conditionally Add user management UI for admins (future) Group-based route protection Admin-specific UI elements Phase 3 complete agent-admin: Full access, all hosts, all features agent-users: Limited hosts, standard features Check group membership on backend, pass to frontend. Test, document, and polish the implementation Test full auth flow end-to-end Test WebSocket reconnection after session refresh Handle edge cases (expired sessions, revoked tokens) Update BookStack documentation Add session timeout warnings Working OIDC authentication Updated documentation Phase 4 complete OIDC with Authentik is well-documented pattern. httpOnly cookies with redirect flow is industry standard. openid-client is mature library for Node.js. - Authentik admin access - DNS/SSL already configured (agents.sneakercloud.de) - Current app deployed and working - Session storage: In-memory vs Redis? - Token refresh strategy: Silent refresh vs re-login? - Should WebSocket auth use same session or separate token? - Authentik is accessible at auth.sneakercloud.de - User has admin access to create OIDC app - Current backend can be extended (single server.js file) - Frontend can add new components without major refactoring ``` Create `.prompts/001-oidc-auth-plan/SUMMARY.md` Structure: ```markdown # OIDC Auth Plan Summary **{Substantive one-liner describing the plan}** ## Version v1 ## Key Findings - {Phase 1 objective} - {Phase 2 objective} - {Phase 3 objective} - {Key architectural decision} ## Decisions Needed {Specific decisions requiring user input} ## Blockers {External impediments, or "None"} ## Next Step {Concrete forward action - likely "Execute Phase 1"} --- *Confidence: High* *Full output: oidc-auth-plan.md* ``` - Plan addresses all 5 requirements (Authentik, backend, frontend, routes, groups) - Phases are sequential and logically ordered - Each phase builds on previous deliverables - Tasks are specific and actionable - Metadata captures open questions and assumptions - SUMMARY.md created with phase overview - Ready for implementation prompts to consume