Autorisierung und die Sicherheits-API in Microsoft GraphAuthorization and the Microsoft Graph Security API

Sicherheitsdaten, auf die über die Sicherheits-API in Microsoft Graph zugegriffen werden kann, sind vertraulich und sind sowohl durch Berechtigungen als auch durch Azure Active Directory (Azure AD)-Rollen geschützt.Security data accessible via the Microsoft Graph Security API is sensitive and protected by both permissions and Azure Active Directory (Azure AD) roles.

Die Sicherheits-API in Microsoft Graph unterstützt zwei Arten von Autorisierung:The Microsoft Graph Security API supports two types of authorization:

  • Autorisierung auf Anwendungsebene – Es ist kein Benutzer angemeldet (z. B. ein SIEM-Szenario).Application-level authorization - There is no signed-in user (for example, a SIEM scenario). Die Berechtigungen, die der Anwendung gewährt wurden, bestimmen die Autorisierung.The permissions granted to the application determine authorization.

    Hinweis: Diese Option unterstützt auch Fälle, in denen die rollenbasierte Zugriffssteuerung (RBAC) von der Anwendung verwaltet wird.Note: This option can also support cases where Role-Based Access Control (RBAC) is managed by the application.

  • Benutzer-delegierte Autorisierung – Ein Benutzer, der ein Mitglied des Azure AD-Mandanten ist, ist angemeldet.User delegated authorization - A user who is a member of the Azure AD tenant is signed in. Der Benutzer muss ein Mitglied einer beschränkten Azure AD-Administratorrolle sein – mit Leseberechtigung für Sicherheitsfunktionen oder Sicherheitsadministrator – zusätzlich dazu, dass der Anwendung die erforderlichen Berechtigungen erteilt wurden.The user must be a member of an Azure AD Limited Admin role - either Security Reader or Securty Administrator - in addition to the application having been granted the required permissions.

Wenn Sie die Sicherheits-API in Microsoft Graph aus Graph Explorer aufrufen:If you're calling the Microsoft Graph Security API from Graph Explorer:

  • Der Azure AD-Mandantenadministrator muss explizit die erforderlichen Berechtigungen für die Graph-Explorer-Anwendung gewähren.The Azure AD tenant admin must explicitly grant consent for the requested permissions to the Graph Explorer application.
  • Der Benutzer muss Mitglied einer beschränkten Azure AD-Administratorrolle (mit Leseberechtigung für Sicherheitsfunktionen oder Sicherheitsadministrator) sein.The user must be a member of the Security Reader Limited Admin role in Azure AD (either Security Reader or Security Administrator).

Hinweis: Graph Explorer unterstützt die Autorisierung auf Anwendungsebene nicht.Note: Graph Explorer does not support application-level authorization.

Wenn Sie die Sicherheits-API in Microsoft Graph aus einer benutzerdefinierten oder Ihrer eigenen Anwendung aufrufen:If you're calling the Microsoft Graph Security API from a custom or your own application:

  • Der Azure AD-Mandantenadministrator muss Ihrer Anwendung explizit zustimmen.The Azure AD tenant admin must explicitly grant consent to your application. Dies ist sowohl für die Autorisierung auf Anwendungsebene als auch für benutzerdelegierte Autorisierung erforderlich.This is required both for application-level authorization and user delegated authorization.
  • Wenn Sie benutzerdelegierte Autorisierung nutzen, muss der Benutzer Mitglied einer beschränkten Azure AD-Administratorrolle mit Leseberechtigung für Sicherheitsfunktionen oder Sicherheitsadministrator sein.If you're using user delegated authorization, the user must be a member of the Security Reader or Security Administrator Limited Admin role in Azure AD.

Verwalten der Autorisierung in Sicherheits-API-ClientanwendungenManage authorization in security API client applications

Über die Sicherheits-API in Microsoft Graph bereitgestellte Sicherheitsdaten sind vertraulich und müssen durch entsprechende Authentifizierungs- und Autorisierungsmechanismen geschützt werden.Security data provided via the Microsoft Graph Security API is sensitive and must be protected by appropriate authentication and authorization mechanisms. Die folgende Tabelle enthält die Schritte zum Registrieren und Erstellen einer Clientanwendung, die auf die Sicherheits-API in Microsoft Graph zugreifen kann.The following table lists the steps to register and create a client application that can access the Microsoft Graph Security API.

Wer?Who AktionAction
Anwendungsentwickler oder -besitzerApplication developer or owner Registrieren Sie die Anwendung als eine Enterprise-Anwendung.Register the application as an enterprise application.
MandantenadministratorTenant admin Gewähren Sie Ihrer Anwendung entsprechende Berechtigungen.Grant permissions to the application.
MandantenadministratorTenant admin Zuweisen von Benutzerrollen.Assign roles to users.
AnwendungsentwicklerApplication developer Melden Sie sich als Benutzer an, und verwenden Sie die Anwendung, um auf die Sicherheits-API in Microsoft Graph zuzugreifen.Sign in as the user and use the application to access the Microsoft Graph Security API.

Die Registrierung der Anwendung definiert nur, welche Berechtigungen die Anwendung zum Ausführen braucht.Application registration only defines which permissions the application needs in order to run. Sie gewährt der Anwendung KEINE Berechtigungen.It does NOT grant these permissions to the application.

Der Azure AD-Mandantenadministrator MUSS der Anwendung die Berechtigungen explizit gewähren.The Azure AD tenant administrator MUST explicitly grant the permissions to the application. Dies muss pro Mandant erfolgen und muss jedes Mal durchgeführt werden, wenn die Anwendungsberechtigungen im Anwendungsregistrierungsportal geändert werden.This must be done per tenant and must be performed every time the application permissions are changed in the application registration portal.

Nehmen wir beispielsweise an, dass Sie eine Anwendung, zwei Azure AD-Mandanten, T1 und T2, und zwei Berechtigungen, P1 und P2, haben.For example, assume that you have an application, two Azure AD tenants, T1 and T2, and two permissions, P1 and P2. Der Autorisierungsprozess sieht folgendermaßen aus:The following is the authorization process:

  • Die Anwendung registriert sich, um Berechtigung P1 anzufordern.The application registers to require permission P1.
  • Wenn Benutzer im Mandanten T1 ein Azure AD-Token für diese Anwendung erhalten, enthält das Token keine Berechtigungen.When users in tenant T1 get an Azure AD token for this application, the token does not contain any permissions.
  • Azure AD-Administrator des Mandanten T1 gewährt der Anwendung explizit Berechtigungen.The Azure AD admin of tenant T1 explicitly grants permissions to the application. Wenn Benutzer im Mandanten T1 ein Azure AD-Token für diese Anwendung erhalten, enthält das Token die Berechtigung P1.When users in tenant T1 get an Azure AD token for the application, it will contain permission P1.
  • Wenn Benutzer im Mandanten T2 ein Azure AD-Token für diese Anwendung erhalten, enthält das Token keine Berechtigungen, da der Administrator des Mandanten T2 der Anwendung noch keine Berechtigungen erteilt hat.When users in tenant T2 get an Azure AD token for the application, the token does not contain any permissions - because the admin of tenant T2 did not yet grant permissions to the application. Berechtigung müssen pro Mandant und pro Anwendung erteilt werden.Permission must be granted per tenant and per application.
  • Die Anwendung hat ihre Registrierung geändert, sodass sie jetzt die Berechtigungen P1 und P2 erfordert.The application has its registration changed to now require permissions P1 and P2.
  • Wenn Benutzer im Mandanten T1 ein Azure AD-Token für diese Anwendung erhalten, enthält das Token nur die Berechtigung P1.When users in tenant T1 get an Azure AD token for the application, it only contains permission P1. Berechtigungen, die einer Anwendung gewährt werden, werden als Momentaufnahmen dessen, was gewährt wurde, aufgezeichnet. Sie ändern sich nicht automatisch nach der (Berechtigungs-)Änderung der Anwendungsregistrierung.Permissions granted to an application are recorded as snapshots of what was granted - they do not change automatically after the application registration (permission) changes.
  • Der Administrator des Mandanten T2 erteilt Berechtigungen P1 und P2 für die Anwendung.The admin of tenant T2 grants permissions P1 and P2 to the application. Wenn nun Benutzer im Mandanten T2 ein Azure AD-Token für diese Anwendung erhalten, enthält das Token die Berechtigungen P1 und P2.Now, when users in tenant T2 get an Azure AD token for the application, the token will contain permissions P1 and P2.

Hinweis: Die Azure AD-Token für die Anwendung im Mandanten T1 und die Anwendung in Mandant T2 enthalten verschiedene Berechtigungen, da jeder Mandantenadministrator verschiedene Berechtigungen für die Anwendung erteilt hat.Note: The Azure AD tokens for the application in tenant T1 and the application in tenant T2 contain different permissions, because each tenant admin has granted different permissions to the application.

  • 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.To make the application work again in tenant T1, the admin of tenant T1 must explicitly grant permissions P1 and P2 to the application.

Registrieren einer Anwendung beim Microsoft Identity Platform-EndpunktRegister an application with the Microsoft identity platform

Zum Registrieren einer Anwendung beim Microsoft Identity Platform-Endpunkt benötigen Sie Folgendes:To register an application to the Azure AD v2.0 endpoint, you'll need:

  • Anwendungsname – Zeichenfolge für den Namen der Anwendung.Application name - A string used for the application name.
  • Umleitungs-URL – Die URL, an die die Authentifizierungsantwort von Azure AD gesendet wird.Redirect URL - The URL where the authentication response from Azure AD is sent. Um zu beginnen, können Sie die Homepage der Test Client Web App verwenden.To start, you can use the test client web app homepage.
  • Erforderliche Berechtigungen – Die Berechtigungen, die die Anwendung erfordert, um Microsoft Graph aufrufen zu können.Required Permissions - The permissions that your application requires to be able to call Microsoft Graph.

So registrieren Sie Ihre AnwendungTo register your application:

  1. Wechseln Sie zum Azure App-Registrierungsportal, und melden Sie sich an.Go to the Azure portal and sign in.

    Hinweis: Sie müssen kein Mandantenadministrator sein. Sie werden zur Liste Meine Programme weitergeleitet.Note: You don't have to be a tenant admin. You will be redirected to the My applications list.

  2. Wählen Sie Neue Registrierung aus.Choose New registration.

  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.On the registration page for the new application, enter a value for Name and select the account types you wish to support. Geben Sie im Feld Umleitungs-URI die Umleitungs-URL ein.In the Redirect URL field, enter the redirect URL.

  4. Wählen Sie Registrieren aus, um die App zu erstellen und ihre Übersichtsseite anzuzeigen.Select Register to create the app and view its overview page.

  5. Navigieren Sie zur Seite API-Berechtigungen der App.Go to the app's API permissions page.

  6. Wählen Sie Berechtigung hinzufügen und dann im Flyout die Option Microsoft Graph aus.Select Add a permission and then choose Microsoft Graph in the flyout. Wählen Sie Delegierte Berechtigungen aus.Select Delegated permissions. Verwenden Sie das Suchfeld, um die erforderlichen Berechtigungen zu suchen und auszuwählen.Use the search box to find and select the required permissions. Eine Liste von Berechtigungen finden Sie unter Sicherheitsberechtigungen.For a list of permissions, see Security permissions.

    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.Note: The Microsoft Graph Security API requires the *.Read.All scope for GET queries, and the *.ReadWrite.All scope for PATCH/POST/DELETE queries.

    BerechtigungPermission EntitätEntity Unterstützte AnforderungenSupported requests
    SecurityActions.Read.AllSecurityActions.Read.All securityActions (Vorschau)securityActions (preview) GETGET
    SecurityActions.ReadWrite.AllSecurityActions.ReadWrite.All securityActions (Vorschau)securityActions (preview) GET, POSTGET, POST
    SecurityEvents.Read.AllSecurityEvents.Read.All alertsalerts
    secureScoressecureScores (preview)
    secureScoreControlProfilessecureScoreControlProfiles
    ABRUFENGET
    SecurityEvents.ReadWrite.AllSecurityEvents.ReadWrite.All alertsalerts
    secureScoressecureScores (preview)
    secureScoreControlProfilessecureScoreControlProfiles
    GET, POST, PATCHGET, POST, PATCH
    ThreatIndicators.ReadWrite.OwnedByThreatIndicators.ReadWrite.OwnedBy tiIndicator (Vorschau)tiIndicator (preview) GET, POST, PATCH, DELETEGET, POST, PATCH, DELETE
  7. Wählen Sie Berechtigungen hinzufügen aus.Choose Add permissions.

Speichern Sie die folgenden Informationen:Save the following information:

  • Anwendungs-ID (Client-ID)Application (client) ID
  • Umleitungs-URLRedirect URL
  • Liste der erforderlichen BerechtigungenList of required permissions

Weitere Informationen finden Sie unter Registrieren Ihrer App bei Microsoft Identity Platform.For more information, see Register your app with the Microsoft identity platform.

Gewähren von Berechtigungen für eine AnwendungGrant permissions to an application

Die Anwendungsregistrierung definiert nur, welche Berechtigungen die Anwendung erfordert. Sie gewährt der Anwendung diese Berechtigungen NICHT.Application registration only defines which permission the application requires - it does not grant these permissions to the application. Ein Azure AD-Mandantenadministrator muss diese Berechtigungen explizit gewähren, indem er den Endpunkt für die Administratorzustimmung aufruft.An Azure AD tenant administrator must explicitly grant these permissions by making a call to the admin consent endpoint. Einzelheiten hierzu finden Sie unter Verwenden des Endpunkts für die Administratorzustimmung.For details, see Using the admin consent endpoint.

Um einer Anwendung Berechtigungen zu gewähren, brauchen Sie:To grant permissions to an application, you'll need:

  • Anwendungs-ID – Die Anwendungs-ID, die Ihrer App vom Azure-Registrierungsportal zugewiesen wurde.Application ID - The application ID from application registration portal.
  • Umleitungs-URL – Die Zeichenfolge, die Sie im Azure-Registrierungsportal für die Authentifizierungsantwort festgelegt haben.Redirect URL - The string you set in the application registration portal for authentication response.

So gewähren Sie BerechtigungenTo grant the permissions:

  • Erstellen Sie in einem Texteditor die folgende URL-Zeichenfolge:In a text editor, create following URL string:

    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.In a web browser, go to this URL, and sign in as a tenant administrator. Das Dialogfeld zeigt die Liste der Berechtigungen, die die Anwendung erfordert, wie im App-Registrierungsportal eingegeben.The dialog box shows the list of permission the application requires, as specified in the application registration portal. Wählen Sie OK, um der Anwendung diese Berechtigungen zu erteilen.Choose OK to grant the application these permissions.

Hinweis: Dieser Schritt erteilt Berechtigungen an die Anwendung – nicht an den Benutzer.Note: This step grants permissions to the application - not to users. Das bedeutet, dass alle Benutzer, die zum Azure AD-Mandanten gehören, die diese Anwendung verwenden, diese Berechtigungen erhalten – sogar Benutzer ohne Administratorberechtigung.This means that all users belonging to the Azure AD tenant that use this application will be granted these permissions - even non-admin users.

Zuweisen von Azure AD-Rollen für BenutzerAssign Azure AD roles to users

Nachdem einer Anwendung Berechtigungen erteilt wurden, erhalten alle Benutzer, die Zugriff auf die Anwendung (d. h. Mitglieder des Azure AD-Mandanten) die Berechtigungen, die erteilt wurden.After an application is granted permissions, everyone with access to the application (that is, members of the Azure AD tenant) will receive the granted permissions. Um vertrauliche Daten zusätzlich zu schützen, verlangt die Sicherheits-API in Microsoft Graph, dass Benutzern die Azure AD-Rolle Benutzer mit Leseberechtigung für Sicherheitsfunktionen zugewiesen wird.To further protect sensitive security data, the Microsoft Graph Security API also requires users to be assigned the Azure AD Security Reader role. Einzelheiten hierzu finden Sie unter Zuweisen von Administratorrollen und Zuweisen eines Benutzers zu Administratorrollen.For details, see Assigning administrator roles and Assign a user to administrator roles.

Hinweis: Sie müssen Mandantenadministrator sein, um diesen Schritt auszuführen.Note: You must be a tenant admin to perform this step.

So weisen Sie Benutzern Rollen zuTo assign roles to users:

  • Melden Sie sich beim Azure-Portalan.(https://portal.azure.com)Sign in to the azure portal (https://portal.azure.com).
  • Wählen Sie im Menü Azure Active Directory > Benutzer.In the menu, select Azure Active Directory > Users.
  • Wählen Sie den Namen des Benutzers aus.Select the name of the user.
  • Wählen Sie Verwalten > Directory-Rolle.Select Manage > Directory role.
  • Wählen Sie Eingeschränkter Administrator, und wählen Sie das Kontrollkästchen Benutzer mit Leseberechtigung für Sicherheitsfunktionen aus.Select Limited administrator, and choose the Security reader check box.
  • Wählen Sie Speichern aus.Choose Save.

Erstellen eines AuthentifizierungscodesCreate an authentication code

Um einen Authentifizierungscode zu erstellen, brauchen Sie:To create an authentication code, you'll need:

  • Anwendungs-ID – Die Anwendungs-ID, die Ihrer App vom App-Registrierungsportal zugewiesen wurde.Application ID - The application ID from application registration portal.
  • Umleitungs-URL – Die URL, an die die Authentifizierungsantwort von Azure AD gesendet wird.Redirect URL - The URL where the authentication response from Azure AD is sent. Zum Beginnen können Sie https://localhost oder die Homepage der Test Client Web App verwenden.To start, you can use https://localhost or the test client web app homepage.
  • Anwendungsschlüssel (optional) — Der Schlüssel der Anwendung.Application Key (optional) - The key of the application. Dies gilt, wenn Sie eine Anwendung entwickeln, die Nur-App-Authentifizierungscodes verwendet (d. h. delegierte Benutzerauthentifizierung nicht unterstützt).This applies when you're developing an application that will use application-only authentication code (that is, will not support user delegated authentication).

Die folgende Tabelle enthält Ressourcen, die Sie zum Erstellen eines Authentifizierungscodes verwenden können.The following table lists resources that you can use to create an authentication code.

Art der AnwendungType of application AuthentifizierungsbibliothekAuthentication library
Desktop-Apps – iOSDesktop apps - iOS MSAL.framework: Microsoft-Authentifizierungsbibliothek (Vorschau) für iOSMSAL.framework: Microsoft Authentication Library Preview for iOS
Desktop-Apps – AndroidDesktop apps - Android Microsoft-Authentifizierungsbibliothek (MSAL)Microsoft Authentication Library (MSAL)
Desktop-Apps – .NETDesktop apps - .Net Microsoft-Authentifizierungsbibliothek (MSAL)Microsoft Authentication Library (MSAL)
Web-Apps — JavaScript SPAWeb apps - JavaScript SPA Microsoft-Authentifizierungsbibliothek für JavaScript (Vorschau)Microsoft Authentication Library for JavaScript Preview
Web-Apps — .NET-WebserverWeb apps - .NET Web Server OpenIdConnection, Cookies, SystemWebOpenIdConnection, Cookies, SystemWeb
Web-Apps - NodeJS-Web-AppWeb apps - NodeJS Web App

Für Anwendungen, die keine der vorhandenen Bibliotheken verwenden, siehe Im Namen eines Benutzers zugreifen.For applications that don't use any of the existing libraries, see Get access on behalf of a user.

  1. Abrufen eines Codes von Azure AD.Get a code from Azure AD. Die Abfrage zum Aufruf enthält die Parameter für die Anwendungs-ID, Umleitungs-URL und erforderliche Berechtigungen.The query to call contains parameter for Application ID, Redirect URl, and required permissions.
  2. Verwenden des Codes zum Abrufen eines Zugriffstokens.Use the code to get an access token.

Wenn Sie die OpenID Connect-Bibliothek verwenden, lesen Sie Authentifizieren mithilfe von Azure Active Directory und OpenID Connect, und rufen Sie app.UseOpenIdConnectAuthentication() auf.If you use OpenId Connect library, see Authenticate using Azure AD and OpenID Connect and call app.UseOpenIdConnectAuthentication().

Hinweis: Wenn Sie benutzerdelegierte Authentifizierungstoken anfordern, ist der Parameter für die Bibliothek angeforderte Bereiche.Note: If you're requesting user delegated authentication tokens, the parameter for the library is Requested Scopes. Verwenden Sie User.Read für diesen Parameter statt den Anforderungen der registrierten Anwendung.Use User.Read for this parameter instead of what the registered application requires. Der Parameter angeforderte Bereiche hat keinen Einfluss auf die Berechtigungen, die in den zurückgegebenen Authentifizierungstoken enthalten sind.The Requested Scopes parameter does NOT affect the permissions contained in the returned authentication tokens. Diese werden durch die Berechtigungen bestimmt, die der Mandantenadministrator der Anwendung erteilt.These are determined by the permissions that the tenant admin granted the application.

Wenn Sie beispielsweise die Bibliothek .NET MSAL verwenden, rufen Sie die folgenden auf:For example, if you're using the .NET MSAL library, call the following:

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

Hinweis: Dieses Beispiel sollte die geringsten Berechtigungen, z. B. User.Read, verwenden.Note: This example should use the least privileged permission, such as 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.However, the returned access token can contain permissions that were granted by the tenant admin for the current user tenant, such as User.Read.All or User.ReadWrite.All.

Ein Token (Zeichenfolge) wird von Azure AD zurückgegeben, das Ihre Authentifizierungsinformation und die von der Anwendung benötigten Berechtigungen enthält.A token (string) is returned by Azure AD that contains your authentication information and the permissions required by the application. Weisen Sie dieses Token dem HTTP-Header als Bearer-Token zu, wie im folgenden Beispiel gezeigt.Assign this token to the HTTP header as a bearer token, as shown in the following example.

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.Microsoft Graph will validate the information contained in this token and grant, or reject, access.

Um die Ansprüche zu sehen, die in den zurückgegebenen Token enthaltenen sind, verwenden Sie die NuGet-Bibliothek System.IdentityModel.Tokens.Jwt.To view claims contained in the returned token, use NuGet library 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.The response from Microsoft Graph contains a header called client-request-id, which is a GUID. 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.If access is denied, please specify this GUID when seeking support at Microsoft Tech Community, so we can help investigate the cause of this authentication failure.