Um das Abholen und Senden von E-Mails über einen Mailserver, der eine OAuth2-Authentifizierung verlangt bzw. ermöglicht sind folgende Einstellungen notwendig.
Wichtiger Hinweis: Die aktuell in der DLE eingesetzte Mail-Bibliothek unterstützt das POP3-Protokoll nicht!
HINWEIS: In Produktivumgebungen sollten keine selbstsignierten Zertifikate verwendet werden.
Folgend eine Anleitung zur Erstellung eines selbstsignierten Zertifikats mittels Powershell.
$certname = "{certificateName}" ## Replace {certificateName}
$cert = New-SelfSignedCertificate -Subject "CN=$certname" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256 -NotAfter (Get-Date).AddYears(10)Das Zertifikat wurde nun auf dem Rechner im Zertifikatsspeicher des Benutzers abgelegt. Mit der folgenden Zeile kann das Zertifikat mit der öffentlichen Information (public key) exportiert werden. Das ist das Zertifikat, das im Azure Portal hochgeladen wird.
Export-Certificate -Cert $cert -FilePath "C:\DLE\temp\$certname.cer" Für die Verwendung in der DLE muss ein Zertifikat erstellt werden, das auch den privaten Teil (private Key) enthält. Dies kann mit folgenden Kommandos erstellt werden. Es muss das Zertifikat mit einem selbst zu wählenden Passwort geschützt werden.
$mypwd = ConvertTo-SecureString -String "{myPassword}" -Force -AsPlainText ## Replace {myPassword}
Export-PfxCertificate -Cert $cert -FilePath "C:\DLE\server\$certname.pfx" -Password $mypwd
Für die Registrierung der DLE in Azure Active Directory (AAD) muss ein Zertifikat mit privatem Schlüssel zur Verfügung stehen. Zu Testzwecken kann dieses Zerfikat selbst-signiert sein, für eine Produktiv-Umgebung sollte eine vollständige Zertifikatskette zu Grunde liegen.
Im AAD wird für die DLE eine neue "App-Registration" angelegt. Nach der Anlage kann unter "Certificates & Secrets" das öffentliche Zertifikat hochgeladen werden.
Nach der Anlage der App-Registration vergibt AAD eine Application (client) ID und eine Object ID. In der "Overview"-Ansicht sieht man auch gleich die Directory (tenant) ID. Im DLEAzureAuthenticationService in der DLESessionConfig werden die beiden Application und Directory -IDs benötigt. Die Object ID wird zusätzlich bei der Vergabe der Rechte am Exchange-Online Server benötigt.
Weiters müssen in der App-Registration der DLE-Applikation Rechte vergeben werden (Menüpunkt "API-Permissions".
Für IMAP Zugriff muss die Application folgendes Recht erhalten:
Um eine Authentifizierung zu ermöglichen sind zwei Services in der DLESessionConfig.xml-Datei einzurichten:
Das DLEAzureAuthenticationService beschreibt die Regisitrierung der DLE in AzureActiveDirectory. Zusätzlich muss der Name des Zertifikatsservices und der Scope der anzufordernden Berechtigungen angegeben werden.
<Service name="AzureAuthenticationService" class="at.visionflow.dle.packages.jwt.DLEAzureAuthenticationService">
<Properties>
<Property name="clientId" value="c8bac473-xxxx-4511-xxxx-e54e74564ccf"/>
<Property name="tenantId" value="2f782989-5c86-xxxx-a5b2-7axxxxxb671b" />
<Property name="certServiceName" value="ApiGraph_Cert_Service" />
<Property name="scope" value="https://outlook.office.com/.default" />
</Properties>
</Service>Das JWTCertificateService beschreibt den Pfad, das Passwort und die Schlüssel-ID des Zertifikats, welches zur Authentifizierung der DLE bzw. zum Signieren des JWT-Tokens verwendet wird.
<Service name="ApiGraph_Cert_Service" class="at.visionflow.dle.packages.jwt.JWTCertificateService">
<Properties>
<Property name="pfx_file" value="~/server/cert/DLE-AAD.pfx" />
<Property name="pfx_password" value="2Kt+`-\R5Dx\toD^fw4" />
<!-- determine the keyalias by using keytool(.exe) -list -keystore <pfx-filename> -->
<Property name="key_alias" value="te-cd0be2fa-57ab-4289-bf8a-01adffa2c2b6"/>
</Properties>
</Service>
Die Berechtigung auf einzelne Mailboxen kann mittels Powershell am Exchange-Online-Server vergeben werden.
Hierzu muss das Modul ExchangeOnlineManagement installiert werden. Dies kann in einer als Administator gestarteten Powershellumgebung mittels dem Befehl
Install-Module -Name ExchangeOnlineManagement -RequiredVersion 2.0.5
installiert werden. Die Versionsnummer sollte der neuesten, verfügbaren Version entsprechen.
Anschließend muss das Modul importiert werden:
Import-Module ExchangeOnlineManagement
und die Verbindung zum Exchange-Server hergestellt werden:
Connect-ExchangeOnline -UserPrincipalName thgr@vision-flow.at
Folgend wird ein ServicePrincipal (ähnlich einem User-Account) angelegt, hierzu werden die Werte aus der App-Registration im AAD benötigt:
ACHTUNG: Die Object_ID entspricht der GUID der Enterprise-Application im Azure Portal, nicht der der App-Registration
New-ServicePrincipal -AppId <CLIENT_ID> -ServiceId <OBJECT_ID> -Organization <TENANT_ID>
Die korrekte Anlage des ServicePrincipal kann mit dem Kommando
Get-ServicePrincipal -Organization <TENANT_ID> | fl
überprüft werden.
Dieser Schritt wird nun für all die Mailboxen wiederholt, auf welche die DLE Zugriff erhalten soll:
Add-MailboxPermission -Identity "test@vision-flow.at" -User <CLIENT_ID> -AccessRights FullAccess
Folgende Properties können in diesem Zusammenhang nützlich sein und können als -D Argument beim Starten der DLE oder in die startupParams.xml - Datei eingetragen werden.
Property "mail.debug" auf Wert "true", aktiviert debug-logging der Mail-Bibliothek.
Property "mail.debug.auth" auf Wert "true", aktiviert zusätzliches debug-logging der Authentifizierung der Mail-Bibliothek.
Property "mail.imaps.sasl.enable", "mail.imap.sasl.enable", "mail.pop3s.sasl.enable", "mail.pop3.sasl.enable" jeweils auf true, aktiviert SASL für das jeweilige Protokoll.