# 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. ```bash 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.** ```bash # Ö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`. ```bash # 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 ```bash # 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. ```bash export FLASK_APP=oidc_server.py export FLASK_ENV=development ``` ### 3. Datenbank initialisieren Für eine neue Datenbank müssen Sie die Migrationen anwenden: ```bash # Erstellt die Datenbank und wendet alle Migrationen an flask db upgrade # Füllt die Datenbank mit initialen Test-Benutzern flask seed ``` ### 4. Server starten ```bash # 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. ```bash flask db migrate -m "Beschreibung der Änderungen" ``` 3. **Migration anwenden**: Wenden Sie die Änderungen auf die Datenbank an. ```bash 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](docs/QUICKSTART.md)** ⚡ - In 10 Minuten integriert (Python, Node.js, PHP Beispiele) - **[API Integration Guide](docs/API_GUIDE.md)** 📚 - Vollständige API-Dokumentation und OIDC-Flow ### Für System-Administratoren (Deployment) Sie möchten den OIDC Provider selbst hosten? - **[Deployment Guide](docs/deployment.md)** 🚀 - Anleitung für Entwicklungs- und Produktionsumgebungen - **[Production Readiness](docs/PRODUCTION_READY.md)** ✅ - Produktions-Checkliste ### Für Projekt-Entwickler (Code-Beiträge) Sie möchten am Provider selbst entwickeln? - **[Architecture](docs/ARCHITECTURE.md)** 🏗️ - System-Architektur und Design-Entscheidungen - **[Testing Guide](docs/TESTING.md)** 🧪 - Anleitung zum Testen der Anwendung - **[Python Quick Start Guide](docs/guides/python-quick-start-guide.md)** 📖 - Best Practices für Python API-Entwicklung - **[TODO & Roadmap](docs/TODO.md)** 📋 - 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](docs/TODO.md).