first commit
This commit is contained in:
198
README.md
Normal file
198
README.md
Normal file
@ -0,0 +1,198 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user