de:desktop:instellingen:microsoft365 [Masterkey]

Diese Seite ist nicht editierbar. Sie können den Quelltext sehen, jedoch nicht verändern. Kontaktieren Sie den Administrator, wenn Sie glauben, dass hier ein Fehler vorliegt.
====== 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.

<code powershell>
Install-Module ExchangeOnlineManagement   # einmalig
Connect-ExchangeOnline
New-ServicePrincipal -AppId <Anwendungs-ID (Client)> -ObjectId <Objekt-ID aus Unternehmensanwendungen> -DisplayName "MasterKey mail"
New-ManagementScope -Name "MasterKey mail" -RecipientRestrictionFilter "PrimarySmtpAddress -eq 'qualitaet@ihrefirma.de'"
New-ManagementRoleAssignment -App <Anwendungs-ID (Client)> -Role "Application Mail.Send" -CustomResourceScope "MasterKey mail"
New-ManagementRoleAssignment -App <Anwendungs-ID (Client)> -Role "Application Mail.ReadWrite" -CustomResourceScope "MasterKey mail"
</code>

Prüfen Sie die Beschränkung; beide Rollen müssen bei //InScope// ''True'' anzeigen. Bei jedem anderen Postfach sollte //InScope// ''False'' sein:

<code powershell>
Test-ServicePrincipalAuthorization -Identity <Anwendungs-ID (Client)> -Resource qualitaet@ihrefirma.de
</code>

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 '<DistinguishedName der Gruppe>'"''.

Möchten Sie die App nicht beschränken, klicken Sie unter **API-Berechtigungen** auf **Administratorzustimmung für <Ihre Organisation> 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]]