GCalendar Gateway

Eine kleine Webanwendung, die Benutzer über Authentik anmeldet und ihren Google-Kalender nach einer einmaligen Google-Freigabe dauerhaft lesbar macht. Google-Passwörter werden weder abgefragt noch gespeichert. Refresh-Tokens liegen verschlüsselt in einer lokalen SQLite-Datenbank.

Funktionen

• zentrale Anmeldung über Authentik (OpenID Connect)
• einmalige Verknüpfung mit Google OAuth 2.0
• automatische Erneuerung kurzlebiger Google Access-Tokens
• responsive Monatsübersicht für alle Google-Kalender mit Auswahl, Farben sowie Vor-/Zurück- und Heute-Navigation
• Termine in beschreibbaren Kalendern erstellen, bearbeiten und löschen
• verschlüsselte Tokenablage pro Authentik-Benutzer
• Version, Commit und Updatezustand in der Fußzeile
• sicher geprüftes Fast-Forward-Update über Oberfläche oder CLI

Voraussetzungen

• Python 3.10 oder neuer
• Authentik mit einem OAuth2/OpenID-Provider
• Google-Cloud-Projekt mit aktivierter Google Calendar API
• Google OAuth Client vom Typ „Web application“
• für den Produktivbetrieb: Linux mit systemd und HTTPS-Reverse-Proxy

Konfiguration

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env

Zwei sichere Werte erzeugen:

python3 -c 'import secrets; print(secrets.token_hex(32))'
python3 -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'

Der erste Wert kommt in SECRET_KEY, der zweite in TOKEN_ENCRYPTION_KEY. Ein Wechsel des Verschlüsselungsschlüssels macht bereits gespeicherte Google-Tokens unlesbar.

Authentik

Im Authentik-Provider wird folgende Redirect-URI eingetragen:

https://calendar.example.com/auth/callback

Issuer, Client-ID und Client-Secret werden anschließend über AUTHENTIK_ISSUER, AUTHENTIK_CLIENT_ID und AUTHENTIK_CLIENT_SECRET konfiguriert.

Google

In der Google Cloud Console die Calendar API aktivieren, den OAuth- Zustimmungsbildschirm konfigurieren und einen Webclient mit dieser Redirect-URI anlegen:

https://calendar.example.com/google/callback

Client-ID und Client-Secret kommen in GOOGLE_CLIENT_ID und GOOGLE_CLIENT_SECRET. Die Anwendung fordert Zugriff auf die Kalenderliste und auf Termine an, damit autorisierte Benutzer Einträge anzeigen und verwalten können.

Interner Dashboard-Zugriff

Nach der einmaligen Google-Verknüpfung liefert GET /api/dashboard/events die nächsten sieben Termine aus allen sichtbaren, einschließlich abonnierter Kalender. Der Nur-Lese-Endpunkt wird über den Header X-API-Key geschützt:

CALENDAR_DASHBOARD_API_KEY=ein-zufaelliger-wert-mit-mindestens-32-zeichen
DASHBOARD_GOOGLE_SUBJECT=

Bei genau einer gespeicherten Google-Verbindung kann DASHBOARD_GOOGLE_SUBJECT leer bleiben. Bei mehreren Verbindungen wird dort die gewünschte Authentik-Subject-ID eingetragen.

Start und Installation

Lokaler Entwicklungsstart unter Windows oder Linux:

python app.py

Produktivinstallation auf Linux:

sudo SERVICE_USER="$USER" ./install-systemd.sh

Der Dienst hört standardmäßig auf Port 8340. Vor ihm sollte ein HTTPS- Reverse-Proxy betrieben werden.

Update

Das vollständige CLI-Update erfolgt mit genau einem Befehl:

./update.sh

Das Skript bricht bei lokalen Änderungen, eigenen Commits oder einem abweichenden Branch ab. Zulässige Updates verwenden ausschließlich git pull --ff-only, aktualisieren vorhandene Python-Abhängigkeiten und starten gcalendar-gateway.service neu. Dieselbe Vorprüfung wird für das Update in der Fußzeile verwendet.

Versionsschema

Die Version in VERSION folgt Semantic Versioning im Format 0.0.0. Die Fußzeile ergänzt sie um Commit und Commit-Datum und prüft den Git-Upstream alle fünf Minuten.

Die öffentlichen Seiten /datenschutz und /nutzungsbedingungen stellen die für Google OAuth benötigten rechtlichen Informationen bereit. Die dort angezeigte Kontaktadresse wird mit LEGAL_CONTACT_EMAIL konfiguriert.

Datenschutz und Sicherung

Die Verzeichnisse data/ und die Datei .env sind nicht Bestandteil von Git. Für eine Wiederherstellung müssen beide separat und geschützt gesichert werden. Über „Google trennen“ wird die gespeicherte Verbindung des angemeldeten Benutzers aus der lokalen Datenbank entfernt.