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.