# SSO Implementation Progress Tracker

**Project:** Google OAuth SSO for Homelab Infrastructure
**Started:** 2025-11-15
**Status:** 🚧 Phase 1 - In Progress

---

## Overview

Implementing Single Sign-On (SSO) using:
- **Identity Provider:** Authentik
- **Authentication Source:** Google OAuth (Workspace + Gmail)
- **In-Scope Services:** core-api, Nextcloud, Jellyfin, Gitea, Open WebUI, Organizr, code-server

---

## Phase 1: Foundation (Week 1)
**Goal:** Deploy Authentik, configure Google OAuth, protect core-api

### Task Checklist

- [x] **1.1 Deploy Authentik Stack** *(In Progress)*
  - [x] Create `stacks/authentik.yml`
  - [x] Generate secrets (PostgreSQL password, Authentik secret key)
  - [x] Create `.env.authentik` file
  - [x] Create data directories
  - [ ] Deploy via Portainer
  - [ ] Verify services running (4/4: server, worker, postgresql, redis)
  - [ ] Complete initial setup wizard
  - [ ] Access admin portal

- [ ] **1.2 Configure NPM Proxy**
  - [ ] Create proxy host: `auth.schweitz.net` → `authentik-server:9000`
  - [ ] Enable SSL with Let's Encrypt
  - [ ] Test HTTPS access
  - [ ] Verify health endpoint

- [ ] **1.3 Google OAuth Setup**
  - [ ] Create/configure Google Cloud Project
  - [ ] Set up OAuth consent screen
  - [ ] Create OAuth 2.0 credentials
  - [ ] Note Client ID and Client Secret
  - [ ] Configure authorized redirect URIs

- [ ] **1.4 Configure Google Source in Authentik**
  - [ ] Add Google OAuth source
  - [ ] Configure scopes: openid, email, profile
  - [ ] Test login with Google Workspace account
  - [ ] Test login with Gmail account
  - [ ] Verify user profile synced

- [ ] **1.5 Implement core-api OIDC Authentication**
  - [ ] Add dependencies: PyJWT, python-jose
  - [ ] Create `src/auth/oidc.py` module
  - [ ] Update `src/config.py` with OIDC settings
  - [ ] Create Authentik OIDC provider for core-api
  - [ ] Protect infrastructure endpoints
  - [ ] Update OpenAPI docs with security scheme

- [ ] **1.6 Testing & Validation**
  - [ ] Test unauthenticated API request (expect 401)
  - [ ] Test authenticated API request with valid token
  - [ ] Verify user claims available in endpoints
  - [ ] Test token expiration handling
  - [ ] Test admin-only endpoints
  - [ ] Update widget for OAuth flow

---

## Progress Log

### 2025-11-15 - 21:20 CET

**[Completed]** Shared Infrastructure Architecture
- ✅ Designed shared PostgreSQL + Redis architecture
- ✅ Created `SHARED_INFRASTRUCTURE_ARCHITECTURE.md` documentation
- ✅ Created separate stacks for modularity:
  - `postgres-shared.yml` (centralized database)
  - `redis-shared.yml` (centralized cache)
  - `authentik-shared.yml` (using shared backends)
- ✅ Generated secure credentials (all passwords 32-byte random)
- ✅ Created unified `docker-dataplane` network
- ✅ Created PostgreSQL init script for multi-database setup
- ✅ Created environment files:
  - `.env.postgres` (PostgreSQL + app DB passwords)
  - `.env.authentik-shared` (Authentik config)

**Architecture Benefits:**
- Resource savings: ~400MB RAM per service using shared infrastructure
- Centralized backups and monitoring
- Easier maintenance and upgrades
- Modular deployment (PostgreSQL and Redis as separate stacks)

**[Next]** Deploy shared infrastructure, then Authentik

---

## Next: Create Authentik Stack

Creating `stacks/authentik.yml` with:
- authentik-server
- authentik-worker
- PostgreSQL database
- Redis cache

Expected resources: ~500MB RAM, 1.5 CPU, 5GB storage

---

## Notes

- **Architecture Decision:** FastAPI native OIDC for core-api (not NPM forward auth)
- **Out of Scope:** Infrastructure tools, data providers, local services
- **Security:** All passwords/secrets via environment variables, not committed to git