timeCard: Konfiguration SMTP über Microsoft Office 365

Ab der timeCard Version 25.03.XX können E-Mails auch über Microsoft Office 365 verschickt werden. Um Emails aus timeCard heraus mittels Office 365 versenden zu können, gehen Sie bitte nach der folgenden Anleitung vor. Hierbei müssen sowohl Einstellungen in timeCard als auch in den Verwaltungsportalen von Microsoft Office 365 gesetzt werden. Hierbei handelt es sich um die von Microsoft empfohlene Vorgehensweise. 

Folgende Einstellungen müssen vorgenommen werden:

1. App-Registrierung im EntraID-Verzeichnis
2. Geheimer Client-Schlüssel erzeugen
3. Absender für Emails auswählen oder anlegen
4. Verbindungsdaten in timeCard hinterlegen
5. EntraID App-Registrierung mit Exchange Server verbinden

Die Erstellung der hierfür  benötigten Verbindungsparameter nutzen Sie bitte die folgenden Microsoft Portale:

• https://entra.microsoft.com/
• https://admin.exchange.microsoft.com/
• https://admin.cloud.microsoft/?#/homepage

Bitte beachten Sie, dass hier für ein EntraID-Benutzer mit entsprechenden administrativen Rechten genutzt wird.

1. App-Registrierung im EntraID-Verzeichnis
   
   Zu erst muss eine App-Registrierung für "Office 365 Exchange Online" im EntraID-Verzeichnis (https://entra.microsoft.com) angelegt werden. Diese Registrierung muss dann mit dem Recht "SMTP.SendAsApp" versehen werden.
   
   
   
2. Geheimer Client-Schlüssel erzeugen
   
   Im zweiten Schritt wechseln Sie ins Menü "Zertifikate und Geheimnisse" und erstellen dort einen geheimen Client-Schlüssel. Speichern Sie diesen Wert temporär (z.B. Notepad). Bei einem erneuten Aufruf ist das Geheimnis nicht mehr verfügbar.
   
   In der Übersicht dieser Ressource finden Sie auch die beiden anderen Verbindungsparameter (Anwendungs-ID/Verzeichnis-ID). Diese müssen in Schritt 4 in timeCard eingetragen werden.
   
   
   
3. Absender für Emails auswählen oder anlegen
   
   Nun müssen Sie einen Absender für Ihre Emails im Portal auswählen oder, falls nicht vorhanden, anlegen. Um einen neuen Nutzer anzulegen, sollte ein Exchange-Administrator kontaktiert werden. Hierzu muss das Verzeichnis "SMTP" grundsätzlich gewähren. Der gewählte oder angelegte Benutzer muss eine Lizenz haben und darf per SMTP auf sein Postfach zugreifen.
   
   Ist "SMTP" nicht aktiviert, muss im Portal "https://admin.exchange.microsoft.com/ " unter "Einstellungen -> Nachrichtenfluss" der Haken bei "Deaktivierung des SMTP-AUTH-Protokolls für ihre Organisation" entfernt werden. Dieser darf nicht gesetzt werden.
   
   
   Ist "SMTP" grundsätzlich aktiviert, muss dies auch noch beim ausgewählten bzw. angelegten Benutzer aktiviert werden. Hierzu im Portal "https://admin.cloud.microsoft/:" unter "Aktive Benutzer -> Ihren Benutzer wählen -> In den Benutzereinstellungen den Reiter "E-Mail" klicken -> E-Mail-Apps verwalten" den Haken bei "Authentifiziertes SMTP" setzen.
   
   
   
   
4. Verbindungsdaten in timeCard hinterlegen

Nun müssen Sie die EntraID-Verbindungsparameter in timeCard hinterlegen. Hierzu gehen Sie unter "Allgemein -> Einstellungen -> SMTP Mailserver" setzen dort den Haken "SMTP Funktion aktiv" und wählen Sie als Authentifizierungsmethode "Office365". Dort geben Sie dann die folgenden Verbindungsparameter aus Schritt 4 des von Ihnen gewählten Absenders ein:

• Geheimer Schlüssel (Client-Secret)
• Anwendungs-ID (App-Id)
• Verzeichnis-ID (Tenant- Id)

1. EntraID App-Registrierung mit Exchange Server verbinden
   
   Um nun die Mails über Office 365 versenden zu können, muss im letzten Schritt die EntraID App-Registrierung noch mit Ihrem Exchange Server verbunden werden. Hierzu benötigen Sie eine lokale Powershell 7 Instanz auf Ihrem timeCard Server. Gehen Sie die folgenden Schritte durch um die Verbindung durchzuführen:

• Powershell öffnen und die benötigten Module importieren und installieren (1)

  Install-Module -Name ExchangeOnlineManagement
  Import-module ExchangeOnlineManagement

• Das EntraID-Verzeichnis mit einem Administratorbenutzer für dieses Verzeichnis verbinden (2)

  Connect-AzAccount -usedeviceauthentication -tenant <Verzeichnis-ID>

• Nun müssen Sie die "Id" Ihrer App-Registrierung mit dem nachfolgenden Befehl heraussuchen (3)
  
  Beachten Sie, dass "timecardsmtp" hier auch für einen beliebig von Ihnen gewählten Namen stehen kann, welchen Sie bei der App-Registrierung in der EntraID-Verwaltungskonsole vergeben haben.

  Get-AzADServicePrincipal -displayname timecardsmtp

  Nach Ausführen des Befehls müssen Sie in der Rückgabe nun den Wert für "Id" suchen und diesen vermerken.
  
   

• Verbindung zum Exchange-Online-Verzeichnis herstellen (4)

  Connect-ExchangeOnline -DelegatedOrganization  <Tenant-Id>

  
  

• Nach herstellen der Verbindung muss nun ein neues "ServicePrincipal" angelegt werden (5)

  New-ServicePrincipal -AppId <AppId der AppRegistrierung> -ObjectId <Id aus Schritt 3>
  # Hiermit prüfen, ob ServicePrincipal angelegt wurde
  Get-ServicePrincipal | fl

• Zum Schluss muss noch die Mailbox-Freigabe für den "ServicePrincipal" aus Punkt 4 und das Postfach des gewählten Users gewährt werden (6)

  Add-MailboxPermission -Identity "<gewählter Benutzer>" -User <Id aus Punkt 3>  -AccessRights FullAccess

Bevor Sie nun die Funktionalität der Konfiguration von SMTP über Microsoft Office 365 testen, sollten Sie überprüfen, ob der SMTP-Server und der zugehörige Port in Ihrer Firewall freigegeben sind.

Ist alles eingerichtet und freigegeben, können Sie nun eine Test-Email aus timeCard versenden. Kommt die Test-Email ohne Probleme im Postfach Ihrer angegebenen Emailadresse an ist die Schnittstelle richtig eingerichtet. 

Sollten Fehler auftreten finden Sie hierzu Informationen an der folgenden Stelle Informationen:

• Allgemeine Fehler, die den Verbindungsaufbau betreffen sind in den Systemmeldungen oder in den Agent-Logs "Sendmail" vermerkt
• Fehler, die beim Versenden einer Nachricht auftreten, können im Postausgang angesehen werden

Bei Fehlermeldungen und Fragen, dürfen Sie sich wie gewohnt an der REINER SCT Support wenden: suppor@reiner-sct.com.