OAuth-Plan – Step 1A Milestone: Authentication Architecture

1️⃣ Purpose of This Document

This document formally completes Step 1A of the OAuth-Plan. It defines and freezes the high-level authentication architecture currently used on rforssen.net, including components, trust boundaries, the Google OAuth popup flow, session model, routing logic, and canonical diagrams.

This milestone does not change implementation behavior. Its purpose is to ensure clarity and a stable architectural reference before further development or refactoring.

2️⃣ High-Level Architecture (Human Description)

Core Components

User Browser – runs the UI, performs login, executes JavaScript
Traefik Ingress – Kubernetes entry point, routes traffic
Apache Pods – serve frontend HTML/JS application
Flask API Pod – handles /api, authentication, backend logic
Google OAuth – identity provider

Routing Model

/ → Apache Frontend
/api/* → Flask Backend

Authentication Model

Login is done via a popup window
Flask performs OAuth 2 / OpenID Connect
A secure session cookie is issued
BroadcastChannel notifies main window when login succeeds

Cookie / Session

Stored in Flask session
Domain: .rforssen.net
Secure, HttpOnly, SameSite=None

3️⃣ High-Level Architecture Diagram (Mermaid Text)

This is the canonical Mermaid representation of the authentication architecture.

flowchart LR

User((User Browser))
Traefik[Traefik Ingress\nrforssen.net]
Apache[Apache Web Frontend\n(Static + JS App)]
Flask[Flask API\n(Auth + Backend Services)]
Google[(Google OAuth\nIdentity Provider)]

User -->|HTTPS| Traefik
Traefik -->|/| Apache
Traefik -->|/api/*| Flask
Flask -->|OAuth Redirect & Token| Google
Google -->|Callback + Code| Flask

Apache -. fetch auth .-> Flask
Apache -. API calls .-> Flask

classDef user fill:#4CAF50,color:white;
classDef service fill:#2980b9,color:white;
classDef gateway fill:#8e44ad,color:white;
classDef idp fill:#f1c40f,color:black;

class User user
class Traefik gateway
class Apache,Flask service
class Google idp

Figure: High-Level OAuth Architecture (Rendered from Mermaid Source Above)

4️⃣ Authentication Flow Sequence (Mermaid Text)

Logical user authentication flow using popup-based OAuth login.

sequenceDiagram
    participant U as User
    participant B as Browser (Main Window)
    participant P as Popup Window
    participant A as Apache UI
    participant API as Flask Auth API
    participant G as Google OAuth

    U->>B: Click "Sign in"
    B->>API: GET /auth/login/google?popup=true
    API-->>G: Redirect to Google OAuth
    G-->>U: Show Google Login Page
    U->>G: Complete Login
    G-->>API: Redirect Back + Code
    API->>G: Exchange Code -> Token
    G-->>API: Token + User Info
    API->>API: Validate + Store Session
    API-->>B: Set Secure Session Cookie

    API-->>P: Redirect to /oauth-popup-complete.html
    P-->>B: Broadcast auth:success
    B->>API: GET /auth/me
    API-->>B: { authenticated:true, user:... }
    B->>A: Update UI (Signed In)

Figure: OAuth Authentication Sequence Flow

5️⃣ PlantUML Version (Self-Contained Text)



  @startuml
  title OAuth-plan: System Context

  actor "User" as User

  rectangle "K3s Cluster" {
    rectangle "Apache Frontend\n(Serves HTML/JS)" as Apache
    rectangle "Traefik\n(Ingress + Routing)" as Traefik
    rectangle "Flask API\n(OAuth + APIs)" as Flask
  }

  rectangle "Google OAuth 2.0\n(accounts.google.com)" as Google

  User --> Apache : Browse https://www.rforssen.net
  Apache --> Traefik : HTTP(S)
  Traefik --> Flask : Routes /api/*
  User --> Flask : AJAX /auth + cookies\n(via browser)
  Flask --> Google : OAuth Authorization Code Flow
  Google --> Flask : Tokens + Profile
  Flask --> User : Secure Session Cookie\n(domain=.rforssen.net)

  @enduml

Figure: PlantUML Popup Authentication Flow

6️⃣ Key Architecture Decisions

Identity Provider: Google OAuth
Login UX: Popup login (not full page redirect)
Ingress Strategy: Traefik routing
Authentication Session: Flask server-side session
Cookie Domain: .rforssen.net
Cookie Flags: Secure + HttpOnly + SameSite=None
Frontend Platform: Apache pods serving static JS
Backend Platform: Flask pod

7️⃣ Known Limitations (To Handle Later)

No centralized role model yet
No cross-app SSO document yet (even if architecture allows it)
Failure flows will be formally documented in Step 1B
No formal token refresh policy written yet

8️⃣ Milestone Status

Step 1A of the OAuth-Plan is now completed.
Architecture is documented, stable, and well understood.

Next milestone: Step 1B — Failure & Edge Case Flow Documentation.

OAuth-Plan – Step 1A Milestone

Authentication Architecture Documentation