OpenNIT

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

# Google Workspace / Gmail für E-Mail-Versand & Ticket-Abruf (OAuth2)

Diese Anleitung beschreibt, wie ein **Google-Workspace-Postfach (Gmail)** statt
mit klassischem IMAP/SMTP-Passwort über **OAuth2** abgerufen und versendet wird.

Hintergrund: Google hat – wie Microsoft – die einfache Passwort-Anmeldung für
IMAP/SMTP („Less secure apps") abgeschaltet. Für Gmail/Workspace-Postfächer ist
daher OAuth2 erforderlich.

OpenNIT spricht Gmail über **IMAP/SMTP mit XOAUTH2** an:

| Eigenschaft | Wert |
|-------------|------|
| IMAP-Endpunkt | `imap.gmail.com:993` (SSL) |
| SMTP-Endpunkt | `smtp.gmail.com:587` (STARTTLS) |
| Token-Scope | `https://mail.google.com/` |

> **Wichtig:** Anders als bei Microsoft gibt es bei Google **keinen App-only-
> Flow** für Mail (das setzt ein signiertes Service-Account-JWT voraus, das
> OpenNIT bewusst nicht nutzt). Für Google wird daher **immer der delegierte
> Refresh-Token-Flow** verwendet. Den Refresh-Token holt man bequem über den
> **„Verbinden"-Button** in den Einstellungen (Consent-Flow) – kein manuelles
> Kopieren nötig.

---

## Teil 1 – Einrichtung in der Google Cloud Console

### 1.1 Projekt & Gmail-API

1. [Google Cloud Console](https://console.cloud.google.com) öffnen und ein
   Projekt anlegen (oder ein bestehendes wählen).
2. **APIs & Dienste → Bibliothek** → **Gmail API** suchen → **Aktivieren**.

### 1.2 OAuth-Zustimmungsbildschirm

1. **APIs & Dienste → OAuth-Zustimmungsbildschirm**.
2. Nutzertyp **Intern** (empfohlen, nur eigene Workspace-Organisation) wählen.
3. App-Name, Support-E-Mail und Entwickler-Kontakt ausfüllen.
4. **Scope** hinzufügen: `https://mail.google.com/`.
5. Speichern.

### 1.3 OAuth-Client-ID erstellen

1. **APIs & Dienste → Anmeldedaten → Anmeldedaten erstellen → OAuth-Client-ID**.
2. Anwendungstyp **Webanwendung**.
3. Unter **Autorisierte Redirect-URIs** exakt die URI eintragen, die OpenNIT
   in den Einstellungen anzeigt, z. B.:

   ```
   https://<deine-opennit-domain>/admin/settings/mail-oauth/callback
   ```

4. **Erstellen** → **Client-ID** und **Client-Secret** notieren.

> Die Redirect-URI muss **zeichengenau** übereinstimmen (inkl. https und ohne
> abschließenden Slash), sonst lehnt Google den Consent mit `redirect_uri_mismatch`
> ab. OpenNIT leitet sie aus `app.url` (runtime/app-Konfiguration) ab.

---

## Teil 2 – Einrichtung in OpenNIT

1. Zielbereich öffnen:
   - **Globaler Versand:** *Einstellungen → E-Mail*
   - **Ticket-Postfach:** *Administration → Ticketsystem → Einstellungen*
2. **Verbindungsverfahren** auf *Microsoft 365 – IMAP/SMTP (XOAUTH2)* stellen
   (das XOAUTH2-Verfahren wird für Google wiederverwendet).
3. Im OAuth-Block als **Anbieter** → **Google Workspace (Gmail)** wählen.
   Das Tenant-Feld entfällt dann automatisch.
4. Eintragen:
   - **Anwendungs-(Client-)ID** (aus 1.3)
   - **Client-Secret** (aus 1.3)
   - **Postfach (E-Mail)** – das Gmail-/Workspace-Postfach, z. B. `helpdesk@firma.de`
5. **Speichern**.
6. Auf **„Mit Google verbinden"** klicken. Es folgt der Google-Consent-Dialog;
   nach Zustimmung kehrt der Browser zurück und OpenNIT speichert den
   **Refresh-Token** (verschlüsselt). Ein grüner Haken „Refresh-Token
   gespeichert" bestätigt den Erfolg.
7. *(Ticket-Postfach)* **Abruf testen** / **Versand testen** klicken.

Client-Secret und Refresh-Token werden mit dem `APP_KEY` **verschlüsselt** in
`config/runtime.php` abgelegt (AES-256-GCM).

---

## Teil 3 – Cron / Betrieb

Am Cron-Setup ändert sich **nichts**. Der Scheduler bzw. die Legacy-Skripte
erkennen den Anbieter automatisch:

```
* * * * * /usr/bin/php /pfad/zu/bin/scheduler.php >> /pfad/zu/storage/logs/scheduler.log 2>&1
```

OAuth-Access-Tokens werden in `storage/cache/m365-tokens/` zwischengespeichert
und automatisch über den gespeicherten Refresh-Token erneuert.

### Status prüfen

Unter **Administration → System-Health** gibt es einen Live-Check „E-Mail /
OAuth": Er prüft Vollständigkeit der Konfiguration und holt ein echtes Token –
so erkennt man sofort, ob die Verbindung funktioniert.

---

## Fehlerbehebung

| Meldung / Symptom | Ursache & Lösung |
|-------------------|------------------|
| `redirect_uri_mismatch` | Redirect-URI in der Cloud Console stimmt nicht exakt mit der in OpenNIT angezeigten überein (https, Domain, kein Slash). |
| Kein Refresh-Token erhalten | Zugriff wurde bereits zuvor erteilt. Im Google-Konto unter *Sicherheit → Drittanbieter-Apps* den Zugriff entfernen und erneut „Verbinden". OpenNIT erzwingt bereits `prompt=consent`. |
| `invalid_client` | Client-ID/Secret falsch oder Projekt deaktiviert. |
| IMAP/SMTP `AUTHENTICATIONFAILED` | Gmail-API nicht aktiviert, Scope `https://mail.google.com/` nicht erteilt, oder IMAP im Postfach deaktiviert (Gmail → Einstellungen → Weiterleitung/POP/IMAP). |
| Tokens werden ständig neu geholt | `storage/cache/` nicht beschreibbar. Schreibrechte prüfen. |

Bei tieferer Analyse hilft das Webserver-Error-Log (`error_log`).