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:
- Sie müssen vollwertige E-Mails angeben, dass bedeutet Sie müssen immer ganze Email-Adressen angeben ansonsten schlägt der Speichervorgang fehl
- Um eventuell mehrere Passwörter einer E-Mail zuzuordnen legen Sie einfach mehrere Einträge an.
- 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:
Prioritäten | Beispiel |
Erste Priorität | spezifscher Sender(support@dexpro.de) + spezifisches Dateimuster(Rechnung.pdf) |
Zweite Priorität | spezifische Domäne(dexpro.de) + unspezifisches Dateimuster (*.pdf) |
usw. | - |
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:
Name | Beschreibung | Bedeutung |
id | ID | Eindeutige technische ID |
batchclassid |
Stapelklassen ID | ID der Stapelklasse für die die Regel definiert wird |
sender | Sender | Absender der Email (Wildcards erlaubt) |
filenamepattern | Dateimuster | Dateinamenfilter (Wildcards erlaubt) |
type | Typ | Relevantes Dokument für die Extraktion oder begleitende Anlage |
singledocument | Einzeldokument | Kennzeichen, ob die Datei ein eigenständiges Dokument werden soll (X) |
newbatchclassid | Neue Stapelklassen ID | Sofern das Dokument in eine andere Stapelklasse verschoben werden soll, ist hier die Stapelklassen-ID der neuen Stapelklasse anzugeben. |
newdocumentclassid | Neue Dokumentenklassen ID |
Sofern auch eine neue Dokumentenklasse gesetzt werden soll, ist hier die ID der Dokumentenklasse anzugeben. |
Beispiel-Konfigurationen
Beispiel
ID | Stapel-klasse | Sender | Muster | Typ | Einzel-Dokument | neue Stapelklasse |
neue Dokumentenklasse |
1 | 1 | * | D | ||||
2 | 1 | * | AGB.pdf | A | |||
3 | 1 | dexpro.de | INV*.pdf | D | X | ||
4 | 1 | payment@dexpro.de | Avis*.pdf | D | X | 2 | 2 |
5 | 1 | dexpro.de | *.xml | A | |||
6 | 1 | invoice@squeeze.one | *.xml | D | |||
7 | 1 | invoice@squeeze.one | A |
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.
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):
- Whitelist Prüfung: Absender der E-Mail wird mittels Whitelist geprüft.
- 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ürhans@dexpro.de
oderhanna@dexpro.de
someone@dexpro.*.de
fürsomeone@dexpro.beispiel.de
odersomeone@dexpro.anderes.beispiel.de
department.*@dexpro.de
fürdepartment.vertrieb@dexpro.de
oderdepartment.entwicklung@dexpro.de
*@dexpro.*
fürhans@dexpro.de
oderhans.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
- Azure-Active-Directory(AAD)
- das EXO-V2 Moduler Powershell 7 in der Version 2.0.4 oder höher.
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
- Posteingang
Dieser Ordner wird regelmäßig überprüft, um die enthaltenen Emails zu importieren. - Verarbeitet
In diesen Ordner werden die erfolgreich importieren Emails verschoben. - 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
- Posteingang
Dieser Ordner wird regelmäßig überprüft, um die enthaltenen Emails zu importieren. - Verarbeitet
In diesen Ordner werden die erfolgreich importieren Emails verschoben. - 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.
Wir empfehlen den Job jede Stunde auszuführen:
Cron-Ausdruck für den Job: */50 * * * *
Wie Jobs zu konfigurieren sind, ist hier dokumentiert:
Fragen und Antworten
Was passiert wenn der Job ausfällt ? |
Ist der Job durch unvorhersehbare Gründe nicht gelaufen so müssen Sie sich neu Authentifizieren mit dem Authentifizierung-Button in der Email-Konfiguration |
Kann ich einfach meine Postfach in der Konfiguration ändern und muss ich danach was tun ? |
Sobald Sie die Konfiguration ändern oder abspeichern, weist die Anwendung Sie darauf hin, ein neuen Authentifizierungsprozess einzuleiten. Lehnen Sie dieses Aufforderung ab, haben Sie immer noch die Möglichkeit den Authentifizierungsbutton zu betätigen. |
Kann ich meine Entra ID Applikation für mehrere Squeeze Mandanten nutzen ? |
Nein, die Verwendung einer Entra ID Applikation für mehrere Mandanten ist nicht Möglich, solange die Mandanten unter anderen Domänen erreichbar sind. test.mandant.squeeze.one
2 Mandant: test2.mandant.squeeze.one
In diesem Beispiel kann man keine Application verwenden, da wir pro Application nur einen Mandanten ansprechen können. Ein Authentifizierung bei Microsoft würde ggf. immer nur auf einen Mandanten laufen.
Du hast die Möglichkeit mehrere Postfächer mit der selben Applikation zu nutzen, dort gibt es keine Begrenzungen.
|
Meine Zugriff durch die AzureTokens laufen ständig ab, obwohl ich den Job richtig konfiguriert habe. |
Es kann vorkommen, dass die Server Zeit und die konfigurierte Zeit der Squeeze Applikation sich unterscheiden. Squeeze Zeit: UTC (UTC +0)
In diesem Fall werden die Tokens, die erzeugt wurden, in CEST abgespeichert. Wenn in diesem Fall die Squeeze Applikation nun prüft, ob ein Token erneuert werden muss, dann wird diese in diesem Fall den Token als noch nicht abgelaufen ansehen, da der Token in der Annahme von Squeeze gültig ist.
Sollten Sie diese Version noch nicht besitzen, versuchen Sie die Serverzeit mit der Applikationszeit zu synchronisieren. |
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
- Inbox
This folder is regularly checked to import the emails it contains. - Done
The successfully imported emails will be moved to this folder. - 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
- Inbox
This folder is regularly checked to import the emails it contains. - Exported
The successfully imported emails are moved to this folder. - 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:
FAQ
What happens if the job fails? |
If the job did not run due to unforeseen reasons you have to re-authenticate using the authentication button in the email configuration. |
Can I just change my mailbox in the configuration and do I have to do anything after that? |
As soon as you change or save the configuration, the application prompts you to initiate a new authentication process. Reject this request. You still have the option to press the authentication button. |
Can I use my Azure Active Directory Application for multiple Squeeze clients? |
No, using one Application (AAD) for multiple clients is not possible as long as the clients are accessible under other domains. test.client.squeeze.one
test2.client.squeeze.one
In this example we cannot use an application, because we can only address one client per application. Authentication with Microsoft would only run on one client at a time.
You have the possibility to use multiple mailboxes with the same application (AAD), there are no limits.
|
My access through AzureTokens constantly expires, even though I have configured the job correctly. |
In this case the server time configuration and the time configuration of the Squeeze application might differ.
Example: Server Time: CEST (UTC +2) Squeeze Time: UTC (UTC +0)
In this case, the tokens that were generated are stored in CEST. If, in this scenario, the Squeeze application checks whether a token needs to be refreshed, the application will consider the token as not yet expired because it assumes the token is valid in the context of Squeeze.
This is because Squeeze checks the token in the past with UTC +0, but the token was issued with CEST (UTC +2). Therefore, the token has already expired in CEST but not in UTC, which Squeeze checks for.
The problem has been fixed in version 2.5. if you don't have this version yet, try to synchronize the server time with the application time.
This can be done by configuring the date.timezone in the php.ini.
See: https://www.php.net/manual/en/datetime.configuration.php
|
Ü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:
Name des anzulegenden Squeeze-Feldes | Information der Mail |
EmailReceivedDate |
Empfangsdatum |
EmailFromAddress |
Absender-Mail-Adresse |
EmailFromName |
Absender-Name |
EmailToAddress |
Empfänger |
EmailMailBoxUser | Postfach (aus dem die Mail abgeholt wurde) |
EmailSubject |
Betreff |
EmailMessageId |
ID der Nachricht |
EmailImportFolder |
Import-Ordner |
EmailProcessedFolder |
Verarbeitet-Ordner |
EmailInvalidFolder |
Fehler-Ordner |
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.