E-Mail-Import

Anleitungen zur Konfiguration von Mail-Importen und der Integration mit anderen Features.

• Allgemeine Konfiguration
• Verarbeitung von Anlagen
• Verarbeitung unter Windows konfigurieren
• Filterung mittels Black- und Whitelisting
• Leitfaden: Zugriff auf Exchange Online Postfächer einschränken
• Konfiguration Client Credentials Flow (application) MS Graph API
• Konfiguration Authentication Code Flow (delegated) MS Graph API
• Configuration Client Credentials Flow (application) MS Graph API [ENG]
• Configuration Authentication Code Flow (delegated) MS Graph API [ENG]
• Übernahme von E-Mail-Feldern in Squeeze-Felder
• Unterstützung von S/MIME

Allgemeine Konfiguration

Je Stapelklasse ist es möglich 1-n Emailkonten zu konfigurieren, um Emails automatisiert aus den konfigurierten Postfächern abzurufen und die angehängten Dokumente zu verarbeiten.

Es werden drei Verfahren unterstützt, um Emails aus den Postfächern abzuholen.

• Abruf via EWS (Exchange Web Services)
• Abruf via IMAP (Internet Message Access Protocol)
• Abruf via Microsoft Graph API (Graph API mit OAuth2.0)

Allgemeine Konfiguration

Über Importe -> E-Mail gelangen Sie zur Übersicht der Email-Konten. Über das Feld Stapelklasse kann die Stapelklasse ausgewählt werden für die ein neues Email-Konto eingerichtet werden soll. Über "+ Neuer Eintrag kann nun ein neues Konto angelegt werden.

Ordner konfigurieren

Die drei Ordner "Posteingang", "Verarbeitet" und "Fehler" sind die Postfach-Ordner, mit welchen SQUEEZE interagiert.

Warnung: Diese Ordner müssen sich auf oberster Ebene des Postfachs befinden. Das Abgreifen von Unterordnern (welches vereinzelt bei Kunden im Einsatz war/ist) ist eine Projektlösung. Bei Updates bitten wir das zu berücksichtigen und darum, die Ordner entsprechend zu verschieben.

Shared Mailboxes abfragen

Besonderheit EWS / Graph API

Wenn Sie mit einem Benutzer auf ein geteiltes Postfach zuzugreifen, tragen sie im Feld Benutzer zuerst den User ein, mit dem sie zugreifen und danach den Benutzer des geteilten Postfachs, getrennt durch /:

Beispiel: benutzername@domain.de/shared-benutzername@domain.de

Beispiel mit NTLM Anmeldung: local.domain.net\benutzername/mailbox@domain.de

Verbindung Testen

Mit einem Klick auf dieses Symbol kann die Mail-Verbindung getestet werden.

Sollte es zu einem Problem bei der Verbindung gekommen sein, wird in der linken unteren Ecke eine Fehlermeldung angezeigt in der der Fehler beschrieben wird.

Mit einem Klick auf dieses Symbol wird der Email-Abruf getriggert.

Provider - EWS

Im Oktober 2022 wird durch Microsoft die Authentifizierung mittels Basic-Auth bei Exchange Online flächendeckend abgeschaltet. Für die Anbindung von Exchange Online Postfächern empfehlen wir die Verwendung der Graph API.

Die BasicAuth für die Exchange Web Services wird im Oktober 2022 abgeschaltet. Wenn der zu einrichtende Dienst nur noch OAuth2.0 mit Verbindung zur Microsoft Graph API unterstütz dann siehe Abschnitt Besonderheit Microsoft Graph API. Um zu prüfen, ob die BasicAuth für ein System noch verfügbar ist, kann die folgende URL (ggf. Server durch den eigenen Exchange Server ersetzen) genutzt werden:

https://outlook.office365.com/EWS/Exchange.asmx

Nach dem Aufruf dieser URL erscheint ein Dialog zur Eingabe des Benutzernamens und des Passworts.
Sofern diese Anmeldung erfolgreich ist und eine entsprechende Webseite angezeigt wird, ist BasicAuth verfügbar.

EWS Verbindungstest

Im Falle einer EWS Verbindung kann es hilfreich sein vorab einen Verbindungstest durchzuführen. Das gilt besonders dann, wenn es sich um einen eignen Exchange Server handelt. Der Verbindungstest kann mit der folgenden Seite durchgeführt werden:

https://testconnectivity.microsoft.com/tests/EwsTask/input

Sollte es sich um einen eignen Exchange Server handeln für den kein AutoDiscover eingerichtet ist, dann muss die EWS Adresse manuell angegeben werden (2). 

Provider - Microsoft Graph API

Die Anmeldung durch Squeeze geschieht unter Verwendung von OAuth.

Microsoft unterstützt zwar mehrere OAuth-Flows, aktuell unterstützt Squeeze nur den Client Credential Flow und den  Authentication Code Flow.

Diese unterscheiden sich darin, welche Permissions Squeeze erhält.

Die Graph API wird seit Squeeze 2.1 unterstützt.

Authentication Code Flow

(Microsoft delegated)

Client Credentials Flow

(Microsoft application)

Verarbeitung von Anlagen

Diese Dokumentation beschreibt, wie Anlagen ("Attachments") bei Mail-Importen gehandhabt werden. Das dokumentierte Verhalten ist unabhängig vom verwendeten Mail-Protokoll, es spielt also keine Rolle, ob Mails mittels IMAP, EWS, usw. importiert werden sollen.

Anlagen mit Passwörtern

Im täglichen Geschäft können über die digitalen Eingangskanäle ihres Unternehmens, eine Vielzahl von verschlüsselten Anlagen erreichen. In folgenden Abschnitt gehen wir auf die zur Verfügung stehenden Möglichkeiten in Squeeze ein.

Komprimierte Archive(.zip)

Erhalten Sie verschlüsselte ZIP-Archive von ihren Absendern so bietet Squeeze Ihnen ab der Version >=2.4.1 eine Möglichkeit Passwörter für die eindeutigen Email-Adressen zu hinterlegen. 

Für die Konfiguration müssen Sie als Admin die Email-Registerkarte öffnen:

im nächsten Schritt gibt es nun eine weitere Registerkarte innerhalb der Email-Konfigurationsoberfläche. Dort können sie die Registerkarte Passwörter auswählen.

im Unteren Teil der Oberfläche finden Sie nun ein Button um ein neuen Eintrag hinzuzufügen. 

Nun können Sie mit der Verwendung einer eindeutigen E-Mail und durch die Eingabe eines Passwort die Daten speichern.

Achten Sie bitte auf folgende Hinweise in der Handhabung dieser Funktionalität:

1. Sie müssen vollwertige E-Mails angeben, dass bedeutet Sie müssen immer ganze Email-Adressen angeben ansonsten schlägt der Speichervorgang fehl
2. Um eventuell mehrere Passwörter einer E-Mail zuzuordnen legen Sie einfach mehrere Einträge an.
3. Wenn Emails Anhänge enthalten die nicht entschlüsselt werden können, werden diese Emails in den spezifizierten Error E-Mail Ordner verschoben.

Die hinterlegten Passwörter werden nicht für passwortgeschützte PDF-Datein verwendet.

Eine eindeutige E-Mail Adresse ist zum Beispiel: dexpro@test.com und nicht Konstrukte wie:  *pro@test.com

Anlagen-Filter

Funktionsweise

Für jede Mail werden die Anlagen auf Basis von Import-Regeln geprüft. Die erste Regel deren Sender und Dateimuster zu einem Anhang passen entscheidet was mit dem Anhang geschieht. Dabei erhalten die Regeln die am nicht global sind die höchste Priorität. 

Beispiel:

Wenn keine der Regeln passen, wird die Anlage ignoriert.

Für die Ausführung der PDF-Zusammenführung oder PDF-Trennung verwendet Squeeze die Software-Bibliothek "PDFBox". Die Verfügbarkeit der Bibliothek ist für die Anlagen-Filterung dringend notwendig. Ab der Squeeze Version 2.3.4 wird diese Bibliothek mit in die System-Prüfungen aufgenommen. Dies ermöglicht Ihnen eine schnelle Identifikation von möglichen Fehlerursachen.

Die Stammdatentabelle emailattachmentfilters wird verwendet um SQUEEZE mitzuteilen, ob und wie Anlagen für die Erkennung relevant sind.

Die Tabelle hat folgende Struktur:

Beispiel-Konfigurationen

Beispiel

Erklärung der Regeln

Regel ID 1:
Diese Regel bedeutet, dass für jeden Absender jedes PDF einer Email als Dokument für die Extraktion behandelt wird und alle PDFs zu einem Dokument zusammengefasst werden.

Regel ID 2:
Diese Regel bedeutet dass für jeden Absender die PDF mit dem Namen AGB.pdf als Anlage beibehalten wird.

Regel ID 3:
Diese Regel greift nur bei Absendern der Domain dexpro.de und bedeutet, dass PDFs die dem Dateinamenmuster INV*.pdf entsprechen als Dokument erhalten bleiben. Dabei gilt zusätzlich, dass jede Datei, die diesem Muster entspricht, zu einem eigenständigen Dokument werden.

Regel ID 4:
Diese Regel greift nur bei dem Absender payment@dexpro.de und bedeutet, dass PDFs die dem Dateinamenmuster Avis*.pdf entsprechen als Dokument erhalten bleiben. Dabei gilt zusätzlich, dass jede Datei, die diesem Muster entspricht, zu einem eigenständigen Dokument einer neuen Stapel- und Dokumentenklasse werden.

Regel ID 5:
Diese Regel greift nur bei Absendern der Domain dexpro.de und bedeutet, dass XML Dateien (bspw. eine XRechnungen) als Anlagen beibehalten werden. Dabei wird vorausgesetzt, dass es eine gültige PDF in der E-Mail gibt (z.B. aus Regel ID 3), die den Hauptvorgang bildet.

Regel ID 6 & 7:
Diese Regel greift nur bei dem Absender invoice@squeeze.one und bedeutet, dass XML Dateien (bspw. eine XRechnung) als Dokument erhalten bleibt. Alle zusätzlich angehangenen PDF-Dokumente werden als Anlagen weitergeführt.

Für die Steuerung der Verarbeitung von E-Mails, die sowohl XRechnungs-Dokumente als auch ZUGFeRD Belege enthalten,
können entsprechende Regeln definiert werden.

Update-Hinweis

Trennung von Anlagen und Dokument ab Squeeze 1.10

In den Squeeze 1.9 (und älter) wurden Dokumente und Anlagen beim Import zwar unterschiedlich behandelt, allerdings in den Folge-Schritten der Verarbeitung als eine Datei behandelt. Ergebniss war, dass primär zu verarbeitendes Dokument und die Anlagen als eine PDF zusammengeführt und dann auch so extrahiert wurden, als wäre eine einzelne Datei importiert worden.

Ab Squeeze 1.10 werden die Anlagen getrennt behandelt und sind somit nicht Teil des Dokumentes, welches extrahiert wird. Zusätzlich kann dies Export-Schnittstellen betreffen, die nur eine Datei pro Dokument exportieren können (Bspw. NavisionSoap). Diese exportieren in der neueren Version nur noch das Hauptdokument, Anlagen werden nicht exportiert.

Falls das Verhalten vor Squeeze 1.10 beibehalten werden soll, dann sind in den Anlagenfiltern alle Anlagen als Dokument zu markieren.

Priorisierung von XML-Rechnungen gegenüber PDF-Dateien ab Squeeze 2.17

Mit der Einführung der Version 2.17 wird das Standardverhalten von Squeeze dahingehend angepasst, dass Rechnungen im XML-Format gegenüber PDF-Dateien bevorzugt werden. Der Hintergrund dieser Änderung ist, dass zunehmend Kunden und Partner darauf hingewiesen haben, dass Rechnungssteller häufig sowohl Belege im XML- als auch im PDF-Format übermitteln. Je nach Konfiguration kann dies zu Dubletten oder Fehlern in der Verarbeitung führen.

Um eine einheitliche Handhabung der Belege im Standard zu gewährleisten, wird in der Version 2.17 festgelegt, dass Belege im XML-Format vorrangig behandelt werden. Dieses Verhalten kann jedoch durch die oben beschriebenen Regeln an individuelle Anforderungen angepasst werden. Eine generelle Priorisierung der PDF-Dateien ist derzeit nicht vorgesehen.

Verarbeitung unter Windows konfigurieren

Um regelmäßig auf neue Emails zu prüfen, muss eine geplante Aufgabe eingerichtet werden.
Unter Windows können dafür die geplanten Tasks genutzt werden.
Unter Linux erfolgt die Einrichtung mit Hilfe von cron Jobs.

Einrichtung unter Windows

Unter Windows kann ein geplanter Task zur Regelmäßigen Prüfung der konfigurierten Postfächer genutzt werden.
Um einen neuen Task einzurichten müssen folgende Schritte durchgeführt werden:

1. Aufgabenplanung öffnen

Es kann eine eigener Unterordner für Squeeze aufgaben erstellt werden, wenn dies gewünscht ist

Auf der rechten Seite kann über den Menüpunkt "Aufgabe erstellen..." die Aufgabe für den Import der Emails angelegt werden.

2. Aufgabe erstellen

Der Name und die Beschreibung ist natürlich frei wählbar.

Damit die Aufgabe unabhängig von der Anmeldung eines Benutzers ausgeführt wird und auch unabhängig von eventuellen Passwortänderungen ist, hat sich bewährt, das System Konto auszuwählen. 

Die Aufgabe "mit höchsten Privilegien" zu starten hat sich ebenfalls bewährt.

3. Trigger/Zeitpunkt festlegen

Das Intervall in dem die Emails abgerufen werden sollen ist ebenfalls frei definierbar.
Bewährt hat sich ein Intervall von 5 Minuten im Produktivsystem. Für Testsysteme kann dieser Intervall natürlich auch kleiner gewählt werden, wenn schnell und viel getestet werden soll. 

4. Aktion festlegen

Als Programm muss die php.exe der Squeeze Installation ausgewählt werden. 
Als Argumente müssen zwei Werte angegeben werden:

• - Pfad zur EmailProcessing.php z.B. C:\SQUEEZE\htdocs\jobs\EmailProcessing.php
• - Mandant für den die Emails abgerufen werden sollen z.B. client.squeeze.net

C:\SQUEEZE\htdocs\jobs\EmailProcessing.php client.squeeze.net

Filterung mittels Black- und Whitelisting

Whitelist und Blacklist sind nacheinander geschalten und stehen daher in Verbindung.
Bei aktiver Whitelist muss der Absender erst auf der Whitelist stehen, damit eine aktive Blacklist geprüft wird!

Validierung eintreffender E-Mails

Kurzgesagt (TLDR):

1.  Whitelist Prüfung: Absender der E-Mail wird mittels Whitelist geprüft.
2.  Blacklist Prüfung: Betreff der E-Mail des Absenders wird mittels Blacklist geprüft.

Fall 1 - Absender nicht auf der Whitelist

Ist eine Whitelist gepflegt und der Absender nicht auf dieser enthalten sein, dann wird der Betreff gar nicht erst geprüft und die E-Mail nicht importiert.

Fall 2 - Absender ist auf der Whitelist

Ist eine Whitelist gepflegt und der Absender ist auf dieser enthalten, dann wird anschließend der Betreff des Absenders per Blacklist geprüft. 

Fall 2a - Absender Betreff ist nicht auf der Blacklist

Ist der Betreff nicht auf der Blacklist, so wird die E-Mail anschließend importiert.

Fall 2b - Absender Betreff ist auf der Blacklist

Ist der Betreff "blacklisted", dann wird die E-Mail nicht importiert.

Whitelisting

Im folgenden Abschnitt wird die Einrichtung der Whitelist beschrieben.

Eine aktive Blacklist wird nach der Whitelist-Prüfung ausgeführt.
Steht der Betreff des Absenders in der Blacklist und gilt als gesperrt, wird die E-Mail nicht importiert, obwohl der Absender in der Whitelist steht!

Whitelist erstellen

Die Whitelist Tabelle emailsenderwhitelist ist unter den Stammdaten zu finden:

Unter der Spalte "Sender" können Absenderadressen (auch mit Wildcard *) eingetragen werden. Eine Stapelklasse ist notwendig.

Beispielsweise: 

• *@dexpro.de für hans@dexpro.de oder hanna@dexpro.de
• someone@dexpro.*.de für someone@dexpro.beispiel.de oder someone@dexpro.anderes.beispiel.de
• department.*@dexpro.de für department.vertrieb@dexpro.de oder department.entwicklung@dexpro.de
• *@dexpro.* für hans@dexpro.de oder hans.mustermann@dexpro.beispiel.de

Ungültige Einträge mit Sonderzeichen werden bei der Validierung der E-Mail nicht berücksichtigt - ungültige Einträge werden geloggt.

Whitelist aktivieren

Die Whitelist ist aktiv, sobald die Whitelist Tabelle existiert und mindestens ein Eintrag vorhanden ist. Wenn die Tabelle fehlt oder leer ist, ist die Whitelist Funktion inaktiv. Wenn die Whitelist inaktiv ist, wird direkt zur Blacklist-Prüfung gesprungen.

Voraussetzung ist außerdem die SQUEEZE Version 2.X.X

E-Mails von Absendern die nicht gelistet sind

E-Mails von nicht gelisteten Absenderadressen, werden nicht importiert. Dies wird geloggt.

Blacklisting

Im folgenden Abschnitt wird die Einrichtung der Blacklist beschrieben.

Eine aktive Whitelist wird vor der Blacklist-Prüfung ausgeführt. Steht der Absender nicht auf der Whitelist, wird die E-Mail bereits nicht importiert und entsprechend nicht weiter geprüft.

Blacklist erstellen

Die Blacklist Tabelle emailsubjectsblacklist ist unter den Stammdaten zu finden:

Unter der Spalte "Sender" können Absenderadressen eingetragen und unter der Spalte "Subject Pattern" der Wert im Betreff der E-Mail angegeben werden, welche nicht importiert werden sollen. Eine Stapelklasse ist notwendig.

Blacklist aktivieren

Die Blacklist ist aktiv, sobald die Blacklist Tabelle existiert und mindestens ein Eintrag vorhanden ist. Wenn die Tabelle fehlt oder leer ist, ist die Blacklist Funktion inaktiv.

Voraussetzung ist außerdem die SQUEEZE Version 1.X.X

E-Mails mit Betreffen von Absendern die gelistet sind

E-Mails von Absendern, deren Betreff als gesperrt (bzw. "blacklisted") eingetragen wurden, werden nicht importiert. Dies wird geloggt.

Leitfaden: Zugriff auf Exchange Online Postfächer einschränken

Dieser Leitfaden wurde bisher mit der Azure-Active-Directory-Cloud getestet.

Dieser Leitfaden bezieht ausschließlich auf die Verwendung der Microsoft Graph-API.

Welches Problem lösen wir ?

Wir verhindern, dass die Graph API zu viele Berechtigungen auf die Azure-Active-Directory Postfächer der verschiedenen Abteilungen erhält.

Was benötigen wir ?

Um diese Anforderung zu erfüllen benötigen wir folgende softwareseitig -Komponenten:

• Eine Powershell +7.0.0
  • Wie installiere ich die Powershell ?
• Azure-Active-Directory(AAD)
• das EXO-V2 Moduler Powershell 7 in der Version 2.0.4 oder höher.
  • Wie installiere ich das EXO-V2-Module in der Powershell 7
  • Ich habe ein Problem beim ausführen von EXO-V2 !
  • Eine Email-Zugriffsberechtige-Gruppe

Vorwort

Diese Dokumentation umfasst nicht die Einrichtung der Graph API für das Abholen der Emails durch Squeeze. 
Die Anleitung der Einrichtung des Email-Import findest du hier. 

Zudem dient dieser Artikel zur Unterstützung der Admins, die Informationen können sich im laufe der Zeit auf den referenzierten Beiträgen ändern.

Das ausführen der nachfolgenden Schritte muss unbedingt von einem Admin des AAD´s durchgeführt werden.

Was muss ich jetzt als nächstes tun ?

Um eine App in seinen Berechtigungen zu beschränken, bietet die Azure-Active-Directory das Anlegen von E-Mail-aktivierten Sicherheitsgruppen. Diese Sicherheitsgruppen können je nach Verwendung zum restriktiven Zugriff auf eine App genutzt werden. Desweiteren sind diese Gruppen in der AAD-Admin-Oberfläche im Standart nicht zu einer App hinzugefügt. Diese Einstellungen kann man nur durch die Verwendung durch die Powershell in Verbindung mit dem EXO-V2 Modul und eines Admin AAD Accounts tätigen. 

Erstellen einer E-Mail aktivierten Sicherheitsgruppe

Wenn du bereits eine Sicherheitsgruppe erstellt hast springe zu:  Verbinden der App mit der E-Mail Sicherheitsgruppe
Um eine E Mail Aktivierte Sicherheitsgruppe zu erstellen wollen wir erst einmal auf die Admin-Oberfläche des AAD´s. Dort klicken wir auf die drei angegebenen Punkte (s. Screenshot) :

Im nachfolgenden sind diese weiteren dokumentierten Schritte auszuführen.

Name und Beschreibung festlegen:

Wähle den Besitzer (Admin-Account):

Wähle nun Mitglieder/Email-Accounts die auf die App durch diese Gruppe berechtigt werden soll:

Nun vergeben wir der Gruppe eine eigene Email-Address:

Die Gruppen-Email Adresse wird für später verwendet, daher sollte man sich diese Email ablegen.

Im letzen Fenster bestätigt ihr eure Einstellung und erstellt die Gruppe.

Verbinde Sicherheitsgruppe mit Application durch Powershell

Da wir nun eine E-Mail aktivierte Sicherheitsgruppe besitzen, müssen wir diese Gruppe der Application (die zuvor erstellt wurde) zuordnen. Aktuell haben wir nur die Möglichkeit über die Powershell in Verbindung mit EXO-V2 eine Gruppe, einer App hinzu zufügen. 

Im ersten Schritt verbinden wir uns mit unserem AAD-Remote Cmdlet, dafür öffnen wir unsere Powershell als Administrator und geben folgenden Befehl ein. Für weitere Information...

Connect-ExchangeOnline -UserPrincipalName <admin@company.com>

Nun sollte sich ein Pop-Up öffnen, dass einen durch die Authentifizierung bei Microsoft führt.

Unter manchen Linux oder MacOS Distributionen wird kein Pop-Up geöffnet.
Um das Problem zu lösen muss über den Device-Code Flow die Authentifizierung durchgeführt werden.
Der folgende Befehl muss für den Device-Code Flow ausgeführt werden:

Connect-ExchangeOnline -device

Nach der erfolgreichen Authentifizierung, erhält man alle Remote-Cmdlets des Exchange-Servers auf die man Berechtigungen hat. Um nun eine App-Berechtigungsgruppe einer App zu zuordnen muss folgender Befehl ausgeführt werden.

New-ApplicationAccessPolicy -AppId <Deine Application ID / Client ID> -PolicyScopeGroupId deineGruppenEmail@deineFirma.com -AccessRight RestrictAccess -Description "Restrict this app to members of distribution group ...."

Ist der Befehl erfolgreich ausgeführt worden, dann kann mann seine Anpassungen mit diesem Befehl testen:

Test-ApplicationAccessPolicy -Identity deineGruppenEmail@deineFirma.com -AppId <deine Application ID / Client ID>

Das Ergebnis des Befehls sollte so aussehen:

Nun solltest du die App auf die ausgewählten Nutzer der E-Mail aktivierten Sicherheitsgruppe beschränkt haben. 

Bis die Änderungen im AAD greifen, kann es bis zu einer Stunde laut Microsoft dauern.  

Konfiguration Client Credentials Flow (application) MS Graph API

Client Credential Flow Microsoft Graph API

Konfiguration in Squeeze

Bei den ersten Versionen dieses Features musste die Konfiguration mittels der Felder "Benutzername" und "Passwort" gepflegt werden. Wir empfehlen ein Update.

Erwarteter Wert im Feld Benutzername: maxMustermann@mustermann.de/{client_id}/{tenant_id}
Erwarteter Wert im Feld Passwort: {client_secret}

Ordner - Konfiguration

Bei der Ordnerkonfiguration müssen Sie drei Ordner angeben

1. Posteingang
   Dieser Ordner wird regelmäßig überprüft, um die enthaltenen Emails zu importieren. 
2. Verarbeitet
   In diesen Ordner werden die erfolgreich importieren Emails verschoben.
3. Fehler
   In diesen Ordner werden, die Emails abgelegt, die nicht importiert werden konnten (z.B. fehlende Anlagen)

Bei der Definition der Ordner achten Sie bitte darauf, dass die Namen der Ordner eindeutig sein müssen, da die Ordner in der Verzeichnisstruktur des Postfachs gesucht werden.
Ist ein konfigurierter Ordner nicht eindeutig kann es dies dazu führen, dass ein anderer Ordner genutzt wird, als der gewünschte. 

Konfiguration in Entra ID (vormals Azure Active Directory)

Weitere notwendige Schritte für ein reibungslosen Ablauf sind die Einrichtung einer Entra ID Application
mit einem Client Secret. Die Globale Registrierung eines Mail-Dienstes der "Dexpro"  im Entra ID-Directory  des Kunden, wird vorerst nicht angeboten.

Zudem muss darauf geachtet werden dass die Applikation folgende Scopes besitzt. 

Im Standard hat diese Application nun Zugriff auf alle Postfächer.

Falls Sie diesen Zugriff auf einzelne Postfächer beschränken möchten, müssen zusätzliche Konfigurationen in Exchange Online, in Entra ID und mittels PowerShell getätigt werden.

In dieser Dokumentation von Microsoft wird beschrieben, wie Sie dies mittels Gruppenrichtlinien einrichten: Verwaltung der Gruppenrichtlinien in der Azure-AD

Wenn der Microsoft Artikel nicht ausreichend unterstützend ist, haben wir ein Leitfaden angefertigt der genauer beschrieben ist.

Konfiguration Authentication Code Flow (delegated) MS Graph API

Konfiguration in Squeeze

Diese Konfigurationsoberfläche wird ab der Version 2.3.0 bereitgestellt.

Wenn Sie diese Authentifizierungsmethode nutzen möchten, stellen Sie sicher, dass der Interne Job refresh-tokens aktiviert ist. Dies ist weiter unten im Artikel dokumentiert.

Wie man nun erkennt, kann man in der Konfigurations-Oberfläche unter Protokoll zwei Arten der Anbindung zu Microsoft(MS) Graph API wählen:

Für den delegierten Autorisierungsprozess wählen wir Microsoft Graph API Delegated. Im nächsten Schritt füllen wir die Felder Client ID, Client Secret die Tenant ID und die restlichen Felder. 

Ordner - Konfiguration

Bei der Ordnerkonfiguration müssen Sie drei Ordner angeben

1. Posteingang
   Dieser Ordner wird regelmäßig überprüft, um die enthaltenen Emails zu importieren. 
2. Verarbeitet
   In diesen Ordner werden die erfolgreich importieren Emails verschoben.
3. Fehler
   In diesen Ordner werden, die Emails abgelegt, die nicht importiert werden konnten (z.B. fehlende Anlagen)

Bei der Definition der Ordner achten Sie bitte darauf, dass die Namen der Ordner eindeutig sein müssen, da die Ordner in der Verzeichnisstruktur des Postfachs gesucht werden.
Ist ein konfigurierter Ordner nicht eindeutig kann es dies dazu führen, dass ein anderer Ordner genutzt wird, als der gewünschte. 

Konfiguration in Entra ID (vormals Azure Active Directory)

Weitere notwendige Schritte für ein reibungslosen Ablauf sind die Einrichtung einer Entra ID Application
mit einem Client Secret. Die Globale Registrierung eines Mail-Dienstes der "Dexpro"  im Entra ID-Directory  des Kunden, wird vorerst nicht angeboten.

Zudem muss darauf geachtet werden dass die Applikation folgende Scopes besitzt. 

Anders als in den Permission für den Client Credential Flow ist jegliche Permission hier beschränkt auf den autorisierenden User.

Merke: Wenn auf ein Shared-Mailbox Postfach zugegriffen werden soll, muss das Shared-Mailbox Postfach unter Postfach eingetragen werden und die Application Permission Mail.Read.Write.Shared muss konfiguriert werden.

Denken Sie daran, dass die Shared-Mailbox auch Ihrer Email-Aktivierten Sicherheitsgruppe hinzugefügt wird, wenn Sie eine eingerichtet haben.

Ebenfalls ein maßgebender Unterschied zum Client Credential Flow ist hier die Verwendung einer Redirect URI. 
Diese Redirect URI wird in der Entra ID unter der Applikation im Reiter Authentication angelegt:

Schema Redirect URI: https://Ihr.vollwertiger.DomainName/api/v2/importers/email/authenticate/end

Merke: Ein Squeeze Mandant benötigt immer eine Entra ID Applikation mit einer Redirect URI.
Das bedeutet Sie müssen für jeden Mandanten eine Applikation anlegen.

Autorisierungsprozess Authentication Code Flow

hat man nun seine Application in Entra ID konfiguriert und alle notwendigen Daten in die Konfigurationsoberfläche getippt kann man  nun seine Konfiguration abspeichern. 

Nun öffnet sich ein weiteres Dialog Feld :

Das System hat Ihre Konfiguration gespeichert, den Prozess der Authentifizierung müssen Sie jedoch separat über einen Button in der Email Konfiguration starten. Hierfür wählen Sie bitte den folgenden Button:

Nach einem Klick auf diesen Button werden Sie nun zur Oberfläche von Microsoft weitergeleitet. Dort beginnt der Authentifizierungsprozess befolgen Sie die Anweisungen von Microsoft:

Geben Sie ihre Email-Adresse an.

Geben Sie Ihr Passwort ein:

Je nach Unternehmen werden Sie ebenfalls aufgefordert eine 2-Faktor-Authentifizierung durchzuführen.:

Sobald Sie Authentifiziert sind, werden die Berechtigungen abgefragt und Sie werden aufgefordert diese Berechtigungen zu bestätigen. Nach Ihrer Bestätigung leitet Microsoft umgehend zurück zur Squeeze-Oberfläche. 

Die Oberfläche wird Ihnen nun anzeigen ob Squeeze nun Autorisiert ist oder ob ein Fehler aufgetreten ist:

Nun können Sie die Mail Verbindung testen Indem Sie den Mail Verbindungstest Button in der Oberfläche bedienen. 

Job-Konfiguration

Die Verwendung dieses Authentifizierungsverfahrens erfordert, dass ein seperater Job aktiviert ist, welcher im Hintergrund die Zugriffsdaten für die Graph API aktuell hält.

Hierfür finden wir in der Administration unter "Skripte" das neue Skript  mit den Namen refresh-tokens:

Dieses Skript kann man zu jedem Zeitpunkt manuell ausführen.

Sie müssen für dieses Skript einen Job einrichten, der häufig genug ausgeführt wird, um ein Ablaufen der Zugriffsdaten zu verhindern. Im Standard sind Refresh-Token von Microsoft 1 Tag lang gültig, es sollte also mehrmals am Tag versucht werden die Zugriffsdaten zu aktualisieren.
Bei geringerer Gültigkeit als 12 Std. muss per Projekt Change Request die Erneuerung eines Tokens auf eine passende kürzere Zeit von einem Consultant angepasst werden. 
Wir empfehlen den Job jede Stunde auszuführen:
Cron-Ausdruck für den Job: */50 * * * *

Wie Jobs zu konfigurieren sind, ist hier dokumentiert:

• Artikel über Job Ausführungen in Squeeze 
• Artikel über Job Steuerungen

Fragen und Antworten

Configuration Client Credentials Flow (application) MS Graph API [ENG]

Client Credential Flow Microsoft Graph API 

Configuration in Squeeze

In the first versions of this feature, the configuration had to be maintained using the "Username" and "Password" fields. We recommend an update.

Expected value in the Username field: maxMustermann@mustermann.de/{client_id}/{tenant_id}
Expected value in the Password field: {client_secret}

Ordner - Konfiguration

In the folder configuration you need to specify three folders

1. Inbox
   This folder is regularly checked to import the emails it contains. 
2. Done
   The successfully imported emails will be moved to this folder.
3. Error
   The emails that could not be imported (e.g. missing attachments) are stored in this folder.

When defining the folders, please make sure that the names of the folders must be unique, since the folders are searched for in the directory structure of the mailbox.
If a configured folder is not unique, this can lead to a different folder being used than the desired one. 

Configuration in AAD (Azure Active Directory)

Other necessary steps for a smooth process are the setup of an Azure Active Directory Application
with a Client Secret. The global registration of a mail service of "Dexpro" in the Azure Active Directory of the customer is not offered for the time being.

In addition, it must be ensured that the application has the following scopes. 

By default, this application now has access to all mailboxes.

If you want to restrict this access to individual mailboxes, additional configurations must be made in Exchange Online, the AAD and using PowerShell.

This documentation from Microsoft describes how to set this up using Group Policy: Managing Group Policy in Azure AAD.

If the Microsoft article is not sufficiently supportive, we have made a guide that is more detailed.

Configuration Authentication Code Flow (delegated) MS Graph API [ENG]

Configuration in Squeeze

This configuration interface is provided as of version 2.3.0.

If you want to use this authentication method, make sure that the Internal job refresh-tokens is enabled. This is documented further down in the article.

As you can see now, in the configuration interface under Protocol you can choose two types of connection to Microsoft(MS) Graph API:

For the delegated authorization process we select Microsoft Graph API Delegated. In the next step we fill in the Client ID, Client Secret, Tenant ID and the rest of the fields. 

Folder - Configuration

In the folder configuration you need to specify three folders

1. Inbox
   This folder is regularly checked to import the emails it contains. 
2. Exported
   The successfully imported emails are moved to this folder.
3. Error
   The emails that could not be imported (e.g. missing attachments) are moved to this folder.

When defining the folders, please make sure that the names of the folders must be unique, because the folders are searched in the directory structure of the mailbox.
If a configured folder is not unique, this can lead to a different folder being used than the desired one. 

Configuration in AAD (Azure Active Directory)

Other necessary steps for a smooth process are the setup of an Azure Active Directory Application
with a Client Secret. The global registration of a mail service of "Dexpro" in the Azure Active Directory of the customer is not offered for the time being.

In addition, it must be ensured that the application has the following scopes. 

Unlike in the Permission for Client Credential Flow, any permission here is limited to the authorizing user.

Note: If a shared mailbox is to be accessed, the shared mailbox must be entered under Mailbox and the Application Permission Mail.Read.Write.Shared must be configured.

Remember that the shared mailbox will also be added to your Email Enabled security group if you have one set up.

Another significant difference to the Client Credential Flow is the use of a Redirect URI. 
This Redirect URI is created in the AzureActive directory under the Application in the Authentication tab:

Scheme Redirect URI: https://Ihr.vollwertiger.DomainName/api/v2/importers/email/authenticate/end

Note: A Squeeze client always requires an Azure Active Directory application with a redirect URI.
This means that you must create an application for each client.

Authorization Process Authentication Code Flow

Once you have configured your application in the AAD and entered all the necessary data in the configuration interface, you can save your configuration. 

Now another dialog box opens:

The system has saved your configuration, but you need to start the process of authentication separately using a button in the email configuration. For this purpose please select the following button:

After clicking this button, you will now be redirected to the Microsoft interface. There, the authentication process begins. Follow Microsoft's instructions:

Enter your email address.

Enter your password:

Depending on the company, you may also be asked to perform 2-factor authentication:

Once you are authenticated, you will be prompted for permissions and asked to confirm those permissions. After your confirmation, Microsoft will immediately redirect you back to the Squeeze interface. 

The interface will now show you if Squeeze is now authorized or if an error has occurred:

Now you can test the mail connection by clicking the Mail Connection Test button in the interface. 

Job-Configuration

The use of this authentication method requires that a separate job is activated, which keeps the access data for the Graph API up-to-date in the background.

For this purpose, we find the new script named refresh-tokens in the administration under "Scripts":

You can run this script manually at any time.

You need to set up a job for this script that runs frequently enough to prevent the access data from expiring. By default, refresh tokens from Microsoft are valid for 1 day, so you should try to refresh the access data several times a day.

We recommend running the job every hour:
Cron expression for the job: */50 * * * *.

How to configure jobs is documented here:

• Artikel über Job Ausführungen in Squeeze 
• Artikel über Job Steuerungen

FAQ

Übernahme von E-Mail-Feldern in Squeeze-Felder

Sofern beim Import einer E-Mail Informationen wie Absender, Empfänger, Betreff usw. ausgelesen werden sollen, müssen die entsprechenden folgenden Squeeze-Felder an der betroffenen Dokumentenklasse vorhanden sein:

Unterstützung von S/MIME

Mails können optional signiert und/oder verschlüsselt werden. Das wird üblicherweise mittels S/MIME umgesetzt.

Signaturen

Es ist aktuell nicht möglich, dass Squeeze die Signature von S/MIME-signierten Mails verifiziert.

Die Verarbeitung solcher Mails ist allerdings dennoch möglich, dabei wird die Signatur allerdings nicht verifiziert.

Zum aktuellen Zeitpunkt (August 2024 / Squeeze 2.12) ist nicht garantiert, dass alle Mails im S/MIME-Format unterstützt werden. Sollten Sie diese intensiv nutzen, melden Sie sich beim Support oder ihrem Partner, um eine Erweiterung der Unterstützung von S/MIME anzustoßen.

Verschlüsselung

Es ist aktuell nicht möglich, dass SMIME verschlüsselte Mails durch Squeeze entschlüsselt werden.