OpenID Connect (OIDC) Identity Provider

Ein produktionsbereiter OIDC Identity Provider (IdP) in Flask, konzipiert für Homelab- und Self-Hosting-Umgebungen. Bietet eine vollständige, datenbankgestützte Implementierung des OIDC Authorization Code Flows mit PostgreSQL, erweiterter Benutzerverwaltung und Docker-basiertem Deployment.

Features

• OIDC Authorization Code Flow: Vollständige und standardkonforme Implementierung.
• Datenbank-basiert: PostgreSQL für die Produktion, SQLite für die Entwicklung.
• Produktionsreif:
  • Docker-Deployment: docker-compose für einfaches Setup von Server und Datenbank.
  • Environment-Konfiguration: Sichere Verwaltung von Secrets und Konfiguration über .env-Dateien.
  • WSGI Server: Gunicorn für robusten Betrieb im Docker-Container.
  • Datenbank-Migrationen: Schema-Änderungen werden mit Flask-Migrate (Alembic) verwaltet.
• Sicherheit:
  • bcrypt-Hashing: Sicherer-Algorithmus zum Speichern von Passwörtern.
  • Rate Limiting: Schutz vor Brute-Force-Angriffen auf kritischen Endpoints.
  • Audit Logging: Detaillierte Protokollierung sicherheitsrelevanter Aktionen.
• Benutzer- und Admin-Verwaltung:
  • Admin-Dashboard: Umfassende Weboberfläche zur Verwaltung von Benutzern, Rollen und Berechtigungen.
  • Self-Service: Benutzer können sich registrieren und ihr Passwort ändern.
  • Rollen & Berechtigungen: Flexibles System zur Zugriffssteuerung.
  • Multi-Client-Unterstützung: Verwaltung mehrerer OIDC-Clients über das Admin-Dashboard.
• Monitoring:
  • Health Check: /health-Endpoint zur Überwachung des Dienststatus.

Technologie-Stack

• Backend: Flask
• Datenbank: PostgreSQL (Produktion), SQLite (Entwicklung)
• Deployment: Docker, Docker Compose
• WSGI Server: Gunicorn
• Bibliotheken: Flask-SQLAlchemy, Flask-Limiter, PyJWT, python-dotenv, Flask-Migrate

Schnellstart (Docker)

Dieser IdP ist für den Betrieb in Docker optimiert.

1. Konfiguration vorbereiten

Kopieren Sie die Produktions-Konfigurationsvorlage. Alle notwendigen Secrets werden automatisch generiert.

cp .env.production .env

Passen Sie die Konfiguration in der .env-Datei an. Das Wichtigste ist, den OIDC_ISSUER auf Ihre öffentliche URL zu setzen.

# Öffnen Sie die .env Datei mit einem Editor
nano .env

# Passen Sie diese Zeile an Ihre Domain an:
# Beispiel: OIDC_ISSUER=https://auth.deine-domain.de
OIDC_ISSUER=https://auth.example.com

2. Server starten

Starten Sie den OIDC-Server und die PostgreSQL-Datenbank mit docker-compose.

# Startet die Dienste im Hintergrund und baut die Images falls notwendig
./deploy.sh

Der Server ist jetzt unter http://localhost:5000 erreichbar (oder unter dem konfigurierten Port).

3. Admin-Passwort ändern (WICHTIG!)

Nach dem ersten Start müssen Sie sofort das Standard-Admin-Passwort ändern.

1. Öffnen Sie http://localhost:5000/admin/login in Ihrem Browser.
2. Loggen Sie sich ein mit:
   • Benutzername: admin
   • Passwort: admin123
3. Navigieren Sie zur Benutzerverwaltung, wählen Sie den admin-Benutzer und vergeben Sie ein neues, sicheres Passwort.

OIDC Endpoints

• Discovery Document: /.well-known/openid-configuration
• Authorization Endpoint: /authorize
• Token Endpoint: /token
• UserInfo Endpoint: /userinfo

Lokale Entwicklung (ohne Docker)

Für Entwicklungszwecke kann der Server auch direkt ohne Docker gestartet werden.

1. Installation

# Virtuelle Umgebung erstellen und aktivieren
python3 -m venv venv
source venv/bin/activate

# Dependencies installieren
pip install -r requirements.txt

2. Konfiguration

Stellen Sie sicher, dass die FLASK_ENV Umgebungsvariable auf development gesetzt ist (oder nicht gesetzt ist), damit die SQLite-Datenbank verwendet wird.

export FLASK_APP=oidc_server.py
export FLASK_ENV=development

3. Datenbank initialisieren

Für eine neue Datenbank müssen Sie die Migrationen anwenden:

# Erstellt die Datenbank und wendet alle Migrationen an
flask db upgrade

# Füllt die Datenbank mit initialen Test-Benutzern
flask seed

4. Server starten

# Server starten
flask run

Der Server läuft auf http://localhost:5000.

Datenbank-Migrationen

Schema-Änderungen werden mit Flask-Migrate verwaltet.

Workflow für Schema-Änderungen:

1. Modelle ändern: Passen Sie die Modelle in models.py an.
2. Migration erstellen: Generieren Sie eine neue Migrations-Datei.

   flask db migrate -m "Beschreibung der Änderungen"
   

3. Migration anwenden: Wenden Sie die Änderungen auf die Datenbank an.

   flask db upgrade
   

Konfiguration

Die gesamte Konfiguration wird über die .env-Datei gesteuert. Eine detaillierte Vorlage finden Sie in .env.example.

Variable	Beschreibung	Standardwert (Dev)
FLASK_ENV	development oder production. Steuert, welche Config geladen wird.	development
OIDC_ISSUER	Die öffentliche URL des IdP. Muss für die Produktion gesetzt werden.	http://localhost:5000
SECRET_KEY	Geheimer Schlüssel für die Flask-Session.	dev-secret-key...
DATABASE_URL	Verbindungs-URL für die Datenbank (für PostgreSQL in Produktion).	sqlite:///oidc.db
ACCESS_TOKEN_LIFETIME	Gültigkeitsdauer für Access Tokens in Sekunden.	3600 (1h)

Sicherheit

• Passwörter: Werden ausschließlich als bcrypt-Hash gespeichert.
• Rate Limiting: Die Endpoints /login, /admin/login und /token sind gegen Brute-Force-Angriffe durch einen Rate Limiter geschützt.
• Audit Log: Kritische Aktionen wie Login-Versuche (erfolgreich/fehlgeschlagen) und administrative Änderungen an Benutzern werden in der audit_logs-Tabelle protokolliert.
• Asymmetric Token Signing (RS256): ID Tokens werden mit dem RS256-Algorithmus signiert. Der Public Key zur Validierung ist über den /jwks-Endpoint verfügbar.
• Keine Secrets im Code: Alle sensiblen Daten werden über Umgebungsvariablen aus der .env-Datei geladen.

Dokumentation

Für Anwendungs-Entwickler (OIDC Integration)

Sie möchten Ihre Anwendung mit diesem OIDC Provider verbinden?

• Quick Start Guide ⚡ - In 10 Minuten integriert (Python, Node.js, PHP Beispiele)
• API Integration Guide 📚 - Vollständige API-Dokumentation und OIDC-Flow

Für System-Administratoren (Deployment)

Sie möchten den OIDC Provider selbst hosten?

• Deployment Guide 🚀 - Anleitung für Entwicklungs- und Produktionsumgebungen
• Production Readiness ✅ - Produktions-Checkliste

Für Projekt-Entwickler (Code-Beiträge)

Sie möchten am Provider selbst entwickeln?

• Architecture 🏗️ - System-Architektur und Design-Entscheidungen
• Testing Guide 🧪 - Anleitung zum Testen der Anwendung
• Python Quick Start Guide 📖 - Best Practices für Python API-Entwicklung
• TODO & Roadmap 📋 - Geplante Features und Verbesserungen

Nächste Schritte

Die folgenden wichtigen Features sind in Entwicklung:

• Refresh Tokens: Für eine verbesserte User Experience ohne häufige Logins.
• PKCE Support: Für sichere Public Clients (SPAs, Mobile Apps)

Eine vollständige Liste finden Sie in docs/TODO.md.