====== Einstellungen: E-Mail über Microsoft 365 ====== MasterKey kann automatische E-Mails (z. B. Berichte und Benachrichtigungen) aus einem Postfach Ihrer eigenen Organisation in **Microsoft 365** versenden. Dazu erstellt Ihre **IT-Abteilung** eine App-Registrierung in Ihrer eigenen Microsoft 365-Umgebung, und ein Administrator trägt deren Daten in MasterKey ein. * MasterKey erhält nur das Recht, E-Mails aus dem von Ihnen gewählten Postfach zu versenden. Es wird kein Benutzerpasswort gespeichert. * Sie bestimmen selbst, aus welchem Postfach MasterKey versenden darf. * Sie können den Zugriff jederzeit widerrufen, indem Sie den geheimen Clientschlüssel oder die App-Registrierung löschen. * Da die E-Mails tatsächlich aus Ihrem eigenen Postfach versendet werden, ist kein SPF-Eintrag für MasterKey nötig, und versendete E-Mails erscheinen im Ordner //Gesendete Elemente// dieses Postfachs. Diese Seite richtet sich an Ihre IT-Abteilung (Schritte 1 bis 5) und an den MasterKey-Administrator in Ihrer Organisation (Schritte 6 und 7). Für die Schritte 1 bis 5 ist ein Konto mit der Rolle //Anwendungsadministrator// (//Application Administrator//) und für Schritt 5 //Exchange-Administrator// (//Exchange Administrator//) nötig. Rechnen Sie mit etwa 30 Minuten. ==== Auf einen Blick ==== ^ Punkt ^ Wert ^ | Art der Verbindung | App-only über Microsoft Graph (OAuth 2.0 //client credentials//); MasterKey meldet keinen Benutzer an | | Unterstützte Kontotypen | Nur Konten in diesem Organisationsverzeichnis (einzelner Mandant) | | Umleitungs-URI (Redirect-/Callback-URL) | **Nicht nötig**, leer lassen | | Berechtigungen | ''Mail.Send'' und ''Mail.ReadWrite'' (Anwendungsberechtigungen, nicht delegiert) | | Authentifizierung | Geheimer Clientschlüssel, maximal 24 Monate gültig | | SMTP AUTH | Nicht nötig, kann deaktiviert bleiben | | DNS (SPF, DKIM, DMARC) | Keine Änderung nötig; die E-Mail wird über Ihr eigenes Microsoft 365 versendet | | Ausgehender Verkehr von MasterKey | ''login.microsoftonline.com'' und ''graph.microsoft.com'' (HTTPS, Port 443) | | Daten für MasterKey | Postfachadresse, Directory (tenant) ID, Application (client) ID, Wert und Ablaufdatum des geheimen Clientschlüssels | ==== Schritt 1: Postfach wählen ==== Wählen oder erstellen Sie das Postfach, aus dem MasterKey versendet. Wir empfehlen ein **freigegebenes Postfach**, z. B. ''qualitaet@ihrefirma.de''; dafür ist keine Lizenz nötig. Sollen Antworten von Empfängern gelesen werden, wählen Sie ein Postfach, das jemand betreut. Exchange Online hat Versandlimits pro Postfach: höchstens 10.000 Empfänger pro Tag und 30 Nachrichten pro Minute. Die standardmäßige maximale Nachrichtengröße beträgt 35 MB. ==== Schritt 2: App-Registrierung erstellen ==== - Öffnen Sie das **Microsoft Entra Admin Center** (https://entra.microsoft.com) mit einem Konto mit der Rolle //Anwendungsadministrator// oder höher. - Gehen Sie zu **Identität → Anwendungen → App-Registrierungen → Neue Registrierung** (//Identity → Applications → App registrations → New registration//). - Name: z. B. ''MasterKey mail''. - Unterstützte Kontotypen: **Nur Konten in diesem Organisationsverzeichnis (einzelner Mandant)**. - Umleitungs-URI: leer lassen. MasterKey meldet keine Benutzer an, daher ist keine Callback-URL nötig. - Klicken Sie auf **Registrieren**. Notieren Sie auf der Übersichtsseite die **Verzeichnis-ID (Mandant)** und die **Anwendungs-ID (Client)** (//Directory (tenant) ID// und //Application (client) ID//). ==== Schritt 3: Berechtigungen hinzufügen ==== - Gehen Sie in der App-Registrierung zu **API-Berechtigungen → Berechtigung hinzufügen → Microsoft Graph → Anwendungsberechtigungen** (//Application permissions//). - Fügen Sie **Mail.Send** und **Mail.ReadWrite** hinzu. Kleine E-Mails versendet MasterKey in einem Schritt mit Mail.Send. Bei E-Mails mit großen Anhängen (ab etwa 3 MB) erstellt MasterKey zuerst einen Entwurf im Postfach, fügt die Anhänge einzeln hinzu und versendet dann den Entwurf; dafür ist Mail.ReadWrite nötig. MasterKey liest keine anderen E-Mails im Postfach. - Entfernen Sie die Standardberechtigung //User.Read//; sie wird nicht benötigt. Mit diesen Berechtigungen allein darf die App noch nichts: In Schritt 5 erteilen Sie die Zustimmung, vorzugsweise auf ein Postfach beschränkt. ==== Schritt 4: Geheimen Clientschlüssel erstellen ==== - Gehen Sie zu **Zertifikate & Geheimnisse → Neuer geheimer Clientschlüssel** (//Certificates & secrets → New client secret//). - Wählen Sie eine Laufzeit (maximal 24 Monate) und notieren Sie das **Ablaufdatum**. - Kopieren Sie sofort den **Wert** (//Value//) des Schlüssels. Er ist später nicht mehr sichtbar. Achtung: Verwenden Sie nicht die //Geheimnis-ID// (//Secret ID//). Behandeln Sie den Schlüssel wie ein Passwort: Versenden Sie ihn nicht per normaler E-Mail. Tragen Sie ihn am besten selbst in MasterKey ein (Schritt 6), gemeinsam mit dem MasterKey-Administrator. ==== Schritt 5: Zustimmung erteilen, auf ein Postfach beschränkt (empfohlen) ==== Mit einer normalen Administratorzustimmung darf die App aus und in **allen** Postfächern Ihrer Organisation arbeiten. Wir empfehlen, dies mit //RBAC for Applications// in Exchange Online auf das Postfach aus Schritt 1 zu beschränken. Erteilen Sie in diesem Fall **keine** Administratorzustimmung unter API-Berechtigungen (oder widerrufen Sie sie über **Unternehmensanwendungen → MasterKey mail → Berechtigungen**), denn diese Zustimmung gilt für alle Postfächer und hebt die Beschränkung auf. Führen Sie Folgendes in der **Exchange Online PowerShell** aus. Verwenden Sie die Objekt-ID der App unter **Unternehmensanwendungen** (//Enterprise applications//), nicht die unter App-Registrierungen. Install-Module ExchangeOnlineManagement # einmalig Connect-ExchangeOnline New-ServicePrincipal -AppId -ObjectId -DisplayName "MasterKey mail" New-ManagementScope -Name "MasterKey mail" -RecipientRestrictionFilter "PrimarySmtpAddress -eq 'qualitaet@ihrefirma.de'" New-ManagementRoleAssignment -App -Role "Application Mail.Send" -CustomResourceScope "MasterKey mail" New-ManagementRoleAssignment -App -Role "Application Mail.ReadWrite" -CustomResourceScope "MasterKey mail" Prüfen Sie die Beschränkung; beide Rollen müssen bei //InScope// ''True'' anzeigen. Bei jedem anderen Postfach sollte //InScope// ''False'' sein: Test-ServicePrincipalAuthorization -Identity -Resource qualitaet@ihrefirma.de Es kann bis zu 2 Stunden dauern, bis Microsoft die Berechtigungen überall übernommen hat. Weitere Postfächer können Sie später über einen angepassten Filter zulassen, z. B. eine E-Mail-aktivierte Sicherheitsgruppe: ''-RecipientRestrictionFilter "MemberOfGroup -eq ''"''. Möchten Sie die App nicht beschränken, klicken Sie unter **API-Berechtigungen** auf **Administratorzustimmung für erteilen**. Nutzt Ihre Organisation //Bedingten Zugriff für Workloadidentitäten// (//Conditional Access for workload identities//) mit einer Standortbeschränkung? Fragen Sie dann bei MasterKey die aktuellen ausgehenden IP-Adressen an und lassen Sie diese für die App ''MasterKey mail'' zu. Normale Richtlinien für bedingten Zugriff für Benutzer gelten für diese App nicht. ==== Schritt 6: Daten in MasterKey eintragen ==== Ein Administrator in MasterKey geht zu **Einstellungen → Applikation → E-Mail** und wählt als **Mailserver** **Microsoft 365**. Tragen Sie ein: * **Senden aus Postfach**: das Postfach aus Schritt 1. * **Directory (tenant) ID** und **Application (client) ID**: aus Schritt 2. * **Geheimer Clientschlüssel (Wert)**: der Wert aus Schritt 4. Nach dem Speichern wird der Schlüssel verschlüsselt gespeichert und nie wieder angezeigt; lassen Sie das Feld später leer, um den gespeicherten Schlüssel zu behalten. * **Schlüssel läuft ab am**: das Ablaufdatum aus Schritt 4. Klicken Sie auf **Speichern** und anschließend auf **Testmail senden**. MasterKey sendet dann eine Test-E-Mail an Ihre eigene E-Mail-Adresse. Schlägt das fehl, zeigt MasterKey die Meldung von Microsoft an, z. B. wenn der Schlüssel falsch ist oder die App keine Berechtigung für das Postfach hat (siehe //Häufige Meldungen//). ==== Schritt 7: Bevor der geheime Clientschlüssel abläuft ==== Ab 30 Tagen vor dem Ablaufdatum zeigt MasterKey unter **Einstellungen → Applikation → E-Mail** eine Warnung. Nach dem Ablaufdatum kann MasterKey keine E-Mails mehr versenden. Erneuern Sie den Schlüssel daher rechtzeitig: - Lassen Sie Ihre IT-Abteilung einen neuen geheimen Clientschlüssel erstellen (Schritt 4). Der alte Schlüssel bleibt bis zu seinem Ablaufdatum gültig. - Tragen Sie den neuen Wert und das Ablaufdatum in MasterKey ein, speichern Sie und senden Sie eine Testmail. - Lassen Sie danach den alten Schlüssel in Entra löschen. ==== Zugriff widerrufen ==== Sie können die Verbindung jederzeit beenden; MasterKey kann danach sofort keine E-Mails mehr aus Ihrem Postfach versenden: * löschen Sie den geheimen Clientschlüssel, oder * löschen Sie die App-Registrierung ''MasterKey mail'', oder * entfernen Sie die Berechtigungen aus Schritt 5 mit ''Remove-ManagementRoleAssignment''. Wählen Sie danach in MasterKey unter **Einstellungen → Applikation → E-Mail** einen anderen Mailserver, sonst werden keine E-Mails mehr versendet. ==== So speichert MasterKey den geheimen Clientschlüssel ==== * Der geheime Clientschlüssel wird beim Speichern sofort verschlüsselt (AES-256-GCM) und nur verschlüsselt in der MasterKey-Datenbank bei den Einstellungen Ihrer Organisation gespeichert. * Der Verschlüsselungsschlüssel liegt nicht in der Datenbank, sondern getrennt davon in einer geschützten Umgebung der MasterKey-Server. Mit einer Kopie der Datenbank allein ist der geheime Clientschlüssel also nicht lesbar. * Der geheime Clientschlüssel wird nie an den Browser zurückgesendet und erscheint nicht in Protokolldateien. * Nur der Maildienst von MasterKey entschlüsselt ihn, und nur im Moment des Versendens. ==== Häufige Meldungen ==== ^ Meldung enthält ^ Ursache ^ | AADSTS7000222 | Der geheime Clientschlüssel ist abgelaufen. Erstellen Sie einen neuen Schlüssel (Schritt 7). | | AADSTS7000215 | Der geheime Clientschlüssel ist falsch; oft wurde die //Geheimnis-ID// statt des **Werts** eingetragen. | | AADSTS700016 | Die Application (client) ID existiert in dieser Microsoft 365-Umgebung nicht. | | AADSTS90002 | Die Directory (tenant) ID existiert nicht. | | ErrorAccessDenied / AccessDenied | Die App hat keine Berechtigung für dieses Postfach (Schritt 5). Gerade geändert? Warten Sie bis zu 2 Stunden. Schlägt es nur bei großen Anhängen fehl, fehlt Mail.ReadWrite. | | ErrorInvalidUser / MailboxNotEnabledForRESTAPI / ResourceNotFound | Das Postfach existiert nicht oder ist kein Exchange Online-Postfach. | | ErrorMessageSizeExceeded | Die E-Mail ist größer, als das Postfach versenden darf. Erhöhen Sie die maximale Sendegröße des Postfachs. | Kommen Sie nicht weiter? Wenden Sie sich an den MasterKey-Support und senden Sie die vollständige Meldung mit. Senden Sie **niemals** den geheimen Clientschlüssel mit. ---- [[de:desktop:instellingen:applicatie|Zurück zu Einstellungen: Applikation]] \\ [[de:desktop:instellingen|Zurück zu Einstellungen]]