Autorisierung und die Sicherheits-API in Microsoft Graph

Sicherheitsdaten, auf die über die Microsoft Graph-Sicherheits-API zugegriffen werden kann, sind vertraulich und durch Berechtigungen und Microsoft Entra Rollen geschützt.

Die Sicherheits-API in Microsoft Graph unterstützt zwei Arten von Autorisierung:

• Autorisierung auf Anwendungsebene: Es gibt keinen angemeldeten Benutzer (z. B. ein SIEM-Szenario). Die Berechtigungen, die der Anwendung gewährt wurden, bestimmen die Autorisierung.

  Hinweis

  Diese Option kann auch Fälle unterstützen, in denen die rollenbasierte Zugriffssteuerung (RBAC) von der Anwendung verwaltet wird.

• Vom Benutzer delegierte Autorisierung: Ein Benutzer, der Mitglied des Microsoft Entra Mandanten ist, ist angemeldet. Der Benutzer muss Mitglied einer Microsoft Entra ID Rolle "Eingeschränkte Admin" sein – entweder Sicherheitsleseberechtigter oder Sicherheitsadministrator – zusätzlich dazu, dass der Anwendung die erforderlichen Berechtigungen erteilt wurden.

Wenn Sie die Sicherheits-API in Microsoft Graph aus Graph Explorer aufrufen:

• Der Microsoft Entra Mandantenadministrator muss explizit die Zustimmung für die angeforderten Berechtigungen für die Graph Explorer-Anwendung erteilen.

• Der Benutzer muss Mitglied der Rolle "Sicherheitsleseberechtigter eingeschränkt" Admin in Microsoft Entra ID sein (entweder Sicherheitsleseberechtigter oder Sicherheitsadministrator).

  Hinweis

  Graph Explorer unterstützt keine Autorisierung auf Anwendungsebene.

Wenn Sie die Sicherheits-API in Microsoft Graph aus einer benutzerdefinierten oder Ihrer eigenen Anwendung aufrufen:

• Der Microsoft Entra Mandantenadministrator muss Ihrer Anwendung explizit seine Zustimmung erteilen. Dies ist sowohl für die Autorisierung auf Anwendungsebene als auch für benutzerdelegierte Autorisierung erforderlich.
• Wenn Sie die vom Benutzer delegierte Autorisierung verwenden, muss der Benutzer Mitglied der Rolle "Sicherheitsleseberechtigter" oder "Sicherheitsadministrator eingeschränkt" Admin in Microsoft Entra ID sein.

Verwalten der Autorisierung in Sicherheits-API-Clientanwendungen

Über die Sicherheits-API in Microsoft Graph bereitgestellte Sicherheitsdaten sind vertraulich und müssen durch entsprechende Authentifizierungs- und Autorisierungsmechanismen geschützt werden. Die folgende Tabelle enthält die Schritte zum Registrieren und Erstellen einer Clientanwendung, die auf die Sicherheits-API in Microsoft Graph zugreifen kann.

Wer?	Aktion
Anwendungsentwickler oder -besitzer	Registrieren Sie die Anwendung als eine Enterprise-Anwendung.
Mandantenadministrator	Gewähren Sie Ihrer Anwendung entsprechende Berechtigungen.
Mandantenadministrator	Zuweisen von Benutzerrollen.
Anwendungsentwickler	Melden Sie sich als Benutzer an, und verwenden Sie die Anwendung, um auf die Sicherheits-API in Microsoft Graph zuzugreifen.

Die Registrierung der Anwendung definiert nur, welche Berechtigungen die Anwendung zum Ausführen braucht. Sie gewährt der Anwendung KEINE Berechtigungen.

Der Microsoft Entra Mandantenadministrator MUSS der Anwendung explizit berechtigungen erteilen. Dies muss pro Mandant erfolgen und muss jedes Mal durchgeführt werden, wenn die Anwendungsberechtigungen im Anwendungsregistrierungsportal geändert werden.

Angenommen, Sie verfügen über eine Anwendung, zwei Microsoft Entra Mandanten, T1 und T2, und zwei Berechtigungen, P1 und P2. Der Autorisierungsprozess sieht folgendermaßen aus:

• Die Anwendung registriert sich, um Berechtigung P1 anzufordern.

• Wenn Benutzer im Mandanten T1 ein Microsoft Entra Token für diese Anwendung erhalten, enthält das Token keine Berechtigungen.

• Der Microsoft Entra Administrator des Mandanten T1 erteilt der Anwendung explizit Berechtigungen. Wenn Benutzer in Mandant T1 ein Microsoft Entra Token für die Anwendung erhalten, enthält es die Berechtigung P1.

• Wenn Benutzer im Mandanten T2 ein Microsoft Entra Token für die Anwendung erhalten, enthält das Token keine Berechtigungen, da der Administrator des Mandanten T2 der Anwendung noch keine Berechtigungen erteilt hat. Berechtigung müssen pro Mandant und pro Anwendung erteilt werden.

• Die Anwendung hat ihre Registrierung geändert, sodass sie jetzt die Berechtigungen P1 und P2 erfordert.

• Wenn Benutzer in Mandant T1 ein Microsoft Entra Token für die Anwendung erhalten, enthält es nur die Berechtigung P1. Einer Anwendung erteilte Berechtigungen werden als Momentaufnahmen dessen aufgezeichnet, was erteilt wurde; Sie ändern sich nicht automatisch, nachdem sich die Anwendungsregistrierung (Berechtigung) geändert hat.

• Der Administrator des Mandanten T2 erteilt Berechtigungen P1 und P2 für die Anwendung. Wenn Benutzer im Mandanten T2 nun ein Microsoft Entra Token für die Anwendung erhalten, enthält das Token die Berechtigungen P1 und P2.

  Hinweis

  Die Microsoft Entra Token für die Anwendung in Mandant T1 und die Anwendung im Mandanten T2 enthalten unterschiedliche Berechtigungen, da jeder Mandantenadministrator der Anwendung unterschiedliche Berechtigungen erteilt hat.

• Damit die Anwendung erneut in Mandant T1 funktioniert, muss der Administrator des Mandanten T1 explizit die Berechtigungen P1 und P2 für die Anwendung erteilen.

Registrieren einer Anwendung beim Microsoft Identity Platform-Endpunkt

Zum Registrieren einer Anwendung beim Microsoft Identity Platform-Endpunkt benötigen Sie Folgendes:

• Anwendungsname: Eine Zeichenfolge, die für den Anwendungsnamen verwendet wird.
• Umleitungs-URL: Die URL, an die die Authentifizierungsantwort von Microsoft Entra ID gesendet wird. Um zu beginnen, können Sie die Homepage der Test Client Web App verwenden.
• Erforderliche Berechtigungen: Die Berechtigungen, die Ihre Anwendung benötigt, um Microsoft Graph aufrufen zu können.

So registrieren Sie Ihre Anwendung

1. Wechseln Sie zum Azure App-Registrierungsportal, und melden Sie sich an.

   Hinweis

   Sie müssen kein Mandantenadministrator sein. Sie werden zur Liste Meine Bewerbungen weitergeleitet.

2. Wählen Sie Neue Registrierung aus.

3. Geben Sie auf der Registrierungsseite für die neue Anwendung einen Wert für Name ein, und wählen Sie die Kontotypen aus, die unterstützt werden sollen. Geben Sie im Feld Umleitungs-URI die Umleitungs-URL ein.

4. Wählen Sie Registrieren aus, um die App zu erstellen und ihre Übersichtsseite anzuzeigen. *

5. Navigieren Sie zur Seite API-Berechtigungen der App.

6. Wählen Sie Berechtigung hinzufügen und dann im Flyout die Option Microsoft Graph aus. Wählen Sie Delegierte Berechtigungen aus. Verwenden Sie das Suchfeld, um die erforderlichen Berechtigungen zu suchen und auszuwählen. Eine Liste von Berechtigungen finden Sie unter Sicherheitsberechtigungen.

   Hinweis

   Die Microsoft Graph-Sicherheits-API erfordert den Bereich *.Read.All für GET-Abfragen und den Bereich *.ReadWrite.All für PATCH/POST/DELETE-Abfragen.

   Berechtigung	Entität	Unterstützte Anforderungen
   SecurityActions.Read.All	• securityActions (Vorschau)	GET
   SecurityActions.ReadWrite.All	• securityActions (Vorschau)	GET, POST
   SecurityEvents.Read.All	• Warnungen • secureScores • secureScoreControlProfiles	GET
   SecurityEvents.ReadWrite.All	• Warnungen • secureScores • secureScoreControlProfiles	GET, POST, PATCH
   ThreatIndicators.ReadWrite.OwnedBy	• tiIndicator (Vorschau)	GET, POST, PATCH, DELETE

7. Wählen Sie Berechtigungen hinzufügen aus.

Speichern Sie die folgenden Informationen:

• Anwendungs-ID (Client-ID)
• Umleitungs-URL
• Liste der erforderlichen Berechtigungen

*Windows Defender Advanced Threat Protection (WDATP) erfordert zusätzliche Benutzerrollen, die vom Microsoft Graph-Sicherheits-API benötigt werden. Daher können nur die Benutzer in den Rollen WDATP und Microsoft Graph Sicherheits-API Auf die WDATP-Daten zugreifen. Die Nur-Anwendung-Authentifizierung ist hierbei nicht eingeschränkt. Deshalb empfiehlt es sich, ein Nur-App-Authentifizierungstoken zu verwenden.

Weitere Informationen finden Sie unter Registrieren Ihrer App bei Microsoft Identity Platform.

Gewähren von Berechtigungen für eine Anwendung

Die Anwendungsregistrierung definiert nur, welche Berechtigung die Anwendung erfordert; Diese Berechtigungen werden der Anwendung nicht erteilt. Ein Microsoft Entra Mandantenadministrator muss diese Berechtigungen explizit erteilen, indem er den Endpunkt für die Administratoreinwilligung aufruft. Einzelheiten hierzu finden Sie unter Verwenden des Endpunkts für die Administratorzustimmung.

Um einer Anwendung Berechtigungen zu gewähren, brauchen Sie:

• Anwendungs-ID: Die Anwendungs-ID aus dem Azure-Anwendungsregistrierungsportal.
• Umleitungs-URL: Die Zeichenfolge, die Sie im Azure-Anwendungsregistrierungsportal für die Authentifizierungsantwort festgelegt haben.

So gewähren Sie Berechtigungen

• Erstellen Sie in einem Texteditor die folgende URL-Zeichenfolge:

  https://login.microsoftonline.com/common/adminconsent?client_id=<Application Id>&state=12345&redirect_uri=<Redirect URL>

• Rufen Sie in einem Webbrowser diese URL auf, und melden Sie sich als Mandantenadministrator an. Das Dialogfeld zeigt die Liste der Berechtigungen, die die Anwendung erfordert, wie im App-Registrierungsportal eingegeben. Wählen Sie OK, um der Anwendung diese Berechtigungen zu erteilen.

  Hinweis

  Dieser Schritt gewährt Berechtigungen für die Anwendung, nicht für Benutzer. Dies bedeutet, dass allen Benutzern, die zum Microsoft Entra Mandanten gehören, die diese Anwendung verwenden, diese Berechtigungen gewährt werden – auch Benutzer ohne Administratorrechte.

Zuweisen von Microsoft Entra Rollen zu Benutzern

Nachdem einer Anwendung Berechtigungen erteilt wurden, erhält jeder Benutzer mit Zugriff auf die Anwendung (d. h. Mitglieder des Microsoft Entra Mandanten) die gewährten Berechtigungen. Um sensible Sicherheitsdaten weiter zu schützen, erfordert das Microsoft Graph-Sicherheits-API benutzern auch die Rolle "Microsoft Entra ID Sicherheitsleseberechtigter". Weitere Informationen finden Sie unter Administratorrollenberechtigungen in Microsoft Entra ID und Zuweisen von Administrator- und Nicht-Administratorrollen zu Benutzern mit Microsoft Entra ID.

Hinweis

Sie müssen ein Mandantenadministrator sein, um diesen Schritt auszuführen.

So weisen Sie einem Benutzer eine Rolle zu

1. Melden Sie sich beim Microsoft Entra Admin Centeran.
2. Erweitern Sie das Menü >Identität, erweitern Sie Benutzer> und wählen Sie Alle Benutzer aus.
3. Wählen Sie den Benutzer aus.
4. Wählen Sie Zugewiesene Rollen und dann Zuweisung hinzufügen aus.
5. Wählen Sie Sicherheitsleseberechtigter aus, und klicken Sie auf Hinzufügen.

Erstellen eines Authentifizierungscodes

Um einen Authentifizierungscode zu erstellen, brauchen Sie:

• Anwendungs ID: Die Anwendungs-ID aus dem Anwendungsregistrierungsportal.
• Umleitungs-URL: Die URL, an die die Authentifizierungsantwort von Microsoft Entra ID gesendet wird. Zum Beginnen können Sie https://localhost oder die Homepage der Test Client Web App verwenden.
• Anwendungsschlüssel (optional): Der Schlüssel der Anwendung. Dies gilt, wenn Sie eine Anwendung entwickeln, die Nur-App-Authentifizierungscodes verwendet (d. h. delegierte Benutzerauthentifizierung nicht unterstützt).

Die folgende Tabelle enthält Ressourcen, die Sie zum Erstellen eines Authentifizierungscodes verwenden können.

Art der Anwendung	Authentifizierungsbibliothek
Desktop-Apps – iOS	MSAL.framework: Microsoft-Authentifizierungsbibliothek (Vorschau) für iOS
Desktop-Apps – Android	Microsoft-Authentifizierungsbibliothek (MSAL)
Desktop-Apps – .NET	Microsoft-Authentifizierungsbibliothek (MSAL)
Web-Apps — JavaScript SPA	Microsoft-Authentifizierungsbibliothek für JavaScript (Vorschau)
Web-Apps — .NET-Webserver	OpenIdConnection, Cookies, SystemWeb
Web-Apps - NodeJS-Web-App

Für Anwendungen, die keine der vorhandenen Bibliotheken verwenden, siehe Im Namen eines Benutzers zugreifen.

1. Rufen Sie einen Code aus Microsoft Entra ID ab. Die Abfrage zum Aufruf enthält die Parameter für die Anwendungs-ID, Umleitungs-URL und erforderliche Berechtigungen.
2. Verwenden des Codes zum Abrufen eines Zugriffstokens.

Wenn Sie die OpenId Connect-Bibliothek verwenden, lesen Sie Authentifizieren mit Microsoft Entra ID und OpenID Connect, und rufen Sie aufapp.UseOpenIdConnectAuthentication().

Hinweis

Wenn Sie vom Benutzer delegierte Authentifizierungstoken anfordern, lautet der Parameter für die Bibliothek Requested Scopes. Verwenden Sie User.Read für diesen Parameter statt den Anforderungen der registrierten Anwendung. Der Parameter angeforderte Bereiche hat keinen Einfluss auf die Berechtigungen, die in den zurückgegebenen Authentifizierungstoken enthalten sind. Diese werden durch die Berechtigungen bestimmt, die der Mandantenadministrator der Anwendung erteilt.

Wenn Sie beispielsweise die Bibliothek .NET MSAL verwenden, rufen Sie die folgenden auf:

var accessToken = (await client.AcquireTokenAsync(scopes)).AccessToken;

Hinweis

In diesem Beispiel sollte die am wenigsten privilegierte Berechtigung verwendet werden, z. B. User.Read. Das zurückgegebene Zugriffstoken kann jedoch Berechtigungen enthalten, die dem aktuellen Benutzer vom Mandantenadministrator gewährt wurden, z. B. User.Read.All oder User.ReadWrite.All.

Ein Token (Zeichenfolge) wird von Microsoft Entra ID zurückgegeben, das Ihre Authentifizierungsinformationen und die von der Anwendung erforderlichen Berechtigungen enthält. Weisen Sie dieses Token dem HTTP-Header als Bearer-Token zu, wie im folgenden Beispiel gezeigt.

request.Headers.Authorization = new AuthenticationHeaderValue("bearer", accessToken);

Microsoft Graph wird die in diesem Token enthaltenen Informationen überprüfen und den Zugriff gewähren oder ablehnen.

Um die Ansprüche zu sehen, die in den zurückgegebenen Token enthaltenen sind, verwenden Sie die NuGet-Bibliothek System.IdentityModel.Tokens.Jwt.

JwtSecurityTokenHandler tokenHandler = new JwtSecurityTokenHandler();
var securityToken = tokenHandler.ReadToken(accessToken) as JwtSecurityToken;

Die Antwort von Microsoft Graph enthält eine Kopfzeile, die-Client-Anforderungs-ID heißt und eine GUID ist. Wenn der Zugriff verweigert wird, geben Sie diese GUID bei Supportanfragen in der Microsoft Tech Community an, damit wir Ihnen helfen können, die Ursache für diesen Authentifizierungsfehler zu untersuchen.