# Pocket-ID OIDC Integration

## Übersicht

myCRM unterstützt nun Single Sign-On (SSO) via Pocket-ID (OpenID Connect).

## Konfiguration

### 1. Pocket-ID Server einrichten

Stellen Sie sicher, dass Ihr Pocket-ID Server läuft (Standard: `http://localhost:17170`).

### 2. Client in Pocket-ID registrieren

1. Öffnen Sie die Pocket-ID Admin-Oberfläche
2. Erstellen Sie einen neuen OAuth2/OIDC Client mit folgenden Einstellungen:
   - **Name**: myCRM
   - **Redirect URI**: `http://localhost:8000/connect/pocketid/check`
   - **Grant Types**: Authorization Code
   - **Scopes**: `openid`, `profile`, `email`
   - **Response Types**: `code`

3. Notieren Sie:
   - Client ID
   - Client Secret

### 3. Umgebungsvariablen konfigurieren

Bearbeiten Sie `.env.local` (NICHT `.env` für Produktionsumgebungen):

```bash
# Pocket-ID OIDC Configuration
OAUTH_POCKET_ID_URL=http://localhost:17170
OAUTH_POCKET_ID_CLIENT_ID=<your-client-id>
OAUTH_POCKET_ID_CLIENT_SECRET=<your-client-secret>
OAUTH_POCKET_ID_REDIRECT_URI=http://localhost:8000/connect/pocketid/check
```

### 4. Cache leeren

```bash
php bin/console cache:clear
```

## Verwendung

### Login-Flow

1. Benutzer klickt auf "Mit Pocket-ID anmelden" auf der Login-Seite
2. Weiterleitung zu Pocket-ID Authorization Endpoint
3. Benutzer authentifiziert sich bei Pocket-ID
4. Redirect zurück zu myCRM mit Authorization Code
5. myCRM tauscht Code gegen Access Token
6. Benutzer-Informationen werden von Pocket-ID abgerufen
7. Benutzer wird erstellt (falls neu) oder aktualisiert
8. Benutzer wird eingeloggt und zum Dashboard weitergeleitet

### Automatische Benutzererstellung

Wenn ein Benutzer sich zum ersten Mal mit Pocket-ID anmeldet:
- Ein neuer User-Account wird automatisch erstellt
- E-Mail, Vorname und Nachname werden von Pocket-ID übernommen
- Standard-Rolle: `ROLE_USER`
- Account ist sofort aktiv

### Bestehende Benutzer

Wenn ein Benutzer mit derselben E-Mail-Adresse bereits existiert:
- Vorname und Nachname werden aktualisiert (falls von Pocket-ID bereitgestellt)
- `lastLoginAt` wird aktualisiert
- Bestehende Rollen und Berechtigungen bleiben erhalten

## Sicherheit

### Implementierte Maßnahmen

- ✅ State Parameter zum Schutz vor CSRF-Angriffen
- ✅ TLS/HTTPS für Produktion erforderlich
- ✅ Sichere Token-Validierung
- ✅ Automatische Token-Rotation
- ✅ Session-basierte Authentifizierung nach OIDC-Login

### Produktions-Checkliste

- [ ] HTTPS aktivieren (`OAUTH_POCKET_ID_URL` auf HTTPS-Endpoint ändern)
- [ ] Redirect URI auf Produktions-URL ändern
- [ ] Client Secret sicher speichern (z.B. Symfony Secrets)
- [ ] Pocket-ID Server mit TLS/SSL absichern
- [ ] Rate Limiting konfigurieren
- [ ] Logging für OIDC-Fehler aktivieren

## Troubleshooting

### "Redirect URI mismatch"
- Überprüfen Sie, dass die Redirect URI in Pocket-ID exakt mit `OAUTH_POCKET_ID_REDIRECT_URI` übereinstimmt
- Achten Sie auf http vs. https und trailing slashes

### "Invalid client credentials"
- Client ID und Secret in `.env.local` überprüfen
- Cache leeren: `php bin/console cache:clear`

### "Email not provided by Pocket-ID"
- Stellen Sie sicher, dass der Scope `email` in der Pocket-ID Client-Konfiguration aktiviert ist
- Überprüfen Sie, dass der Benutzer in Pocket-ID eine E-Mail-Adresse hinterlegt hat

### Benutzer kann sich nicht anmelden
- Überprüfen Sie Symfony-Logs: `var/log/dev.log`
- Aktivieren Sie Debug-Logging im `PocketIdAuthenticator`
- Prüfen Sie die Pocket-ID Server-Logs

## Architektur

### Komponenten

1. **PocketIdProvider** (`src/OAuth/PocketIdProvider.php`)
   - Extends League\OAuth2\Client GenericProvider
   - Konfiguriert OIDC-Endpoints

2. **PocketIdResourceOwner** (`src/OAuth/PocketIdResourceOwner.php`)
   - Repräsentiert OIDC User-Informationen
   - Extrahiert Claims (sub, email, name, etc.)

3. **PocketIdAuthenticator** (`src/Security/PocketIdAuthenticator.php`)
   - Symfony Security Authenticator
   - Handhabt OAuth2-Flow
   - Erstellt/aktualisiert Benutzer

4. **OAuthController** (`src/Controller/OAuthController.php`)
   - Start-Endpoint: `/connect/pocketid`
   - Callback-Endpoint: `/connect/pocketid/check`

### OIDC-Flow

```
User → myCRM → Pocket-ID (Authorization) → User authenticates
     ← Redirect with code ← 
     → Exchange code for token →
     ← Access Token + ID Token ←
     → Fetch user info →
     ← User claims ←
User logged in
```

## Alternative Authentifizierung

Die traditionelle Login-Methode (E-Mail + Passwort) bleibt weiterhin verfügbar und kann parallel zu OIDC verwendet werden.

## Weitere Informationen

- [Pocket-ID Dokumentation](https://github.com/stonith404/pocket-id)
- [OAuth2 Client Bundle](https://github.com/knpuniversity/oauth2-client-bundle)
- [OpenID Connect Spezifikation](https://openid.net/specs/openid-connect-core-1_0.html)