OAuth Implementation Guide

rforssen.net – *Practical guide on how to implement authentication correctly*

🟦 A. In-App Authentication

Mixed public content + authenticated personalization

This is used when an application should load normally for anyone, but behave differently based on login state and role.

Examples:

• Media platform
• Genealogy
• Future landing page with personalized visibility

1️⃣ Backend Requirements

You already have the correct backend foundation:

/auth/me Contract

If NOT authenticated:

{
  "authenticated": false
}

If authenticated:

{
  "authenticated": true,
  "user": {
    "email": "...",
    "name": "...",
    "sub": "google-id"
  },
  "role": "me | family | public"
}

2️⃣ Frontend Implementation Pattern

Every page using in-app authentication follows this pattern:

Your media app already implements this extremely well (using fetchAuth(), initAuth(), BroadcastChannel, popup login, etc.). This is your platform standard.

3️⃣ Personalizing / Filtering Content

A mixed page normally behaves like this:

• Guests can see public elements
• Family sees extra things
• Roland sees everything

Filtering works with classes and logic like:

// If not logged in
hideElementsWithClass("onlyMe");
hideElementsWithClass("familyOnly");

// If Roland
show everything
setRole("me");

// If Family
show public + family

4️⃣ Backend Security Enforcement

Even if UI hides features, the backend always decides access.

5️⃣ Cookie Security

Ensure Flask session configuration:

SESSION_COOKIE_SECURE = True
SESSION_COOKIE_HTTPONLY = True
SESSION_COOKIE_SAMESITE = "Lax"

6️⃣ Redirect Safety

Only approve whitelisted domains when handling: ?redirect=

7️⃣ Implementation Checklist

• Page loads for everyone
• /auth/me called on load
• Login badge shows correctly
• Features filtered by role
• Backend enforces authorization
• Cookies secure

🟥 B. Edge Authentication

Hard gate – block all access unless authenticated

Use this when nothing should be visible unless the user is authenticated. Not even the UI. No partial access. No leaks.

Perfect for:

• phpMyAdmin
• Admin dashboards
• Cluster management tools
• Dangerous development utilities
• Sensitive internal pages

Conceptual Flow

Who Handles Authentication?

• NOT the frontend
• NOT Flask
• Traefik + oauth2-proxy do it

This means the protected application never sees anonymous traffic.

Edge Authentication Guarantees

• App does not render unless authenticated
• No HTML exposure
• No debugging info for strangers
• No “view source” guessing
• No discovery of internal tools

Implementation Requirements

• Ingress routes traffic to oauth2-proxy
• oauth2-proxy handles Google login
• Authorized users proceed
• Unauthorized users denied

Optional Identity Headers

If app wants to know who logged in:

X-Auth-User
X-Auth-Email
X-Auth-Verified

App may:

• Use these
• Ignore them

Behavior Rules

• No “guest mode”
• No partial rendering
• No public visibility
• Always fail safe

When NOT to Use Edge Auth

• If public should see the page
• If family needs normal UX
• If different role experiences exist
• If app benefits from personalization

Strategy Summary

Platform Philosophy