Files

T

Fusion 9b04760423 docs: sync oauth-traefik-integration specs to main specs

- Update auth-oauth spec: configurable endpoints via environment variables
- Update docker-infrastructure spec: add traefik deployment mode
- Add traefik-deployment spec: new capability for reverse proxy deployment

2026-05-17 23:28:43 +02:00

3.0 KiB

Raw Blame History

Authentication Specification

Purpose

Manage user authentication via Authentik OAuth with secure session handling.

Requirements

Requirement: OAuth2/OIDC Flow

The system SHALL support OAuth2/OIDC authentication via Authentik with fully configurable endpoints and SHALL validate Authentik-issued tokens via JWKS before creating local sessions.

GIVEN a user clicks the login button
WHEN the frontend redirects to Authentik authorization endpoint
THEN the redirect URI SHALL be constructed from environment-configured domains
AND the Authentik authorize URL SHALL be read from environment variables

Scenario: Token exchange and validation

GIVEN Authentik has redirected with authorization code
WHEN the callback endpoint receives the code
THEN it exchanges the code for provider tokens at the configured token URL
AND verifies token signature using the configured JWKS URL
AND validates the issuer and audience from environment configuration
AND upserts the local user account
AND mints internal access and refresh tokens

Requirement: Session Security

The system SHALL protect sessions using httpOnly cookies and SHALL apply secure cookie defaults by environment.

GIVEN successful authentication in production
WHEN cookies are set
THEN access_token cookie SHALL be httpOnly
AND access_token cookie SHALL have Secure flag
AND access_token cookie SHALL have SameSite=strict
AND refresh_token cookie SHALL have the same attributes

GIVEN successful authentication in localhost development
WHEN cookies are set
THEN access_token cookie SHALL be httpOnly
AND access_token cookie SHALL have Secure=false
AND access_token cookie SHALL have SameSite=lax
AND refresh_token cookie SHALL have the same attributes

Requirement: Token Refresh

The system SHALL support automatic token refresh with server-side refresh token storage, rotation, and revocation.

Scenario: Access token expiration

GIVEN a user has an expired access token
WHEN the user makes an authenticated request that can refresh
THEN the system validates the refresh token against non-expired, non-revoked DB state
AND rotates the refresh token
AND issues a new internal access token

Scenario: Refresh token reuse detection

GIVEN a refresh token has already been rotated or revoked
WHEN it is presented again to the refresh endpoint
THEN the system rejects the request with unauthorized status
AND invalidates the token chain for the session

Requirement: Session Termination

The system SHALL support explicit logout with refresh token invalidation.

Scenario: User logout

GIVEN an authenticated user
WHEN the user clicks logout
THEN all auth cookies are cleared
AND the refresh token is invalidated in server-side storage

Dependencies

Authentik OIDC provider configured
Database models: User

Quality Gates

pytest must pass
mypy . must pass
ruff check . must pass

3.0 KiB Raw Blame History