9312586f18
- Change .replace(tzinfo=BERLIN_TZ) to BERLIN_TZ.localize() for correct pytz TZ handling - Update Phase 4 to use proper TZ localization for adv_ts - Add documentation section on correct Advoware timestamp handling - Add .gitignore, GOOGLE_SETUP_README.md, and check_db.py utility
93 lines
3.8 KiB
Markdown
93 lines
3.8 KiB
Markdown
# Google Service Account Setup für Advoware Calendar Sync
|
|
|
|
## Übersicht
|
|
Dieser Calendar Sync verwendet **ausschließlich Google Service Accounts** für die Authentifizierung. Kein OAuth, kein Browser-Interaktion - perfekt für Server-Umgebungen!
|
|
|
|
## Voraussetzungen
|
|
- Google Cloud Console Zugang
|
|
- Berechtigung zum Erstellen von Service Accounts
|
|
- (Optional) Google Workspace Admin Zugang für Domain-wide Delegation
|
|
|
|
## Schritt 1: Google Cloud Console aufrufen
|
|
1. Gehen Sie zu: https://console.cloud.google.com/
|
|
2. Melden Sie sich mit Ihrem Google-Konto an
|
|
3. Wählen Sie ein bestehendes Projekt aus oder erstellen Sie ein neues
|
|
|
|
## Schritt 2: Google Calendar API aktivieren
|
|
1. Klicken Sie auf "APIs & Dienste" → "Bibliothek"
|
|
2. Suchen Sie nach "Google Calendar API"
|
|
3. Klicken Sie auf "Google Calendar API" → "Aktivieren"
|
|
|
|
## Schritt 3: Service Account erstellen
|
|
1. Gehen Sie zu "IAM & Verwaltung" → "Service-Konten"
|
|
2. Klicken Sie auf "+ Service-Konto erstellen"
|
|
3. Grundlegende Informationen:
|
|
- **Service-Kontoname**: `advoware-calendar-sync`
|
|
- **Beschreibung**: `Service Account für Advoware-Google Calendar Synchronisation`
|
|
- **E-Mail**: wird automatisch generiert
|
|
4. Klicken Sie auf "Erstellen und fortfahren"
|
|
|
|
## Schritt 4: Berechtigungen zuweisen
|
|
1. **Rolle zuweisen**: Wählen Sie eine der folgenden Optionen:
|
|
- Für volle Zugriffe: `Editor`
|
|
- Für eingeschränkte Zugriffe: `Calendar API Admin` (falls verfügbar)
|
|
2. Klicken Sie auf "Fertig"
|
|
|
|
## Schritt 5: JSON-Schlüssel erstellen und installieren
|
|
1. Klicken Sie auf das neu erstellte Service-Konto
|
|
2. Gehen Sie zum Tab "Schlüssel"
|
|
3. Klicken Sie auf "Schlüssel hinzufügen" → "Neuen Schlüssel erstellen"
|
|
4. Wählen Sie "JSON" als Schlüsseltyp
|
|
5. Klicken Sie auf "Erstellen"
|
|
6. Die JSON-Datei wird automatisch heruntergeladen
|
|
7. **Benennen Sie die Datei um zu: `service-account.json`**
|
|
8. **Kopieren Sie die Datei nach: `/opt/motia-app/service-account.json`**
|
|
9. **Stellen Sie sichere Berechtigungen ein:**
|
|
```bash
|
|
chmod 600 /opt/motia-app/service-account.json
|
|
```
|
|
|
|
## Schritt 6: Domain-wide Delegation (nur für Google Workspace)
|
|
Falls Sie Google Workspace verwenden und auf Kalender anderer Benutzer zugreifen möchten:
|
|
|
|
1. Gehen Sie zurück zum Service-Konto
|
|
2. Aktivieren Sie "Google Workspace Domain-wide Delegation"
|
|
3. Notieren Sie sich die "Unique ID" des Service-Kontos
|
|
4. Gehen Sie zu Google Admin Console: https://admin.google.com/
|
|
5. "Sicherheit" → "API-Berechtigungen"
|
|
6. "Domain-wide Delegation" → "API-Clienten verwalten"
|
|
7. Fügen Sie die Unique ID hinzu
|
|
8. Berechtigungen: `https://www.googleapis.com/auth/calendar`
|
|
|
|
## Schritt 7: Testen
|
|
Nach dem Setup können Sie den Calendar Sync testen:
|
|
|
|
```bash
|
|
# Vollständige Termindetails synchronisieren
|
|
curl -X POST http://localhost:3000/api/flows/advoware_cal_sync \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"full_content": true}'
|
|
|
|
# Nur "blocked" Termine synchronisieren (weniger Details)
|
|
curl -X POST http://localhost:3000/api/flows/advoware_cal_sync \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"full_content": false}'
|
|
```
|
|
|
|
## Wichtige Hinweise
|
|
- ✅ **Kein Browser nötig** - läuft komplett server-seitig
|
|
- ✅ **Automatisch** - einmal setup, läuft für immer
|
|
- ✅ **Sicher** - Service Accounts haben granulare Berechtigungen
|
|
- ✅ **Skalierbar** - perfekt für Produktionsumgebungen
|
|
|
|
## Fehlerbehebung
|
|
- **"service-account.json nicht gefunden"**: Überprüfen Sie den Pfad `/opt/motia-app/service-account.json`
|
|
- **"Access denied"**: Überprüfen Sie die Berechtigungen des Service Accounts
|
|
- **"API not enabled"**: Stellen Sie sicher, dass Calendar API aktiviert ist
|
|
- **"Invalid credentials"**: Überprüfen Sie die service-account.json Datei
|
|
|
|
## Sicherheit
|
|
- Halten Sie die `service-account.json` Datei sicher und versionieren Sie sie nicht
|
|
- Verwenden Sie IAM-Rollen in GCP-Umgebungen statt JSON-Keys
|
|
- Rotiere Service Account Keys regelmäßig
|