Verbindung zu Mail über OAuth für Google Mailboxen

Frage:
Wie verwende ich die Moderne Authentifizierung bzw. OAuth mit Connect to Mail und einem Google-Konto?

Lösung:
Um Connect to Mail mit Google-Konten über OAuth zu nutzen, benötigen Sie für jeden Ordner, den Sie mit Connect to Mail lesen möchten, eine Google OAuth 2.0 Client ID, die auch das jeweilige Client Secret enthält. Wir führen Sie mit diesen KBA durch die notwendigen Schritte:

1. Gehen Sie bitte zunächst auf https://console.cloud.google.com/apis

2. Legen Sie dort ein Projekt für OAuth in Verbindung mit DocuWare an.


3. Sobald das Projekt angelegt ist, klicken Sie auf "Enable APIs and Services", wählen die Gmail-API aus und aktivieren sie.

⇓

⇓

4. Wechseln Sie zum "OAuth-Zustimmungsbildschirm" und erstellen Sie einen OAuth-Zustimmungsbildschirm des User Typs External und klicken Sie auf Erstellen.


5. Im nächsten Konfigurationsbildschirm können Sie die App-Informationen eingeben. In unserem Fall können Sie die meisten Informationen hier leer lassen, da außer Ihnen niemand diese App nutzen wird.

Wichtig: Am Ende der App-Informationsseite fragt Google nach der E-Mail-Adresse des Entwicklerkontakts. Dies bezieht sich nicht auf DocuWare als Entwickler von Connect to Mail, sondern auf den Ersteller dieser App, also auf Sie. Tragen Sie hier also bitte Ihre E-Mail-Adresse ein, auch weil der Empfänger dieser Adresse informiert werden soll, wenn es Probleme mit dem von Ihnen erstellten Projekt und dieser Google OAuth-App gibt.

Klicken Sie auf Speichern und Weiter.


6. Auf der zweiten Seite, "Scopes", klicken Sie auf "Scopes Hinzufügen oder entfernen" und wählen Sie "openid" und die "Gmail API" mit den folgenden Berechtigungen: Lesen, Verfassen, Senden und dauerhaftes Löschen aller Ihrer E-Mails aus Google Mail.

Dies ist das Ergebnis, wenn Sie auf Aktualisieren klicken:


7. Fügen Sie auf der Registerkarte Test Users alle E-Mail-Adressen hinzu, die Sie mit dieser OAuth-App abfragen möchten. Klicken Sie auf Speichern und Weiter.

Zurück in der Übersicht gibt Ihnen Google die Möglichkeit, die OAuth Consent Screen App zu veröffentlichen. Wir raten von diesem Schritt ab, da Google die App dann überprüfen möchte. Da es sich nur um eine Verbindung zu einem Postfach handelt, die zum Abrufen von E-Mails hergestellt werden soll, und keine API für andere Aktivitäten innerhalb des Postfachs verwendet wird, halten wir diesen Schritt für zu zeitaufwändig. Wir empfehlen, die App im Status "Testing" zu verwenden.

8. Gehen Sie nun zu "Credentials" und klicken Sie auf Create Credentials. Wählen Sie die OAuth Client ID aus der Liste aus.


9. Der Anwendungstyp für die OAuth Client ID ist "Web Application". Wählen Sie nun einen aussagekräftigen Namen (wir empfehlen eine Kombination aus der E-Mail-Adresse und dem zu verbindenden Ordner, z.B. Rechnungen-Süd-West-Posteingang) und fügen Sie die Redirect URI hinzu.

Wichtig: Die Redirect URI ist, wie bei Microsoft OAuth, Ihre DocuWare Cloud URL + der Zusatz "/DocuWare/Settings?link=MailCapture".
So geht's: https://your-dw-cloud-name.docuware.cloud/DocuWare/Settings?link=MailCapture

10. Notieren Sie abschließend die Client ID, das Client Secret und die Redirect URI für die Konfiguration in DocuWare. Die Redirect URI muss in Google und DocuWare identisch geschrieben sein, sonst kommt es zu einem Mismatch-Fehler. Wir empfehlen den Download der JSON-Datei. Diese können Sie in der DocuWare-Konfiguration speichern und alle Einstellungen von Google werden dann automatisch in die DocuWare-Konfiguration übernommen.

Auf der DocuWare-Konfigurationsseite wählen Sie "Mail-Dienste", klicken auf "Neuer Mail-Dienst" und wählen IMAP. Benennen Sie den neuen Maildienst so, wie Sie die OAuth-Client-ID in Schritt 9. benannt haben, damit Sie immer wissen, welcher Maildienst zu welcher Google-Client-ID gehört.

12. Klicken Sie im neuen Fenster auf "Weitere Optionen" und wählen Sie "IMAP OAuth-Authentifizierung verwenden". Stellen Sie sicher, dass dort Google und nicht Andere ausgewählt ist.

13. Sie können nun die JSON-Datei von Google hochladen und die Konfiguration ist abgeschlossen. Sie können die Daten auch manuell hochladen, aber wir empfehlen dies nicht, da es normalerweise zu mehr Fehlern führt.

Wenn Sie den Dienst manuell konfigurieren möchten, benötigen Sie diese Werte zusätzlich zu den in Schritt 10 notierten Werten:

14. Verbinden Sie nun Ihr Google-Postfach mit Connect to Mail. Öffnen Sie dazu auf der DocuWare-Konfigurationsseite "Allgemeine E-Mail". Wählen oder erstellen Sie eine neue Speicherkonfiguration und klicken Sie dann auf "Mit E-Mail-Konto verbinden".

15. Im neuen Fenster müssen Sie sich nun einmalig am Google-Konto anmelden. Es ist möglich, dass Google eine Sicherheitsmeldung wie diese anzeigt:

Diese Meldung erscheint aufgrund der in Schritt 5 gemachten Eingaben. Ignorieren Sie diese Meldung und klicken Sie auf Weiter.

Im nächsten Fenster müssen Sie DocuWare die Rechte für den Zugriff auf das Postfach erteilen. Klicken Sie auf Weiter.

Wenn Sie nun in der DocuWare Connect to Mail Konfiguration Ihre Google Labels sehen, ist die Konfiguration abgeschlossen.

Wichtiger Hinweis:
Leider erlaubt es Google nicht, dass Sie sich mit einem Set aus Client ID + Client Secret mehrfach an Ihrem Postfach anmelden, um verschiedene Ordner zu überwachen. Dazu müssen Sie auf der Google API-Seite zu Ihrem DocuWare-Projekt wechseln und unter Credentials neue OAuth 2.0 Client ID Credentials erstellen. Um Verwechslungen zu vermeiden, empfehlen wir, wie in Schritt 9 erwähnt, diese IDs nach den Ordnern zu benennen, die Sie in DocuWare anbinden wollen.
Legen Sie dann in DocuWare einen neuen Mailservice an, am besten ebenfalls mit dem Ordnernamen, und laden Sie dort die neue JSON-Datei hoch.

Weitere Informationen zu OAuth:
https://knowledgecenter.docuware.com/docs/mail-services?highlight=oauth
https://developers.google.com/identity/protocols/oauth2/javascript-implicit-flow
https://developers.google.com/workspace/guides/configure-oauth-consent