portainer-core/docs/SSO_IMPLEMENTATION_PROGRESS.md

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

• 1.1 Deploy Authentik Stack (In Progress)

  • Create stacks/authentik.yml
  • Generate secrets (PostgreSQL password, Authentik secret key)
  • Create .env.authentik file
  • 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