headquarter/openspec/changes/archive/2026-05-18-simplify-authentik-auth/proposal.md

Simplify Authentik Auth Flow

Problem

The current authentication implementation is overly complex for our needs:

• Multiple layers: OIDC token exchange, refresh token rotation, complex cookie management
• Difficult to debug: Many moving parts make deployment issues hard to diagnose
• Over-engineered: We don't need the full OIDC flow complexity for our use case
• Maintenance burden: The sophisticated approach requires deep understanding of OAuth2/OIDC internals

Solution

Replace the current complex auth flow with a simplified approach:

1. Authentik OAuth: Keep OAuth2 authentication via Authentik
2. Session-based: Use simple session cookies instead of JWT + refresh tokens
3. Authentik as source of truth: User profiles synced from Authentik on login
4. Simpler implementation: Reduce auth-related code by ~70%

Benefits

• Easier to deploy: Fewer configuration variables and moving parts
• Easier to debug: Clear flow: Login → Authentik → Session Cookie
• Less code: Remove JWT service, refresh token store, complex OIDC logic
• Future-proof: Still supports teams/groups via Authentik's user info endpoint
• Better UX: No token refresh issues, simpler logout

Scope

What stays:

• OAuth2 authentication via Authentik
• User model in database (synced from Authentik)
• Protected routes requiring authentication
• Frontend auth state management

What goes:

• JWT access tokens
• Refresh token rotation
• Complex OIDC token verification
• Multiple cookie types (access_token, refresh_token)
• Token expiry/refresh logic
• JWKS fetching and validation

What's new:

• Simple session cookie (httpOnly, secure, SameSite)
• Authentik user info endpoint integration
• Simplified auth middleware
• Cleaner logout (just delete session)