Konfigurationsoptionen für das REST-API-Protokoll für Office 365 Message Trace

Das Protokoll der Office 365 Message Trace REST-API für „ IBM® Security“ ( QRadar® ) erfasst Nachrichtenverfolgungsprotokolle aus der Microsoft Message Trace REST-API. Dieses aktive abgehende Protokoll wird verwendet, um Office 365-E-Mail-Protokolle zu erfassen.

Wichtig: Ab dem 1. Januar 2023 unterstützt Microsoft die Basisauthentifizierung nicht mehr. Um weiterhin Nachrichten-Trace-Ereignisse zu empfangen, müssen Sie die moderne Authentifizierung verwenden. Die moderne Authentifizierung nutzt OAuth 2.0 zur Authentifizierung und Autorisierung des Zugriffs auf die Veranstaltungen. Weitere Informationen zur Einstellung der Basisauthentifizierung finden Sie unter „Einstellung der Basisauthentifizierung in Exchange Online – Update vom September 2022 “ ( https://techcommunity.microsoft.com/t5/exchange-team-blog/basic-authentication-deprecation-in-exchange-online-september/ba-p/3609437 ).

Wichtig: Microsoft hat angekündigt, dass der veraltete Webdienst für die Nachrichtenverfolgungsberichte in Microsoft Exchange Online ab dem 18. März 2026 nicht mehr unterstützt wird. Um die Kompatibilität mit dieser Änderung zu gewährleisten, wurde die IBM QRadar Message-Trace-Integration in aktualisiert, sodass nun die neue Message-Trace-API verwendet wird. Sie müssen auf die neueste Protokollversion aktualisieren, um weiterhin Message-Trace-Ereignisse zu empfangen. Wenn Sie vor der Abkündigung kein Upgrade durchführen, kann dies dazu führen, dass keine Message-Trace-Protokolle mehr erfasst werden. Weitere Informationen finden Sie unter „Ankündigung der allgemeinen Verfügbarkeit (GA) der neuen Nachrichtenverfolgung in Exchange Online“ ( https://techcommunity.microsoft.com/blog/exchange/announcing-general-availability-ga-of-the-new-message-trace-in-exchange-online/4420243 ).

Ausnahme für Kunden der Tarife „GCC“, „GCC-High“, „ DoD, “ und „Sovereign Cloud“:

Die neue Message Trace API ist derzeit nur für weltweite (WW) Umgebungen verfügbar. Wie Microsoft mitteilt: „Bitte beachten Sie, dass dieser Zeitplan ausschließlich für unsere WW-Umgebung gilt und keine Auswirkungen auf GCC, GCC-High, DOD oder andere staatliche Clouds hat.“ „Ein Zeitplan für GCC, GCC-High, DoD, und andere staatliche Clouds wird unter CY25H2 bereitgestellt.“

Wenn Sie Kunde der Tarife „GCC“, „GCC-High“, „ DoD, “ oder „Sovereign Cloud“ sind, müssen Sie weiterhin die folgenden RPM-Versionen verwenden:

Protokoll: 7.5.0-QRADAR-PROTOCOL-Office365MessageTraceRESTAPI-7.5-20250213060632.noarch.rpm
DSM: 7.5.0-QRADAR-DSM-MicrosoftOffice365MessageTrace-7.5-20260113065949.noarch.rpm

Führen Sie kein Upgrade auf neuere Versionen durch, bis Microsoft offiziell die Unterstützung für „ MessageTraceV2 “ für Ihre Cloud-Umgebung veröffentlicht hat.

Um automatische Updates zu verhindern, gehen Sie zu „Automatische Updates“ und wählen Sie „Nach Updates suchen “. Sollten neuere RPMs für „ MessageTrace “ erscheinen, markieren Sie diese und wählen Sie die Option, diese Updates auszublenden.

Die moderne Authentifizierung ist standardmäßig ausgewählt, da die Basisauthentifizierung entfernt wurde und nicht mehr verfügbar ist. Um die moderne Authentifizierung zu nutzen, müssen Sie eine Anwendung im Microsoft Entra Admin Center ( https://entra.microsoft.com/ ) registrieren. Das Portal stellt die wichtigen Werte bereit, die zum Erstellen einer Protokollquelle für die Microsoft Message Trace API erforderlich sind.

Registrieren Sie eine App in der Microsoft-Identitätsplattform. Eine Schritt-für-Schritt-Anleitung finden Sie unter „Anwendung bei der Microsoft Identity Platform registrieren“ ( https://learn.microsoft.com/en-us/graph/auth-register-app-v2 ).
Rufen Sie die Werte Client-ID, Tenant-IDund Geheimer Clientschlüssel ab.
1. Suchen Sie auf der Seite Übersicht der Anwendung die Werte für Client-ID und Tenant-ID und kopieren Sie sie. Sie verwenden diese Werte, wenn Sie eine Microsoft Office 365 Message Trace-Protokollquelle erstellen. Weitere Informationen finden Sie unter „Tenant- und App-ID-Werte für die Anmeldung abrufen“ ( https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#sign-in-to-the-application ).
2. Klicken Sie auf der Seite Zertifikate und geheime Schlüssel der Anwendung auf Neuer geheimer Schlüssel , um den geheimen Clientschlüssel zu erstellen. Kopieren Sie dann den geheimen Clientschlüssel in einen Texteditor. Sie verwenden diesen Wert für den Parameter Client Secret , wenn Sie eine Microsoft Office 365 Message Trace-Protokollquelle erstellen. Weitere Informationen finden Sie unter „Neues Client-Geheimnis erstellen“ ( https://learn.microsoft.com/en-us/graph/auth-register-app-v2#option-2-add-a-client-secret ).
Erteilen Sie Ihrer Anwendung in Microsoft Entra ID die erforderlichen Anwendungsberechtigungen. Die erforderliche Berechtigung für Ereignisse der Message-Trace-API lautet „ ExchangeMessageTrace “. Read.All. Weitere Informationen finden Sie unter „Microsoft Graph-Berechtigungen konfigurieren“ ( https://learn.microsoft.com/en-us/exchange/monitoring/trace-an-email-message/graph-api-message-trace#configure-microsoft-graph-permissions ).
Richten Sie einen Dienstprinzipal in Ihrem Mandanten ein. Weitere Informationen finden Sie unter „Bereitstellen eines Dienstprinzipals“ ( https://learn.microsoft.com/en-us/exchange/monitoring/trace-an-email-message/graph-api-message-trace#provision-a-service-principal ).
Hinweis: Nach der Erstellung des Dienstprinzipals kann die Bereitstellung mehrere Stunden dauern. Während dieser Zeit können Anfragen an die API zur graphbasierten Nachrichtenverfolgung den Fehlercode 401 (Nicht autorisiert) zurückgeben.
```
Service principal-less authentication failed: The service principal for App ID 8bd644d1-64a1-4d4b-ae52-2e0cbf64e373 was not found.
Please create a service principal for this app in your tenant. Provisioning may take several hours to complete.
```

Wichtig: Dieses Protokoll unterstützt den Abruf von historischen Daten für maximal 30 Tage. Der Zeitraum für den Abruf historischer Daten wird rückwärts vom aktuellen Zeitstempel berechnet und um den konfigurierten Parameter für die Ereignisverzögerung angepasst. Genauer gesagt ruft das Protokoll Nachrichten-Trace-Daten der letzten 30 Tage ab, beginnend mit {current_timestamp - event_delay} und zurückreichend bis 30 Tage vor diesem Zeitpunkt.

Die folgenden Parameter müssen bestimmte Werte enthalten, damit Ereignisse über die Microsoft Message Trace REST-API erfasst werden können:

Tabelle 1 Protokollquellenparameter für das Office 365 Message Trace-REST-API-Protokoll
Parameter	Wert
Log Source Identifier (Protokollquellenkennung)	Ein eindeutiger Name für die Protokollquelle. Der Name darf keine Leerzeichen enthalten und muss unter allen Protokollquellen dieses Typs, die mit dem REST-API-Protokoll von Office 365 Message Trace konfiguriert sind, eindeutig sein.
Authentifizierungsmethode	Bei der modernen Authentifizierung wird OAuth 2.0 verwendet, um den Zugriff auf die Ressource zu authentifizieren und zu autorisieren. Die Basisauthentifizierung verwendet den Benutzernamen und das Kennwort. Da die Basisauthentifizierung entfernt wurde, ist dies die einzige verfügbare Methode, um Ereignisse für die Microsoft Message Trace API abzurufen. Diese Methode ist standardmäßig ausgewählt. Wichtig: Ab dem 1. Januar 2023 unterstützt Microsoft die Basisauthentifizierung nicht mehr. Um weiterhin Nachrichten-Trace-Ereignisse zu empfangen, müssen Sie die moderne Authentifizierung verwenden.
Client ID	Der Wert für die Client-ID aus Ihrer Anwendungskonfiguration unter Microsoft AzureActive Directory. Weitere Informationen finden Sie unter „Bei der Anwendung anmelden“ ( https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#sign-in-to-the-application ).
Clientschlüssel	Das Client-Geheimnis, das Sie für Ihre Anwendung im Portal „ Microsoft Azure “ erstellt haben. Weitere Informationen finden Sie unter „Neues Client-Geheimnis erstellen“ ( https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#option-3-create-a-new-client-secret ).
Tenant-ID	Der Wert für die Mandanten-ID, der für die Authentifizierung unter Microsoft Azure Active Directory verwendet wird. Weitere Informationen finden Sie unter „Bei der Anwendung anmelden“ ( https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#sign-in-to-the-application ).
Ereignisverzögerung	Die Verzögerung für die Datenerfassung in Sekunden. Microsoft Message Trace-Protokolle basieren auf einem System der eventuellen Zustellung. Um sicherzustellen, dass keine Daten übersehen werden, werden Protokolle mit einer Verzögerung erfasst. Die Standardverzögerung beträgt 900 Sekunden (15 Minuten) und kann auf 0 Sekunden festgelegt werden.
Proxy verwenden	Wenn auf die API über einen Proxy zugegriffen wird, wählen Sie dieses Markierungsfeld aus. Konfigurieren Sie die Felder Proxy Server, Proxy Port, Proxy Usernameund Proxy Password . Wenn der Proxy keine Authentifizierung erfordert, können Sie die Felder Proxy-Benutzername und Proxy-Kennwort leer lassen.
Erweiterte Optionen aktivieren	Wählen Sie diese Option aus, um die Standardwerte für die Microsoft-API-Anmeldungsendpunkt- und URL zu ändern. Wenn Sie diesen Parameter nicht aktivieren, werden die Standardwerte verwendet.
Microsoft-API-Anmeldeendpunkt	Geben Sie den Microsoft API-Anmeldeendpunkt an. Der Standardwert ist `https://login.microsoftonline.com` für die Authentifizierung über OAuth 2.0. Wenn Sie den Parameter Erweiterte Optionen aktivieren nicht aktivieren, wird der Standardwert verwendet.
Microsoft Graph API Management URL	Über diesen Link URL erhält Ihr Token Zugriff auf die Microsoft Graph-API. Der Standardwert für den Zugriff auf `https://graph.microsoft.com` die Message-Trace-API lautet Wenn Sie den Parameter Erweiterte Optionen aktivieren nicht aktivieren, wird der Standardwert verwendet.
Wiederholung	Das Zeitintervall zwischen den Abfragen der Protokollquelle an die Microsoft Message Trace REST-API nach neuen Ereignissen. Das Zeitintervall kann in Stunden (H), Minuten (M) oder Tagen (D) angegeben werden. Die Standardeinstellung ist 5 Minuten.
EPS-Regulierung	Die maximale Anzahl von Ereignissen pro Sekunde, die QRadar einpflegt. Wenn Ihre Datenquelle die EPS-Regulierung überschreitet, wird die Datenerfassung verzögert. Die Daten werden weiterhin erfasst und dann aufgenommen, wenn die Datenquelle die EPS-Regulierung nicht mehr überschreitet. Der Standardwert ist 5000.

Zugriffsberechtigung und Berechtigung zum Lesen von Message-Trace-Berichten

Wenn die Fehlermeldung „Status Code: 401 | Status Reason: Unauthorized„Überprüfen Sie die folgenden Konfigurationsanforderungen für den Zugriff auf Message-Trace-Daten über die Microsoft Graph-API:

Stellen Sie sicher, dass die Anwendung in Microsoft Entra ID registriert ist.
Stellen Sie sicher, dass die Anwendung für die Anwendungsauthentifizierung konfiguriert ist ( OAuth 2.0 ).
Stellen Sie sicher, dass für die registrierte Anwendung ein Dienstprinzipal ( https://learn.microsoft.com/en-us/exchange/monitoring/trace-an-email-message/graph-api-message-trace#provision-a-service-principal ) für Exchange Online bereitgestellt wird.
Hinweis: Nach der Erstellung des Dienstprinzipals kann die Bereitstellung mehrere Stunden dauern. Während dieser Zeit können Anfragen an die API zur graphbasierten Nachrichtenverfolgung den Fehlercode 401 (Nicht autorisiert) zurückgeben.
```
Service principal-less authentication failed: The service principal for App ID 8bd644d1-64a1-4d4b-ae52-2e0cbf64e373 was not found.
Please create a service principal for this app in your tenant. Provisioning may take several hours to complete.
```
Stellen Sie sicher, dass die Anwendung über die erforderlichen Microsoft Graph-Berechtigungen verfügt, um auf Message Trace-Daten zugreifen zu können.
Stellen Sie sicher, dass die erforderlichen Berechtigungen vom Administrator erteilt wurden.

Weitere Informationen zur erforderlichen Einrichtung und Konfiguration finden Sie im Einführungsleitfaden zur graphbasierten Message-Trace-API ( https://learn.microsoft.com/en-us/exchange/monitoring/trace-an-email-message/graph-API-message-trace ).

Überprüfen Sie außerdem die Richtlinien für den bedingten Zugriff, um sicherzustellen, dass die Anwendung oder der Benutzer auf Microsoft Graph zugreifen kann:

Weitere Informationen zum Blockieren und Entsperren von älteren Inhalten in Richtlinien für den bedingten Zugriff finden Sie unter „Bedingter Zugriff: Ältere Authentifizierungsmethoden blockieren“ ( https://docs.microsoft.com/en-us/azure/active-directory/conditional-access/howto-conditional-access-policy-block-legacy ).
Weitere Informationen zum Erstellen von Richtlinien für den bedingten Zugriff für Benutzer und Gruppen finden Sie unter „Bedingter Zugriff: Benutzer und Gruppen“ ( https://docs.microsoft.com/en-us/azure/active-directory/conditional-access/concept-conditional-access-users-groups ).
Weitere Informationen zum Erstellen von Richtlinien für den bedingten Zugriff auf Cloud-Apps oder -Aktionen finden Sie unter „Bedingter Zugriff: Cloud-Apps oder -Aktionen“ ( https://docs.microsoft.com/en-us/azure/active-directory/conditional-access/concept-conditional-access-cloud-apps ).