Fusion
9b04760423
- 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
79 lines
3.0 KiB
Markdown
79 lines
3.0 KiB
Markdown
# 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.
|
|
|
|
#### Scenario: User login
|
|
- 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.
|
|
|
|
#### Scenario: Cookie attributes in production
|
|
- 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
|
|
|
|
#### Scenario: Cookie attributes in localhost development
|
|
- 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
|