OAuth Architecture

rforssen.net – Authentication Strategy, Principles & Design

Authentication Mental Model

Authentication Flow

Current Implementation (Modules & File Layout)

/rforssen_net/
  js/
    auth/
      authClient.js
      initAuth.js
      setupAuthUI.js
  authtest/
    index.html
    js/
      authUI.js         (app-specific UI demo)
  oauth-popup-complete.html
  

{
  "authenticated": false,
  "is_authorized": false,
  "user": null,
  "role": "public"
}

{
  "authenticated": true,
  "is_authorized": true,
  "user": {
    "email": "...",
    "name": "...",
    "role": "admin | family | public | ..."
  },
  "role": "admin | family | public | ..."
}

<!-- /oauth-popup-complete.html -->
<script>
  try {
    const bc = new BroadcastChannel("auth");
    bc.postMessage({ type: "auth:success" });
    bc.close();
  } catch (e) {}

  setTimeout(() => window.close(), 150);
</script>
  

Roland maintains multiple environments:

• Personal development tools
• Administrative / platform tools
• Family-facing applications
• Mixed public / private services

Authentication Strategies

No single authentication pattern fits all of them. Therefore the platform supports two complementary authentication strategies:

1️⃣ In-App Authentication
User-Aware UI + Filtered Content

Objective

Use this strategy when the page or app should:

• Load even if the user is not logged in
• Adapt its behavior depending on login
• Support roles such as “public / family / Roland”
• Provide rich UI experience
• Allow public + private content in same app

Typical use cases:

• Media platform
• Genealogy
• Landing page with controlled visibility
• Any family-facing application

Backend Requirements

Google OAuth + secure session cookies.

/auth/me Contract (Current)

If user is NOT authenticated (401):

{
  "authenticated": false,
  "is_authorized": false,
  "user": null,
  "role": "public"
}

If user IS authenticated:

{
  "authenticated": true,
  "is_authorized": true,
  "user": {
    "email": "...",
    "name": "...",
    "role": "admin | family | public | ..."
  },
  "role": "admin | family | public | ..."
}

Frontend Responsibilities

• Probe auth state at page load via /auth/me (with credentials: "include")
• Render login badge if not authenticated
• Render avatar/user + logout if authenticated
• Enable / disable features depending on role
• Do not trust frontend role checks for security; backend enforces policy

Backend Security Rules

• Verify session cookie
• Verify identity
• Verify role
• Reject unauthorized calls

Cookie Security Requirements

SESSION_COOKIE_SECURE   = True
SESSION_COOKIE_HTTPONLY = True
SESSION_COOKIE_SAMESITE = "Lax"

Redirect Safety

Only allow trusted redirect destinations.

Summary

🔁 Authentication Invocation Model (Frontend)

This section explains where authentication is invoked in a frontend application, and which parts are reusable vs app-specific.

Mental Model

Authentication in rforssen.net is event-driven, not global.

There is no background authentication process running continuously. Instead, authentication is invoked explicitly at a small number of well-defined points.

The Three Authentication Entry Points

Every in-app authenticated page invokes authentication in exactly three situations:

page load →
  setupAuthUI() →
    fetchAuth() →
      GET /auth/me (credentials: include) →
        renderAuthBadge()
        decide page behavior

popup login →
  oauth-popup-complete.html →
    BroadcastChannel("auth") "auth:success" →
      (opener) fetchAuth() →
        GET /auth/me →
          re-render auth badge / enable features

logout click →
  POST /auth/logout →
    session cleared →
      GET /auth/me →
        unauthenticated state →
          render login button

What Does NOT Invoke Authentication

• Rendering unrelated UI components
• Fetching non-auth application data (unless the backend endpoint requires it)
• Clicking internal UI elements
• Navigation inside the page

Authentication is always explicit and intentional.

Reusable vs App-Specific Code (Current)

✅ How to Add Auth to a New Page (Minimal Pattern)

Minimal HTML Pattern

<div id="authBadge"></div>

<script type="module">
  import { setupAuthUI } from "../js/auth/setupAuthUI.js";
  import { renderAuthBadge, wireAuthUI } from "./js/authUI.js";

  const { auth } = await setupAuthUI({ renderAuthBadge, wireAuthUI });

  if (auth.is_authorized) {
    // app-specific load here
  }
</script>

Important Note: Cookies Must Be Sent to the API

Design Principle

This keeps the platform predictable, debuggable, reusable, and difficult to break accidentally.

2️⃣ Edge Authentication
Hard Gate / Full Access Blocker

Objective

Use this when:

• Page must NOT be visible without login
• No public access allowed
• No partial visibility allowed
• No information leakage accepted

Typical use cases:

• phpMyAdmin
• Admin tools
• Cluster & maintenance utilities
• Dangerous dev tools
• Sensitive dashboard systems

Implementation Summary

• Ingress sends traffic through oauth2-proxy
• oauth2-proxy handles Google login
• Only authenticated traffic reaches application

Optional Identity Injection

oauth2-proxy can inject headers:

X-Auth-User
X-Auth-Email

Backend may use them — or ignore them.

Behavior Rules

• No page content without login
• No public mode
• No anonymous visibility
• Fail safe if auth fails

Summary

Which Strategy To Use?

Platform Philosophy

They are not competing approaches — they are deliberately chosen tools, each excellent at its job.

Future Enhancements (Optional)

• Unified auth role logic
• Shared identity model
• Standardized /auth/me contract
• Backend integration with edge identity
• Failover auth strategy