Gmail OAuth-Authentifizierung einrichten

Diese Anleitung führt Sie durch die Erstellung einer Google Cloud-Anwendung für die OAuth-Authentifizierung mit Gmail. OAuth bietet eine sicherere Möglichkeit, auf Ihr Gmail-Konto zuzugreifen als die traditionelle Passwort-Authentifizierung.

Voraussetzungen

• Ein Google-Konto (persönlich oder Google Workspace)
• Zugang zur Google Cloud Console
• Ihre Perfex-CRM-Installations-URL (für Redirect-URI-Konfiguration)

Schritt-für-Schritt-Setup

Schritt 1: Google Cloud-Projekt erstellen

1. Gehen Sie zur Google Cloud Console
2. Klicken Sie auf die Projekt-Dropdown-Liste oben auf der Seite
3. Klicken Sie auf "New Project"
4. Geben Sie einen Projektnamen ein (z. B. "Perfex Mailbox OAuth")
5. Klicken Sie auf "Create"
6. Warten Sie auf die Projekterstellung und wählen Sie es aus

Schritt 2: Gmail API aktivieren

1. Navigieren Sie in der Google Cloud Console zu "APIs & Services" > "Library"
2. Suchen Sie nach "Gmail API"
3. Klicken Sie auf "Gmail API" in den Ergebnissen
4. Klicken Sie auf "Enable"
5. Warten Sie auf die API-Aktivierung

Schritt 3: OAuth-Zustimmungsbildschirm konfigurieren

1. Navigieren Sie zu "APIs & Services" > "OAuth consent screen"
2. Wählen Sie "External" als Benutzertyp (außer Sie haben ein Google Workspace-Konto, dann können Sie "Internal" wählen)
3. Klicken Sie auf "Create"
4. Füllen Sie die erforderlichen Informationen aus:
   • App name: Geben Sie Ihren Anwendungsnamen ein (z. B. "Perfex CRM Mailbox")
   • User support email: Ihre E-Mail-Adresse
   • Developer contact information: Ihre E-Mail-Adresse
5. Klicken Sie auf "Save and Continue"
6. Klicken Sie auf der Seite "Scopes" auf "Add or Remove Scopes"
7. Fügen Sie die folgenden Scopes hinzu:
   • https://www.googleapis.com/auth/gmail.readonly
   • https://www.googleapis.com/auth/gmail.send
   • https://www.googleapis.com/auth/gmail.modify
8. Klicken Sie auf "Update", dann "Save and Continue"
9. Auf der Seite "Test users" (bei Verwendung von External App-Typ):
   • Fügen Sie Ihre Gmail-Adresse als Testbenutzer hinzu
   • Klicken Sie auf "Save and Continue"
10. Überprüfen Sie und klicken Sie auf "Back to Dashboard"

Schritt 4: OAuth 2.0-Anmeldedaten erstellen

1. Navigieren Sie zu "APIs & Services" > "Credentials"
2. Klicken Sie auf "Create Credentials" > "OAuth client ID"
3. Wählen Sie "Web application" als Anwendungstyp
4. Geben Sie einen Namen für Ihren OAuth-Client ein (z. B. "Perfex Mailbox Client")
5. Unter "Authorized redirect URIs" klicken Sie auf "Add URI"
6. Fügen Sie Ihre Redirect-URI im Format hinzu:

https://your-domain.com/admin/mailbox/oauth/callback?provider=gmail

Ersetzen Sie your-domain.com durch Ihre tatsächliche Perfex-CRM-Domain.

7. Klicken Sie auf "Create"
8. WICHTIG: Kopieren und speichern Sie beide:
   • Client ID (Sie werden diese benötigen)
   • Client Secret (Sie werden diese benötigen - klicken Sie auf "Show" um sie anzuzeigen)

Schritt 5: In Perfex CRM konfigurieren

1. Gehen Sie zu Ihrem Perfex-CRM-Admin-Bereich
2. Navigieren Sie zu Mailbox > Configuration
3. Wählen Sie "OAuth2" als Authentifizierungsmethode
4. Wählen Sie "Gmail" als Anbieter
5. Geben Sie Ihre Client ID in das Feld "Gmail Client ID" ein
6. Geben Sie Ihr Client Secret in das Feld "Gmail Client Secret" ein
7. Klicken Sie auf "Save Configuration"
8. Klicken Sie auf die Schaltfläche "Connect Gmail"
9. Autorisieren Sie die Anwendung im Google-Popup-Fenster
10. Sie sollten eine Erfolgsmeldung zur Bestätigung der Verbindung sehen

Wichtige Einschränkungen und Überlegungen

Google Test App-Einschränkungen

These limitations are imposed by Google, not by our software.

1. Token-Ablauf (7 Tage) - Unverifizierte Apps (Apps im Testmodus) haben OAuth-Tokens, die nach 7 Tagen ablaufen. Nach 7 Tagen müssen Benutzer die Verbindung erneut autorisieren. Dies ist eine Google-Sicherheitsrichtlinie für unverifizierte Anwendungen.

2. Testbenutzer-Einschränkungen - Nur Benutzer, die zur "Test users"-Liste hinzugefügt wurden, können die OAuth-App verwenden. Maximal 100 Testbenutzer erlaubt. Diese Einschränkung gilt, bis die App verifiziert und veröffentlicht ist.

3. App-Verifizierungsprozess - Um den 7-Tage-Token-Ablauf zu entfernen, müssen Sie Ihre App zur Google-Verifizierung einreichen. Die Verifizierung kann mehrere Wochen dauern (typischerweise 4-8 Wochen). Google prüft Ihre App auf Sicherheit und Compliance.

App-Verifizierung und Veröffentlichung

Um Einschränkungen zu entfernen:

1. Zur Verifizierung einreichen

   • Gehen Sie zu "OAuth consent screen" in der Google Cloud Console
   • Klicken Sie auf die Schaltfläche "PUBLISH APP"
   • Füllen Sie das Verifizierungsformular aus mit:
     • App-Zweck und Funktionalität
     • Datenschutzrichtlinien-URL
     • Nutzungsbedingungen-URL
     • Video-Demonstration (optional, aber empfohlen)
   • Reichen Sie zur Überprüfung ein

2. Verifizierungszeitrahmen

   • Erste Überprüfung: 1-2 Wochen
   • Zusätzliche Informationsanfragen: Variabel (wenn Google Klärung benötigt)
   • Endgültige Genehmigung: 4-8 Wochen insgesamt (typisch)

3. Nach der Verifizierung

   • Tokens laufen nicht mehr nach 7 Tagen ab
   • Keine Testbenutzer-Einschränkungen
   • App kann von jedem Gmail-Benutzer verwendet werden

Produktion vs. Test

• Testmodus: Schnelle Einrichtung, aber Tokens laufen alle 7 Tage ab
• Produktionsmodus: Erfordert Verifizierung, aber Tokens laufen nicht ab
• Die Wahl liegt bei Ihnen - unsere Software funktioniert mit beiden Modi

Token-Aktualisierung

Unser Modul behandelt die Token-Aktualisierung automatisch, wenn möglich. Allerdings:

• Unverifizierte Apps: Tokens laufen nach 7 Tagen ab und erfordern manuelle Re-Autorisierung
• Verifizierte Apps: Tokens werden automatisch ohne Benutzerintervention aktualisiert

Hinweise

• Die Redirect-URI muss exakt mit dem übereinstimmen, was Sie in der Google Cloud Console konfiguriert haben
• Bewahren Sie Ihr Client Secret sicher auf - teilen Sie es niemals öffentlich
• Wenn Sie Ihre Domain ändern, aktualisieren Sie die Redirect-URI in der Google Cloud Console
• Der OAuth-Flow wird vollständig von Google behandelt - unser Modul initiiert und empfängt nur den Callback

Fehlerbehebung

"Redirect URI mismatch"-Fehler:

• Stellen Sie sicher, dass die Redirect-URI in der Google Cloud Console exakt übereinstimmt: https://your-domain.com/admin/mailbox/oauth/callback?provider=gmail
• Prüfen Sie auf nachgestellte Schrägstriche oder HTTP vs. HTTPS-Abweichungen

"Token expired" nach 7 Tagen:

• Dies ist bei unverifizierten Apps erwartet (Google-Richtlinie)
• Autorisieren Sie erneut, indem Sie erneut auf "Connect Gmail" klicken
• Um dies zu vermeiden, reichen Sie Ihre App zur Google-Verifizierung ein

"Access blocked"-Fehler:

• Stellen Sie sicher, dass Ihre E-Mail zur "Test users"-Liste hinzugefügt ist (bei unverifizierten Apps)
• Prüfen Sie, ob die Gmail API in Ihrem Google Cloud-Projekt aktiviert ist

Gmail API nicht gefunden:

• Stellen Sie sicher, dass Sie sich im richtigen Google Cloud-Projekt befinden
• Versuchen Sie, in der API-Bibliothek nach "Gmail" zu suchen

Zusätzliche Ressourcen

• Google OAuth 2.0 Documentation
• Gmail API Documentation
• Google Cloud Console

info

Der 7-Tage-Token-Ablauf und die Testbenutzer-Einschränkungen sind Google-Sicherheitsrichtlinien für unverifizierte Anwendungen. Diese Einschränkungen werden nicht von unserer Software auferlegt. Sobald Ihre App von Google verifiziert wurde, werden diese Einschränkungen aufgehoben.