Es wurde seitens Microsoft Änderungen an den Exchange-Services vorgenommen. Wir zeigen Anwendern der ameax Unternehmenssoftware, die die Exchange-Schnittstellen für Online-Server nutzen, welche Einstellungen nun durchzuführen sind.
Einrichtung des Zugriffs auf EWS-Dienste durch die ameax Unternehmenssoftware
Damit die ameax Unternehmenssoftware auf den Exchange-Server zugreifen können, wird entweder ein „NTML-Zugriff“ oder ein Zugriff via „OAuth2“ benötigt. Die bisherige Anmeldung über „Basic-Realm“ wird nicht mehr unterstützt.
„NTML“ bedeutet, dass die Freigabe via Benutzername und Passwort passiert. Das ist bei öffentlichen Microsoft Exchange- oder Teams-Servern nicht möglich, sondern nur, wenn Sie einen Server bei sich im Hause stehen und dort selbst eine Installation vorgenommen haben.
„OAuth2“ ist die einzige Möglichkeit, sich bei öffentlichen Microsoft-Servern anzumelden. So zum Beispiel bei Servern unter der Domain outlook.office365.com.
Diese Option kann aber auch bei Installationen auf Servern, die Sie selbst im Haus haben, verwenden werden.
Bei „OAuth2“ wird ein Zugangsschlüssel für jeden Benutzer generiert, welcher für die Anmeldung verwendet wird. In diesem Zugangsschlüssel sind die Zugriffsrechte definiert, die einem Dienst (in unserem Fall einem ameax-Produkt) gewährt werden.
Es wird empfohlen, für die Verbindung mit einem ameax-Produkt immer mit der OAuth2-Anmeldung zu arbeiten.
1. App in Exchange- oder Teams-Server einrichten
1.1 Azure Active Directory Admin Center
- Bitte öffnen Sie die Seite Ihres Azure Active Directory.
- Wenn Sie einen öffentlichen Microsoft-Server verwenden, ist der Link hierzu:
https://aad.portal.azure.com/ - Wenn Sie eine Installation auf einem im Haus befindlichen Server haben, so erfragen Sie die entsprechende URL bitte bei Ihrem System-Administrator.
- Melden Sie sich bitte mit einem Benutzer an, welcher administrativen Zugriff hat.
- Sie werden (je nach Version und Installation) den Bildschirm in der Abbildung 1 sehen.
1.2 App registrieren
- Wählen Sie bitte im ersten Menü den Punkt „Azure Active Directory“
- Im daraufhin eingeblendeten Menü wählen Sie bitte „App-Registrierungen“ aus.
Im oberen Bereich des Fensters steht „Neue Registrierung“, welche Sie bitte ausführen:
Das nun angezeigte Formular füllen Sie bitte folgt aus:
- Name (1)
Diesen Namen können Sie frei vergeben. Er dient dazu, dass Sie diese App wieder erkennen. Wir empfehlen hier „ameax OAuth2“ - Unterstütze Kontotypen (2)
Bitte wählen Sie hier „Nur Konten in diesem Organisationsverzeichnis“ - Umleitungs-URI (3)
Hier benötigen Sie keine Einstellungen. Lassen Sie beide Felder leer. - Klicken Sie danach auf den Button „Registrieren“ (4) am Ende des Formulars.
1.3 APP-Daten
Normalerweise werden Sie nun direkt auf die Übersichtsseite weitergeleitet. Sollte dies nicht passieren, so klicken Sie links im zweiten Menü auf „Übersicht“.
Aus dieser Übersicht müssen Sie sich zwei Werte notieren.
- Anwendungs-ID (Client)
- Verzeichnis-ID (Mandant)
Je nach Version kann diese auch als „Tenant“ bezeichnet sein.
Beide Werte können jederzeit in der Übersicht erneut eingesehen werden.
1.4 Berechtigungen der APP festlegen
Damit die ameax-Software auf die Inhalte des Kontos zugreifen kann, muss der App nun Zugriff auf bestimmte Daten gewährt werden. Dazu klicken Sie bitte im zweiten Menü auf „Manifest“. Es öffnet sich folgender Bildschirm:
Rechts finden Sie einen Text-Editor, in dem Sie Daten eingeben und ändern können. Bitte nehmen Sie nur die folgend beschriebene Änderung vor:
Suchen Sie bitte den Bereich, der mit „requiredResourceAccess“ beginnt und mit einer eckigen Klammer und einem Komma endet.
Ersetzen Sie diesen Teil durch den folgenden Text (es ist egal wo die Leerzeichen und Zeilenumbrüche stehen):
"requiredResourceAccess": [{"resourceAppId": "00000002-0000-0ff1-ce00-000000000000","resourceAccess": [{"id": "1d490c92-d2ca-4a30-b52e-6edf5f279f4d","type": "Scope"},{"id": "3b5f3d61-589b-4a3c-a359-5dd4b5ee5bd5","type": "Scope"},{"id": "eb665d05-7f76-4d1b-b176-1cfc814e668d","type": "Scope"},{"id": "9b005f11-86f0-45f7-8c27-4fff5d849916","type": "Scope"},{"id": "c21d8660-9de1-4404-85b6-59695921bd8d","type": "Scope"},{"id": "4585ecca-5b47-432f-ac70-e1391e4951ed","type": "Scope"},{"id": "c54cba4f-60fe-4332-b0de-b5990fd1999e","type": "Scope"},{"id": "d6aa6fa9-3360-416a-b8db-021249d58e86","type": "Scope"},{"id": "5b9be81f-2977-4d27-8faf-bb43af8fc705","type": "Scope"},{"id": "765f423e-b55d-412e-97e3-13a800c3a537","type": "Scope"},{"id": "181aac24-028a-486e-a649-b3742c74ec71","type": "Scope"},{"id": "32253599-e142-4cf0-810d-4827eedd1cfa","type": "Scope"},{"id": "6223a6d3-53ef-4f8f-982a-895b39483c61","type": "Scope"},{"id": "6222dbab-a24c-4210-9d91-2f47cf565614","type": "Scope"},{"id": "9478ac54-3753-4543-b95a-4fad24978902","type": "Scope"},{"id": "44882612-f346-430a-b938-4f00ee1c77a7","type": "Scope"},{"id": "d660a04c-7b62-4b4c-bea3-89226df00142","type": "Scope"},{"id": "bbd1ca91-75e0-4814-ad94-9c5dbbae3415","type": "Scope"},{"id": "da710fc9-1e83-407b-8c5c-09d225031769","type": "Scope"},{"id": "15f260d6-f874-4366-8672-6b3658c5a09b","type": "Role"},{"id": "bf24470f-10c1-436d-8d53-7b997eb473be","type": "Role"},{"id": "77e65b5a-ceae-48b3-9490-50a86a038a48","type": "Role"},{"id": "dc890d15-9560-4a4c-9b7f-a736ec74ec40","type": "Role"},{"id": "798ee544-9d2d-430c-a058-570e29e34338","type": "Role"},{"id": "089fe4d0-434a-44c5-8827-41ba8a0b17f5","type": "Role"},{"id": "6918b873-d17a-4dc1-b314-35f528134491","type": "Role"},{"id": "ef54d2bf-783f-4e0f-bca1-3210c0444d99","type": "Role"},{"id": "2dfdc6dc-2fa7-4a2c-a922-dbd4f85d17be","type": "Role"}]}],
Klicken Sie anschließen oben im Menü auf „Speichern“.
1.5 Freigabe durch den Administrator
Da einige Zugriffe auf – von Microsoft definiert – sensible Daten bestehen, müssen diese Berechtigungen nun auch noch vom Administrator freigegeben werden.
- Klicken Sie links im zweiten Menü auf „API-Berechtigungen“. Dort sehen Sie nun, welche Rechte über das Manifest angefordert wurden und können auch im Klartext lesen, was die entsprechenden Rechte bedeuten.
Erteilen Sie nun über den Button „Administratorzustimmung für IHRE-FIRMA erteilen“ alle nötigen Freigaben. Bestätigen Sie dies mit dem „Ja“-Button im Rückfrage-Dialog
Bestätigung der Administratoreinwilligung
- Anschließend sind bei allen Rechten in der Spalte „Status“ grüne OK-Zeichen zu sehen.
1.6 Schlüssel zur ersten Anmeldung
Damit die ameax-Software nun einen OAuth2-Schlüssel für die Anmeldung generieren kann, benötigen Sie noch einen sogenannten „geheimen Clientschlüssel“. Dieser Schlüssel hat nur einen begrenzten Gültigkeitsbereich und wird häufig auf als „Einmal-Passwort“ oder „Wegwerf-Passwort“ bezeichnet.
- Für dessen Generierung klicken Sie bitte auf den Menüpunkt „Zertifikate und Geheimnisse“ und wählen in der Übersichtsseite den Button „Geheime Clientschlüssel“ Klicken Sie danach auf „Neuer geheimer Clientschlüssel“.
Im folgenden Formular (auf der rechten Seite) verwenden Sie bitte folgende Angaben:
- Beschreibung (1)
Diesen Namen können Sie frei vergeben. Er dient dazu, den diesen Schlüssel wieder zu erkennen. Wir empfehlen hier „Einrichtungsschlüssel“ - Gültig bis (2)
Verwenden Sie den längsten Zeitraum, der angeboten wird.
- Klicken Sie danach auf den Button „Hinzufügen“.
- Sie benötigen den Text, der in der Spalte „Wert“ steht. Dieser Text kann nur jetzt im Klartext gelesen werden.
Wenn Sie das Azure Active Directory Admin Center verlassen und wieder öffnen, ist der Wert nicht mehr auslesbar. Es ist also sehr wichtig, dass Sie diesen Wert sofort kopieren und sich in Ihren sicheren Unterlagen vermerken, zusammen mit dem Gültigkeitszeitraum.
Um sich den Wert zu kopieren, benutzen Sie am besten das Icon „In Zwischenablage kopieren“ (im Bild durch den roten Pfeil markiert).
2. Einstellungen in der ameax Unternehmenssoftware
2.1 Exchange-Account verknüpfen
- Melden Sie sich in Ihrer ameax Unternehmenssoftware an, öffnen Sie im Einstellungsbereich bei „Schnittstellen & Dienste“ den Bereich „Exchange Accounts“ und klicken auf „Anlegen“.
- Bearbeiten Sie die darauf erscheinende Maske wie folgt:
- Der „Host“ ist die URL zu Ihrem Microsoft-Server. Bei öffentlichen Exchange- oder Teams-Servern ist dies outlook.office365.com.
- Unter „Version“ geben Sie bitte an, welche Exchange-Version Sie im EWS-Protokoll verwenden. Bei öffentlichen Exchange- oder Teams-Servern ist das die Version: Microsoft Exchange 2016
- Tragen Sie bitte in das Feld „Benutzername“ (1) den Anmeldenamen Ihres Benutzers von Ihrem Microsoft-Server ein. Dies ist meistens Ihre E-Mail-Adressen. Wenn Sie Ihren Anmeldenamen nicht wissen, so können Sie im Azure Active Directory Admin Center unter „Benutzer“ das „Benutzerprofil“ öffnen und dort im Feld „Benutzerprofilprinzipalname“ den Anmeldenamen prüfen.
- Tragen Sie bitte in das Feld „OAuth2-App-ID“ (2) die „Anwendungs-ID (Client)“ aus Schritt 1.3 ein.
- Tragen Sie bitte in das Feld „App-Directory-ID“ (3) die „Verzeichnis-ID (Mandant)“ aus Schritt 1.3 ein.
- Klicken Sie danach auf „Speichern“.
2.2 Ersten Access-Token anfordern
Derzeit ist Ihr Exchange-Konto mit dem ameax-Konto verknüpft, aber gearbeitet werden kann noch nicht, da noch kein Access-Token vorhanden ist. Daher steht im Status „Gesperrt“ und als Meldung der Hinweis „Bitte fordern Sie einen neuen Access-Token an“.
- Klicken Sie auf „Access-Token erneuern und aktivieren“.
- Es wird ein Formular für den „Secret-Value“ (1) ausgegeben. Übertragen Sie bitte den in Schritt 1.5 gespeicherten Wert. Klicken Sie danach auf „Anfordern“.
2.3 Weitere Exchange- oder Teams-Konten anlegen
Die Einrichtungen aller weiteren Konten laufen nach dem gleichen Schema ab. Der einzige Unterschied ist, dass Sie jedes Mal einen anderen Benutzernamen verwenden müssen. Die ID- und Secret-Werte sind jedes Mal identisch.
Bitte beachten Sie, dass zur Einrichtung ein gültiger geheimer Clientschlüssel verwendet werden muss und dieser eine Laufzeit hat (standardmäßig 6 Monate, die Laufzeit haben Sie im Schritt 1.5 selbst angegeben). Sollte dieser Schlüssel abgelaufen sein, so müssen Sie einen neuen Schlüssel wie in Schritt 1.5 anlegen.
Sobald ein ameax-Konto mit einem Exchange- oder Teams-Konto verknüpft ist, benötigen Sie den Client-Schlüssel nicht mehr. Der verwendete Access-Token bleibt aktiv, solange innerhalb von 14 Tagen die ameax-Software auf das Exchange-Konto zugreift. Da die Termine und Kontakte mehrfach täglich synchronisiert werden, bleibt somit die Gültigkeit des Access-Tokens automatisch erhalten. Sollte die Gültigkeit aus irgendwelchen Gründen abgelaufen sein, können Sie mit dem geheimen Clientschlüssel wieder einen neuen Access-Token anfordern, wie in Schritt 2.2 beschrieben.