oicd/README.md

# 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).