motia/bitbylaw/docs/GOOGLE_SETUP.md

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:

   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:

# 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