Skip to main content

ADR-005: OIDC Authentication Architecture

Status

Accepted

Context

Tasteful applications need secure authentication that supports enterprise identity providers while integrating seamlessly with the async FastAPI architecture and flavor system.

Decision

We selected OpenID Connect (OIDC) with FastAPI Security dependencies for authentication.

Architecture

Rationale

Why OIDC?

  • Industry Standard: Built on OAuth 2.0, widely supported
  • Enterprise Ready: Works with Azure AD, Zitadel, Keycloak, Auth0
  • Rich Claims: Access to user roles, permissions, and attributes
  • Automatic Discovery: Metadata endpoints for easy configuration

Why FastAPI Security Dependencies?

  • Native Integration: Leverages FastAPI’s dependency injection
  • Automatic Protection: All endpoints protected without boilerplate
  • Async Performance: Non-blocking token validation
  • Easy Testing: Simple to mock for unit tests

Authentication Flow

  1. Client sends Authorization: Bearer <token> header
  2. Backend extracts and validates token via OIDC introspection
  3. User object created from token claims
  4. User available in request.state.user for controllers

Implementation

Controller Integration

Custom Authentication Backend

Consequences

Positive

  • Standards Compliance: OIDC industry standard
  • Enterprise Integration: Works with existing identity providers
  • Developer Experience: Minimal boilerplate, automatic user injection
  • Performance: Async token validation
  • Security: Real-time token validation and revocation

Negative

  • External Dependency: Requires OIDC provider availability
  • Network Latency: Token introspection adds round-trip
  • Configuration Complexity: OIDC setup requires OAuth knowledge

Testing

References