Files

T

Fusion 83f94b1f09 docs: comprehensive documentation overhaul

Add complete documentation structure:
- Frontend architecture documentation
- Database schema documentation
- Deployment guides (Docker, Traefik, Authentik, Environment)
- Development guides (Setup, Testing, Contributing, Quality Gates)
- Deployment architecture documentation
- Updated docs README with complete navigation

All new features and APIs are now documented.
Quality gates: docs only, no code changes

2026-05-19 14:18:20 +02:00

2.7 KiB

Raw Blame History

Authentication

Overview

Headquarter uses OAuth2 authentication via Authentik. Users log in through their Authentik identity provider and receive a session cookie for authenticated access.

How to Use

Logging In

Navigate to the application
Click the "Login" button in the header
You will be redirected to Authentik
Enter your Authentik credentials
You will be redirected back to Headquarter, now logged in

User Profile

After logging in, you can view your profile:

Click your name in the header
Select "Profile" from the dropdown
View and edit:
- Display name
- Email
- Avatar (upload or change)

Logging Out

Click your name in the header
Select "Logout"
Your session will be cleared
You will be redirected to the login page

Authentication Flow

User → Click Login → Authentik Login → OAuth2 Callback → Session Cookie → Authenticated

Technical Details

Session Management:

Uses signed session cookies
Cookie is HttpOnly and Secure (in production)
Session expires after configurable TTL (default: 24 hours)

OAuth2 Flow:

User clicks login
Backend redirects to Authentik authorize URL
User authenticates with Authentik
Authentik redirects back with authorization code
Backend exchanges code for access token
Backend fetches user info from Authentik
Backend creates/updates local user record
Backend sets session cookie
User is authenticated

API Reference

Endpoints

GET /auth/login - Initiate login (redirects to Authentik)
GET /auth/callback - OAuth2 callback
GET /auth/me - Get current user
POST /auth/logout - Logout (clears session)

See Auth API for detailed endpoint documentation.

Configuration

Variable	Description	Default
`AUTHENTIK_DOMAIN`	Authentik server domain	-
`AUTHENTIK_CLIENT_ID`	OAuth client ID	-
`AUTHENTIK_CLIENT_SECRET`	OAuth client secret	-
`AUTHENTIK_APPLICATION_SLUG`	Application slug for URLs	`headquarter-web`
`SESSION_SECRET`	Session cookie signing secret	`change-me`
`SESSION_TTL_HOURS`	Session duration	`24`

Troubleshooting

Issue: After logging in, you're redirected back to login Solution: Check that cookie domain matches your domain configuration

"Invalid State" Error

Issue: Error about invalid state parameter Solution: Clear cookies and try again. If persistent, check Authentik configuration.

Session Expired

Issue: "Session expired" message Solution: Log in again. Session duration is configurable via SESSION_TTL_HOURS.

User Settings - Configure user preferences

2.7 KiB Raw Blame History