# Gmail-Anbindung einrichten

## Kurzfassung

1. In der Google Cloud Console ein Projekt anlegen oder auswaehlen.
2. Die Gmail API aktivieren.
3. OAuth Consent Screen konfigurieren.
4. OAuth-Client vom Typ "Web application" erstellen.
5. Als Redirect-URI eintragen:

```text
https://be.bestforming.de/gmail-anbindung/oauth_callback.php
```

6. `public/gmail-anbindung/config.local.example.php` nach `config.local.php` kopieren und Client-ID, Client-Secret und Redirect-URI eintragen.
7. `https://be.bestforming.de/gmail-anbindung/index.php` oeffnen und mit Google verbinden.

## Benoetigte OAuth-Daten

- Client-ID
- Client-Secret
- Redirect-URI
- Gmail-Scope: `https://www.googleapis.com/auth/gmail.readonly`

Der Scope ist absichtlich lesend. Damit kann die Anwendung E-Mails und Attachments lesen, aber keine E-Mails senden, loeschen oder veraendern.

## Produktionshinweise

Die aktuelle Implementierung speichert das Access Token nur in der PHP-Session. Das reicht fuer einen ersten Test und fuer das technische Grundgeruest. Fuer eine produktive Anwendung sollten Tokens verschluesselt in einer Datenbank gespeichert werden.

Wenn die Anwendung dauerhaft ohne erneute Anmeldung lesen soll, muss das Refresh Token ebenfalls gespeichert und zum Erneuern des Access Tokens verwendet werden. Google liefert ein Refresh Token typischerweise nur, wenn `access_type=offline` gesetzt ist und der Nutzer der App neu zustimmt.

Fuer eine oeffentliche App werden ausserdem benoetigt:

- Datenschutzseite mit genauer Beschreibung der Gmail-Nutzung
- OAuth Consent Screen mit App-Name, Support-Mail und autorisierten Domains
- Google-Verifizierung, falls die App breiter als nur fuer Testnutzer angeboten wird
- Klare Loeschroutine fuer gespeicherte Tokens und geladene Attachments

## Einfachere Alternativen

### Google Workspace Domain-Wide Delegation

Wenn alle Nutzer zu einer eigenen Google-Workspace-Domain gehoeren, kann ein Service Account mit Domain-Wide Delegation sinnvoll sein. Dann muessen sich einzelne Nutzer nicht separat per OAuth verbinden. Das ist administrativ aufwendiger, aber fuer interne Firmen-Tools oft sauberer.

### Gmail IMAP

Gmail kann auch per IMAP gelesen werden. Fuer normale Google-Konten ist dafuer in der Praxis ebenfalls OAuth noetig; klassische Passwort-Anmeldung ist nicht mehr die empfohlene Variante. IMAP ist brauchbar, wenn bereits eine Mail-Bibliothek vorhanden ist, aber Attachments und Labels sind ueber die Gmail API oft angenehmer zu verarbeiten.

### Manuelle Weiterleitung oder Import-Postfach

Fuer sehr einfache Prozesse kann ein Nutzer E-Mails an ein zentrales Postfach weiterleiten. Die Anwendung liest dann nur dieses eine Postfach. Das ist technisch einfacher, aber schwacher bei Datenschutz, Nutzerkontrolle und Rueckverfolgbarkeit.

### Google Apps Script

Fuer kleine interne Automationen kann Google Apps Script E-Mails lesen und Attachments weiterverarbeiten. Das ist schnell gebaut, aber weniger geeignet, wenn eine eigene oeffentliche Webanwendung mit sauberem Nutzer-Login entstehen soll.

## Dateien

- `index.php`: Projektstartseite und Status
- `oauth_start.php`: startet den Google-OAuth-Flow
- `oauth_callback.php`: verarbeitet Googles Callback
- `emails.php`: listet die letzten E-Mails und Attachments
- `attachment.php`: laedt ein Gmail-Attachment herunter
- `lib/GmailClient.php`: HTTP-Client fuer OAuth und Gmail API