oAuth

1 Grundlegendes

Microsoft (und die Unternehmenslösung von Google, die im deutschsprachigem Raum eine untergeordnete Rolle spielt) haben für E-Mailkonten den Zugriff über Benutzername und Passwort deaktiviert, und fordern den Zugriff über OAuth. Deshalb ändert sich der Prozess für das Einrichten von E-Mailkonten, wenn die E-Mailkonten von Microsoft bereitgestellt werden. Bekannte Produktnamen dafür sind Microsoft 365, Office 365, Exchange Cloud oder Microsoft Azure.

Grober Ablauf: Bei OAuth wird zuerst die fremde Applikation (in unserem Fall: cmxOrganize) beim Betreiber der E-Mailkonten (Microsoft) registriert und die Registrierungsinformationen in cmxOrganize eingetragen. Bei der Einrichtung der einzelnen E-Mailkonten wird kein Passwort in das E-Mailkonto eingetragen, sondern es wird ein Login-Prozess bei Microsoft gestartet. Dort wird auf die gewohnte Art eingeloggt, mit dem Firmenzugang und falls eingerichtet, auch mit Smartcard, 2-Faktor-Authentifizierung und/oder mit Passkeys. Nach diesem Login-Prozess erhält cmxOrganize einen eindeutigen, widerrufbaren und sicheren Zugang zum E-Mailkonto.

Vorteile: Kein Passwort zu verwenden bedeutet in der Regel, dass der Prozess sicherer ist und bspw. gehackte E-Mailkonten deutlich unwahrscheinlicher sind. Zudem kann der Zugriff durch Fremdapplikationen bei Microsoft gesteuert werden und der Benutzer erhält Infos darüber, auf was genau zugegriffen wird. Außerdem sind keine Serverzugangsdaten für die Einrichtung notwendig.

Nachteile: Das Einrichten ist deutlich aufwändiger und fehleranfälliger. Microsoft bietet viele Konfigurationsmöglichkeiten und damit viele Möglichkeiten, dass etwas nicht korrekt funktioniert. Zudem muss die Applikationsregistierung alle zwei Jahre erneuert werden.

2 Registrieren der Applikation bei Microsoft

Dieser Vorgang muss nur einmal pro cmxOrganize-Instanz durchgeführt werden. Es wird Zugriff auf das Microsoft Entra Admin Center benötigt.

Der nötige Ablauf hierfür ist in folgender Anleitung von Microsoft beschrieben:
Folgen Sie der Anleitung dort, zusammen mit den unten stehenden Hinweisen.

Als Anzeigenamen können Sie etwas beliebiges eintragen, wir empfehlen etwa „cmxOrganize“ oder „cmxOrganize <Ihre Organisation>“. Wichtig ist, dass es eindeutig zugeordnet werden kann. Dieser Name wird beim Loginprozess bei der Abfrage der Berechtigungen angezeigt.

Für die Zielgruppe für die Anmeldung müssen Sie die Auswahl treffen, die den Konten erlaubt, sich anzumelden, die in cmxOrganize eingerichtet werden sollen. Typischerweise ist das die erste Option.
Folgen Sie der Anleitung weiter. Beim Hinterlegen der Umleitungs-URL wählen Sie den Plattform-Typ „Web“, und hinterlegen Sie die Umleitungs-URL, die Sie von uns erhalten haben. Diese hat die Form https://<ihre-domain.de>/App%20E-Mailkonto/continue_oauth. Achten Sie auf das https:// am Anfang, das "%20" und dass die Domain inkl. einem eventuellen www. genau mit der übereinstimmt, die bei der Verwendung von cmxOrganize oben in der Adresszeile steht. Achtung: Manche Browser blenden das "www." aus! Klicken Sie zur Sicherheit einmal in die Adresszeile, um den exakten Wert zu erhalten.

Folgen Sie der Anleitung weiter. Beim Hinzufügen von Anmeldeinformationen wird ein Kundengeheimnis (Client Secret) benötigt. Legen Sie die Laufzeit am besten auf den Maximalwert (24 Monate) fest. Nach Ablauf dieser Zeit müssen Sie das Kundengeheimnis neu generieren und in cmxOrganize eintragen. Wichtig: Es wird der Wert des Schlüssels benötigt (nicht die ID), diesen müssen Sie kopieren/notieren, sobald Sie ihn sehen.

Die Registrierung im Azure-Portal ist damit abgeschlossen. Für die Einrichtung in cmxOrganize benötigen Sie den Wert des geheimen Schlüssels, die Anwendungs-ID (Client) und die Verzeichnis-ID (Mandant).

Navigieren Sie in cmxOrganize auf die Schnittstellen (Suchbegriff „Schnittstellen“ in die Suchleiste oben eingeben) und erstellen Sie eine Schnittstelle vom Typ „Azure“. Im Feld Benutzernamen tragen Sie die Anwendungs-ID (Client) ein. Ins Feld Passwort kommt der Wert des geheimen Schlüssels.
Wenn nötig, fügen Sie die Applikation Einstellungen hinzu. Öffnen Sie dann die Applikation Einstellungen und fügen Sie die Einstellung „TenantID“ hinzu. Dort tragen Sie die Verzeichnis-ID (Mandant) ein.

Damit ist die Anwendungsregistrierung abgeschlossen und Sie können mit dem Einrichten des ersten E-Mailkontos beginnen.

Wichtiger Konfigurationshinweis:
Das SMTP-AUTH-Protokoll muss aktiviert sein, damit der Mailversand funktionieren kann. Mehr Information hierzu erhalten Sie bei Microsoft unter learn.microsoft.com/en-us/exchange/clients-and-mobile-in-exchange-online/authenticated-client-smtp-submission.

3 Einrichten der E-Mailkonten

Dieser Vorgang muss für jedes E-Mailkonto ausgeführt werden.

  1. Navigieren Sie zu den E-Mailkonten, indem Sie oben in die Suchleiste „E-Mailkonten“ eingeben.
  2. Erstellen Sie ein neues E-Mailkonto. Im grünen Feld sollte ein Button erscheinen, mit dem Sie die Verwendung von OAuth für dieses E-Mailkonto aktivieren.
  3. Tragen Sie den/die zuzuweisende Mitarbeiter*in oder Geschäftsstelle bei Kontakt und die zu verwendende E-Mailadresse bei E-Mailadresse ein. Bei Benutzername muss in der Regel ebenfalls Ihre E-Mailadresse eingetragen sein. Für weitere Informationen können Sie hier die normale Anleitung zum Einrichten von E-Mailkonten zu Rate ziehen.
  4. Nun sollte ein Button erscheinen, mit dem Sie den Loginprozess bei Microsoft starten können. Melden Sie sich dabei wie üblich mit Ihren Zugangsdaten an, und bestätigen Sie den Zugriff durch cmxOrganize.
  5. Nun sollten Sie zurück bei cmxOrganize sein. Das System hat im Hintergrund den Zugang fertig eingerichtet und versucht, eine Testmail zu versenden. Ihnen wird eine Meldung angezeigt, ob der Vorgang erfolgreich war. Falls Fehler aufgetreten sind, kontaktieren sie den den cmxOrganize-Keyuser, Ihren IT-Admin oder den cmxKonzepte-Support.
Falls Sie nach dem Einrichten eines E-Mailkontos auf demselbem PC weitere E-Mailkonten einrichten möchten, müssen Sie sich vorab bei Microsoft im Browser wieder abmelden. Ansonsten wird der Loginprozess ohne eine Möglichkeit, diesen zu unterbrechen, komplett mit dem vorherigen Konto durchgeführt.

4 Erneuern des Applikationsschlüssels

Dieser Vorgang muss nach Ablauf des Kundengeheimnisses, mindestens alle zwei Jahre, einmal pro cmxOrganize-Instanz ausgeführt werden.

Da der geheime Clientschlüssel eine maximale Laufzeit von 2 Jahren hat, muss dieser nach Ablauf (oder optimalerweise kurz zuvor) erneuert werden. Gehen Sie wie folgt vor:

  1. Kurz vor dem Ablauf des alten Schlüssels, navigieren Sie mit dem Administrator-Konto im Entra Admin Center zu Identität → Anwendungen → App-Registrierungen, und wählen Sie dort die cmxOrganize-Registrierung aus.
  2. Wechseln Sie zu Zertifikate & Geheimnisse → Kundengeheimnisse
  3. Erstellen Sie dort, wie beim initialen Registrieren der Applikation, ein neues Kundengeheimnis und notieren Sie den Wert des geheimen Schlüssels, die Anwendungs-ID (Client) und die Verzeichnis-ID (Mandant) (Wobei die letzten beiden Werte die gleichen sein sollten wie beim alten Kundengeheimnis).
  4. Öffnen Sie cmxOrganize, navigieren Sie zu Schnittstellen und öffnen dort die bestehende „Azure“-Schnittstelle.
  5. Tragen Sie dort, ebenfalls wie bei der initialen Registierung, die Werte ein: die Anwendungs-ID (Client) in das Feld Benutzername, den Wert des geheimen Schlüssels in das Passwortfeld, und die Verzeichnis-ID (Mandant) in die Einstellung TenantID (dafür Applikation Einstellungen öffnen). Falls die Verzeichnis-ID oder die Tenant-ID dieselben sind wie die zuvor verwendeten, müssen diese nicht aktualisiert werden.
  6. Testen Sie den Mailversand, indem Sie zu einem mit OAuth eingerichteten E-Mailkonto navigieren und dort die Methode „E-Mailkonto testen“ ausführen.
  7. Nach dem erfolgreichen Test können Sie das alte Kundengeheimnis in im Microsoft Admin Center löschen.