EWS OAuth für Mailarchive via MS GraphAPI / OAuth
Führen Sie bitte folgende Schritte für die E-Mail-Konfiguration von Office 365 durch:
- Wählen Sie für Office 365 als Verfahren MS GraphAPI / OAuth aus
- Klicken Sie auf Speichern
- Nach dem Speichern muss über den Button "OAuth Access-Token abrufen" der Abruf durchgeführt werden und die APP bestätigt werden
EWS OAuth für Mailarchive via App Registrierung (Altes Verfahren)
Für Anwender, die die Autorisierung in der Vergangenheit über Microsoft Azure durchgeführt haben, ist wie folgt vorzugehen.
Alternativ kann das Mailkonto in der DOCBOX® auch gelöscht und vereinfacht über die Schritte 1 - 3 (siehe oben) neu angelegt und autorisiert werden.
Anmeldung im Microsoft Azure
Die „Basic Auth“ Authentifizierung von Microsoft wurde in 10/2022 deaktiviert, stattdessen muss eine App in Microsoft Azure registriert werden. Für die Registrierung und Administrierung wird ein Benutzer mit administrativen Rechten im Azure benötigt.
Bevor Sie mit der Konfiguration beginnen, prüfen Sie bitte, ob Microsoft .NET Framework 4.8 oder höher auf dem DOCBOX® Server installiert ist. Sofern dies nicht Fall ist, muss dieses installiert werden.
Anmeldung
Mit dem nachfolgenden Link können Sie sich im Microsoft Azure anmelden.
Weiter zu Microsoft Azure
Azure Active Directory
Nach der erfolgreichen Anmeldung navigieren Sie zum Punkt „Azure Active Directory“ Ihres Unternehmens.
Erstellung einer App-Registrierung
Damit Ihre DOCBOX® zukünftig weiterhin Nachrichten über das Modul Mailarchive abrufen kann, muss im „Azure Active Directory“ eine neue App registriert werden.
App-Registrierung
Navigieren Sie dazu direkt zum Punkt "App-Registrierung" unter "Verwalten".
Neue App anlegen
Damit Sie eine neue App registrieren können, klicken Sie bitte auf "Neue Registrierung".
Bezeichnung der App
Im nächsten Schritt, müssen Sie einen Namen für Ihre App vergeben. Wir empfehlen Ihnen einen eindeutigen Namen z.B. „DOCBOX® Mailarchive“.
Unterstützte Kontotypen
Als „Unterstützte Kontotypen“ geben Sie bitte die Standardeinstellung „Konten in einem beliebigen Organisationsverzeichnis (beliebiges Azure AD-Verzeichnis – mehrinstanzenfähig) an.
Umleitungs-URL
Als Umleitungs-URL geben Sie bitte den Typ „Öffentlicher Client/nativ“ an.
Die Umleitungs-URL fließt als Zeichenkette in die Berechnung des Authentifizierungsschlüssels ein. Daher muss die URL angegeben werden, unabhängig davon, ob ihre DOCBOX® von außen zu erreichen ist oder nicht.
Ein Beispiel für die URL (Inhouse-Variante mit SSL-Zertifikat) sieht wie folgt aus: "https://docbox.aktivweb.de/admin/mailarchive/ews/oauth"
Die einzelnen Einstellungen können Sie aus dem Ihnen bekannten Aufruf (URL) Ihrer DOCBOX® entnehmen:
Beispiellinks DOCBOX® (ab Version 7.3)
"https://docbox.aktivweb.de/" dann lautet die Umleitungs-URL "https://docbox.aktivweb.de/admin/mailarchive/ews/oauth"
"https://192.168.1.123:8080/" dann lautet die Umleitungs-URL "https://192.168.1.123:8080/admin/mailarchive/ews/oauth"
"https://cloud.docbox.eu/" dann lautet die Umleitungs-URL
"https://cloud.docbox.eu/admin/mailarchive/ews/oauth"
Wenn man intern ohne SSL-Zertifikat arbeitet, wird von Microsoft nur localhost unterstützt. Hier ist dann darauf zu achten, dass der Abruf des Tokens über den Server durchzuführen ist.
"http://192.168.1.123:8080/" dann lautet die Umleitungs-URL "http://localhost:8080/admin/mailarchive/ews/oauth"
Beispiellinks DOCBOX® (ab Version 6.8.2)
"https://docbox.aktivweb.de/" dann lautet die Umleitungs-URL "https://docbox.aktivweb.de/docbox.webapp/docbox/admin/controlcenter/ewsoauth.xhtml"
"https://192.168.1.123:8080/" dann lautet die Umleitungs-URL "https://192.168.1.123:8080/docbox.webapp/docbox/admin/controlcenter/ewsoauth.xhtml"
"https://cloud.docbox.eu/" dann lautet die Umleitungs-URL
"https://cloud.docbox.eu/docbox.webapp/docbox/admin/controlcenter/ewsoauth.xhtml"
Wenn man intern ohne SSL-Zertifikat arbeitet, wird von Microsoft nur localhost unterstützt. Hier ist dann darauf zu achten, dass der Abruf des Tokens über den Server durchzuführen ist.
"http://192.168.1.123:8080/" dann lautet die Umleitungs-URL "http://localhost:8080/docbox.webapp/docbox/admin/controlcenter/ewsoauth.xhtml"
Wenn die Umleitungs-URL "http://localhost:8080/docbox.webapp/docbox/admin/controlcenter/ewsoauth.xhtml" lautet, muss in der DOCBOX® auch mit "http://localhost:8080" der Token abgerufen werden.
Bestätigung
Nachdem alle notwendigen Felder ausgefüllt wurden, muss die App mit dem Button "Registrieren" bestätigt werden.
API-Berechtigungen
Nachdem die App erfolgreich registriert wurde, muss die API-Berechtigungen gesetzt und ein Clientschlüssel erstellt werden.
Neue Berechtigung hinzufügen
Innerhalb der API-Berechtigungen muss über "Berechtigung hinzufügen" ein zusätzliches Recht eingefügt werden.
Organisation verwendete APIs
Wechseln Sie dazu in den Reiter "Von meiner Organisation verwendete APIs". Suchen Sie in der Suche nach "Office 365 Exchange Online" und wählen diesen Dienst aus.
Art der Berechtigung
Nach Auswahl des Dienstes muss die Art gewählt werden. Wir verwenden hier "Delegierte Berechtigungen".
Berechtigung auswählen
Wählen Sie bitte unter "EWS" die Berechtigung "EWS.AccessAsUser.All" aus und bestätigen Sie die Berechtigung mit "Berechtigungen hinzufügen".
Administratorzustimmung
Da es sich hierbei um eine Berechtigung mit Administratorzustimmung handelt, muss diese noch zusätzlich bestätigt werden. Dazu muss die soeben eingefügte Berechtigung ausgewählt werden und mit der Funktion "Administratorzustimmung für "ORANGISATION" erteilen" bestätigt werden.
Clientschlüssel
Nachdem die API-Berechtigungen gesetzt wurden, muss noch ein Clientschlüssel angelegt werden.
Verwaltung von Clientschlüssel
Clientschlüssel werden im Bereich "Zertifikate & Geheimnisse" verwaltet.
Neuen geheimen Clientschlüssel anlegen
Ein neuer Clientschlüssel kann mit "Neuer geheimer Clientschlüssel" angelegt werden. In diesem Fenster muss eine Beschreibung vergeben werden. Wir empfehlen hier wieder eine eindeutige Beschreibung wie z.B. "DOCBOX". Zusätzlich muss noch festgelegt werden, wie lange ein solcher Clientschlüssel gültig ist. Hier empfehlen wir das Feld "Gültig bis" auf 24 Monate zu setzen.
Der neue Schlüssel wird mit dem Button "Hinzufügen" in die App eingefügt.
Anzeigen des Clientschlüssels
Nachdem der Clientschlüssel hinzugefügt wurde, wird dieser nur einmal dargestellt. Daher muss der Schüssel direkt nach dem Anlegen kopiert und gesichert werden.
Hinweis: Wird dieser Schüssel nicht direkt nach dem Anlegen kopiert, muss ein neuer Clientschlüssel angelegt werden.
Microsoft Office 365 App in der DOCBOX® hinterlegen
Nachdem nun die App vollständig im Microsoft Azure Portal eingerichtet worden ist, muss die App auch noch in der DOCBOX® hinterlegt werden.
Notwendige Informationen zur Verknüpfung
Damit die DOCBOX® die Nachrichten von Microsoft über OAuth abrufen kann, wird die Anwendungs-ID (Client) und der Wert des geheimen Clientschlüssel der APP benötigt.
Anwendungs-ID (Client) = Client ID in der DOCBOX®
Wert des Geheimschlüssels = Client Secret in der DOCBOX®
Die Anwendungs-ID (Client) wird direkt auf der Übersichtsseite der App in Microsoft Azure angezeigt.
Mailarchive-Einstellungen
Ab Version 7.3
Die Konfigurations-Seite "Micrososft Azure Client konfigurieren" für den "Microsoft Azure Client" finden Sie in der Administration unter "Module -> Mailarchive" bei Exchange Konten.
Ab Version 6.8.2
Die Konfigurations-Seite "Micrososft Azure Client konfigurieren" für den "Microsoft Azure Client" finden Sie in der Administration unter "Integration -> Mailarchive" im Tab "Azure Client".
Hinterlegung der Client-ID und des Schlüssels
Auf der Konfigration-Seite müssen Sie die Client-ID und den Client Secret (Geheimschlüssel in Office 365) hinterlegen und abspeichern.
Anlage eines E-Mail-Kontos
Konfiguration des Kontos ab Version 7.3
EWS E-Mail: EWS E-Mailadresse
Verfahren: Hier haben Sie drei Möglichkeiten den Abruf eines Microsoft OAuth-Kontos einzustellen:
1. EWS / MS OAuth / Access+Refresh Token: Mit dieser Methode klicken Sie auf den Button
"OAuth Access-Token abrufen". Sie werden auf die Seite zur Anmeldung an dem
abzurufendem Konto an Microsoft weitergeleitet. Nach der Anmeldung wird der Token
abgerufen und die Email-Abholung funktioniert. Beachten Sie bitte, dass die Anmeldung
ca. 60 Tage gültig ist, danach müssen Sie den Token wieder mit diesem Button abrufen.
2. EWS / MS OAuth / Access-Token anhand Benutzer u. Passwort: Hier müssen Sie den
Benutzernamen und das Passwort des Emailkontos in der DOCBOX® hinterlegen.
Wenn alle Daten korrekt eingegeben wurden, werden Ihre Emails abgerufen.
Diese Methode funktioniert nicht bei der Zwei-Faktor-Authentifizierung des Email-Kontos.
3. MS GraphApi / OAuth: Mit dieser Methode klicken Sie auf den Button "OAuth Access-Token abrufen".
Sie werden auf die Seite zur Anmeldung an dem abzurufendem Konto an Microsoft weitergeleitet.
Nach der Anmeldung wird der Token abgerufen und die Email-Abholung funktioniert.
E-Mail Ordner: Posteingang oder INBOX
(Abhängig von den Spracheinstellungen in Office 365 kann der E-Mail Ordner "Posteingang" oder "INBOX" lauten; ersichtlich durch eine Anmeldung in Outlook 365)
Konfiguration des Kontos ab Version 6.8.2
URL zum Exchange Web-Service: „https://outlook.office365.com/EWS/Exchange.asmx“
Exchange Version: Exchange 2010 SP2(oder höher)
Exchange E-Mail-Adresse: EWS E-Mailadresse
Exchange Benutzername: EWS Benutzername
Exchange Passwort: EWS Passwort
Mailarchive V7 verwenden: anhaken
E-Mail-Ordner: Posteingang oder INBOX
(Abhängig von den Spracheinstellungen in Office 365 kann der E-Mail Ordner "Posteingang" oder "INBOX" lauten; ersichtlich durch eine Anmeldung in Outlook 365)
Microsoft OAuth: anhaken
Abruf des Tokens
Nachdem Sie ein neues E-Mail-Postfach für Exchange Server in der DOCBOX® angelegt und gespeichert haben, müssen Sie den erstellten Datensatz erneut öffnen. Nun erscheint ein zusätzlicher Button für den "OAuth Token" Abruf. Durch Klick auf diesen Button wird der Token zum ersten Mal abgerufen. Melden Sie sich dann zwingend bei Office365 mit der in der DOCBOX® (neu) angelegten E-Mail Adresse an. Achten Sie darauf, dass Sie nicht bereits mit einem (anderen Konto) in Azure angemeldet sind, sonst werden Sie unter Umständen direkt zu Azure mit dem falschen Login weiter geleitet. Der Token muss pro E-Mailpostfach abgerufen werden, d.h wenn Sie mehrere Postfächer haben muss der Token mehrfach abgerufen werden. Nachdem der Token erfolgreich abgerufen wurde, werden Sie direkt zu Microsoft weitergeleitet.
Der Token Abruf muss innerhalb der DOCBOX® zusätzlich im Dialog noch einmal bestätigt werden.
Zustimmung der App im Account
In diesem Fenster werden Sie von Microsoft aufgefordert, notwendige Berechtigungen für den Abruf von Nachrichten zuzustimmen. Bitte klicken Sie auf den Button "Akzeptieren" und Sie werden wieder in Ihre DOCBOX® zurückgeleitet und der Abruf über den OAuth steht Ihnen zur Verfügung.
Nachdem Sie alles korrekt konfiguriert haben, prüfen Sie bitte, ob es für das E-Mail Konto auch eine gültige E-Mail Regel in der DOCBOX® gibt. Die DOCBOX® holt nur E-Mails ab, sofern eine gültige E-Mail Regel vorhanden ist.
