Zum Hauptinhalt springen

Outlook/Microsoft 365 OAuth-Authentifizierung einrichten

Diese Anleitung führt Sie durch die Erstellung einer Microsoft Azure-Anwendung für die OAuth-Authentifizierung mit Outlook/Microsoft 365. OAuth bietet eine sicherere Möglichkeit, auf Ihr Outlook-Konto zuzugreifen als die traditionelle Passwort-Authentifizierung.

Voraussetzungen​

  • Ein Microsoft-Konto (persönlich oder Microsoft 365/Office 365)
  • Zugang zum Azure Portal
  • Ihre Perfex-CRM-Installations-URL (für Redirect-URI-Konfiguration)
info

Für Microsoft-365-Organisationen kann eine Admin-Genehmigung erforderlich sein.

Schritt-für-Schritt-Setup​

Schritt 1: Anwendung im Azure Portal registrieren​

  1. Gehen Sie zum Azure Portal
  2. Melden Sie sich mit Ihrem Microsoft-Konto an
  3. Navigieren Sie zu "Azure Active Directory" (oder suchen Sie danach)
  4. Klicken Sie auf "App registrations" im linken Menü
  5. Klicken Sie auf "+ New registration"
  6. Füllen Sie die Anwendungsdetails aus:
    • Name: Geben Sie einen Namen ein (z. B. "Perfex CRM Mailbox")
    • Supported account types: Wählen Sie "Accounts in any organizational directory and personal Microsoft accounts" für maximale Kompatibilität
    • Redirect URI:
      • Platform: Web
      • URI: https://your-domain.com/admin/mailbox/oauth/callback?provider=outlook
      • Ersetzen Sie your-domain.com durch Ihre tatsächliche Perfex-CRM-Domain
  7. Klicken Sie auf "Register"

Schritt 2: API-Berechtigungen konfigurieren​

  1. Klicken Sie in Ihrer App-Registrierung auf "API permissions" im linken Menü
  2. Klicken Sie auf "+ Add a permission"
  3. Wählen Sie "Microsoft Graph"
  4. Wählen Sie "Delegated permissions"
  5. Fügen Sie die folgenden Berechtigungen hinzu:
    • Mail.Read - E-Mail in allen Postfächern lesen
    • Mail.ReadWrite - E-Mail in allen Postfächern lesen und schreiben
    • Mail.Send - E-Mail als Benutzer senden
    • offline_access - Zugriff auf Daten aufrechterhalten (für Token-Aktualisierung)
  6. Klicken Sie auf "Add permissions"
  7. WICHTIG: Klicken Sie auf "Grant admin consent for [Your Organization]", falls diese Schaltfläche angezeigt wird
warnung

Dies ist für Organisationskonten erforderlich. Dies erfordert Admin-Berechtigungen.

Schritt 3: Client Secret erstellen​

  1. Klicken Sie in Ihrer App-Registrierung auf "Certificates & secrets" im linken Menü
  2. Klicken Sie auf "+ New client secret"
  3. Geben Sie eine Beschreibung ein (z. B. "Perfex Mailbox Secret")
  4. Wählen Sie einen Ablaufzeitraum: 24 months (empfohlen für Produktion)
  5. Klicken Sie auf "Add"
  6. WICHTIG: Kopieren Sie den Value sofort (Sie werden ihn nicht wieder sehen können) - dies ist Ihr Client Secret

Schritt 4: Application (Client) ID abrufen​

  1. Gehen Sie in Ihrer App-Registrierung zu "Overview"
  2. Kopieren Sie die Application (client) ID - dies ist Ihre Client ID

Schritt 5: Redirect URI verifizieren​

  1. Klicken Sie in Ihrer App-Registrierung auf "Authentication" im linken Menü
  2. Prüfen Sie unter "Redirect URIs", ob Ihre Redirect-URI aufgeführt ist:
https://your-domain.com/admin/mailbox/oauth/callback?provider=outlook
  1. Falls nicht vorhanden, klicken Sie auf "+ Add a platform" > "Web" und fügen Sie sie hinzu
  2. Unter "Implicit grant and hybrid flows" stellen Sie sicher, dass "Access tokens" aktiviert ist (falls verfügbar)
  3. Klicken Sie auf "Save"

Schritt 6: 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 "Outlook" als Anbieter
  5. Geben Sie Ihre Client ID (Application ID aus Azure) ein
  6. Geben Sie Ihr Client Secret (den kopierten Secret-Wert) ein
  7. Für Microsoft 365-Organisationen: Geben Sie Ihre Tenant ID ein (gefunden in Azure AD > Overview). Für persönliche Microsoft-Konten leer lassen.
  8. Klicken Sie auf "Save Configuration"
  9. Klicken Sie auf die Schaltfläche "Connect Outlook"
  10. Autorisieren Sie die Anwendung im Microsoft-Popup-Fenster
  11. Sie sollten eine Erfolgsmeldung zur Bestätigung der Verbindung sehen

Wichtige Einschränkungen und Überlegungen​

Microsoft Azure App-Einschränkungen​

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

  1. Admin-Zustimmungsanforderungen - Organisationskonten (Microsoft 365/Office 365) erfordern Admin-Zustimmung für bestimmte Berechtigungen. Der Admin muss die App genehmigen, bevor Benutzer sie nutzen können.

  2. Kontotyp-Einschränkungen:

    • "Accounts in this organizational directory only" - Nur Benutzer in Ihrer Organisation
    • "Accounts in any organizational directory" - Benutzer aus beliebigen Microsoft 365-Organisationen
    • "Accounts in any organizational directory and personal Microsoft accounts" - Maximale Kompatibilität
    • "Personal Microsoft accounts only" - Nur persönliche @outlook.com-, @hotmail.com-Konten

  3. Tenant ID-Anforderungen - Organisationskonten erfordern Tenant ID für ordnungsgemäße Authentifizierung. Persönliche Konten können es leer lassen.

App-Verifizierung und Veröffentlichung​

  • Unverifizierte Apps können sofort für persönliche Konten verwendet werden, zeigen aber möglicherweise Warnmeldungen für Benutzer.
  • Verifizierte Apps erfordern Einreichung beim Microsoft App Store (optional) und bieten eine bessere Benutzererfahrung (keine Warnungen).
  • Admin-Zustimmungs-Workflow - Für Organisationskonten muss der Admin zustimmen. Der Admin sieht, welche Berechtigungen die App anfordert.

Token-Aktualisierung​

Unser Modul behandelt die Token-Aktualisierung automatisch:

  • Refresh-Tokens: Automatisch mit offline_access-Berechtigung erhalten
  • Token-Ablauf: Typischerweise 1 Stunde für Access-Tokens, 90 Tage für Refresh-Tokens
  • Automatische Aktualisierung: Unser Modul aktualisiert Tokens automatisch vor Ablauf

Multi-Tenant vs. Single-Tenant​

  • Multi-Tenant: App kann von jedem Microsoft-Konto verwendet werden (erfordert Admin-Zustimmung pro Organisation)
  • Single-Tenant: App kann nur innerhalb Ihrer Organisation verwendet werden

Hinweise​

  • Die Redirect-URI muss exakt mit dem übereinstimmen, was Sie im Azure Portal konfiguriert haben
  • Bewahren Sie Ihr Client Secret sicher auf - teilen Sie es niemals öffentlich
  • Wenn Sie Ihre Domain ändern, aktualisieren Sie die Redirect-URI im Azure Portal
  • Für Organisationskonten stellen Sie sicher, dass die Admin-Zustimmung erteilt wurde
  • Tenant ID wird nur für Microsoft 365/Office 365-Konten benötigt
  • Der OAuth-Flow wird vollständig von Microsoft behandelt - unser Modul initiiert und empfängt nur den Callback

Fehlerbehebung​

"AADSTS50011: Redirect URI mismatch"-Fehler:

  • Stellen Sie sicher, dass die Redirect-URI im Azure Portal exakt übereinstimmt: https://your-domain.com/admin/mailbox/oauth/callback?provider=outlook
  • Prüfen Sie auf nachgestellte Schrägstriche oder HTTP vs. HTTPS-Abweichungen
  • Verifizieren Sie, dass die URI unter dem Plattformtyp "Web" aufgeführt ist

"Admin consent required"-Fehler:

  • Dies ist bei Organisationskonten erwartet (Microsoft-Richtlinie)
  • Kontaktieren Sie Ihren Microsoft 365-Administrator zur Zustimmung
  • Admin kann die Zustimmung im Azure Portal > Enterprise applications erteilen

"Invalid client secret"-Fehler:

  • Client Secrets laufen ab - erstellen Sie einen neuen im Azure Portal
  • Stellen Sie sicher, dass Sie den "Value" kopiert haben (nicht die Secret ID)
  • Prüfen Sie, ob das Secret nicht abgelaufen ist

"AADSTS700016: Application not found"-Fehler:

  • Verifizieren Sie, ob die Client ID korrekt ist
  • Stellen Sie sicher, dass Sie die Application (client) ID verwenden, nicht die Object ID
  • Prüfen Sie, ob die App-Registrierung im richtigen Azure AD-Tenant existiert

"Token refresh failed"-Fehler:

  • Stellen Sie sicher, dass die Berechtigung offline_access erteilt wurde
  • Verifizieren Sie, dass die Admin-Zustimmung erteilt wurde (für Organisationskonten)
  • Prüfen Sie, ob das Client Secret nicht abgelaufen ist

Zusätzliche Ressourcen​

info

Admin-Zustimmungsanforderungen, Kontotyp-Einschränkungen und Token-Richtlinien sind Microsoft-Sicherheitsrichtlinien für Azure-Anwendungen. Diese Einschränkungen werden nicht von unserer Software auferlegt.