Freigeben über

Leitfaden für Entwickler zum Anfordern von Berechtigungen und Einwilligungen in Microsoft Identity Platform

Anwendungen in der Microsoft Identity Platform basieren auf der Zustimmung, um Zugriff auf erforderliche Ressourcen oder APIs zu erhalten. Für unterschiedliche Anwendungsszenarien sind unterschiedliche Arten von Zustimmungen besser. Die Wahl des besten Ansatzes für die Einwilligung Ihrer Anwendung führt zu einem größeren Erfolg bei Benutzern und Organisationen.

In diesem Artikel erfahren Sie mehr über die verschiedenen Arten der durch die Einwilligung anfordern.

Hinweis

Für Anwendungen in externen Mandanten können Kunden Berechtigungen nicht eigenständig zustimmen. Ein Administrator muss der Anwendung die Zustimmung erteilen, um in ihrem Namen auf Ressourcen zuzugreifen. Weitere Informationen finden Sie unter Erteilen der Administratorzustimmung.

Im Szenario für die statische Benutzerzustimmung müssen Sie alle Berechtigungen angeben, die sie in der Konfiguration der App im Microsoft Entra Admin Center benötigt. Wenn der Benutzer (oder ggf. der Administrator) keine Einwilligung für diese App erteilt, wird er von Microsoft Identity Platform aufgefordert, die Einwilligung zu diesem Zeitpunkt zu geben.

Mit statischen Berechtigungen können Administrator*innen auch im Namen aller Benutzer*innen in der Organisation einwilligen.

Die Verwendung der statischen Einwilligung und einer einzelnen Berechtigungsliste hält den Code zwar übersichtlich und einfach, bedeutet aber auch, dass Ihre App von vornherein alle Berechtigungen anfordert, die sie jemals benötigen könnte. Diese Einstellung kann Benutzer und Administratoren davon abhalten, die Zugriffsanforderung Ihrer App zu genehmigen.

Mit dem Microsoft Identity Platform-Endpunkt können Sie die statischen Berechtigungen ignorieren, die in den Anwendungsregistrierungsinformationen im Microsoft Entra Admin Center definiert sind. Stattdessen können Sie Berechtigungen inkrementell anfordern. Sie können zunächst nur ein Minimum an Berechtigungen anfordern und im Lauf der Zeit weitere beantragen, wenn der Kunde weitere Anwendungsfunktionen verwendet. Hierzu können Sie die Bereiche angeben, die für Ihre Anwendung zu beliebigen Zeitpunkten benötigt werden, indem Sie die neuen Bereiche in den Parameter scope einfügen, wenn Sie ein Zugriffstoken anfordern. Es ist nicht erforderlich, sie in den Informationen der Anwendungsregistrierung vorab zu definieren.

Wenn der Benutzer den neuen Bereichen, die der Anfrage hinzugefügt werden, nicht zustimmt, wird er aufgefordert, nur den neuen Berechtigungen zuzustimmen. Inkrementelle oder dynamische Zustimmung gilt nur für delegierte Berechtigungen und nicht für Anwendungsberechtigungen.

Wenn eine Anwendung Berechtigungen dynamisch über den scope Parameter anfordert, erhalten Entwickler volle Kontrolle über die Benutzererfahrung. Sie können die Einwilligungserfahrung auch vorziehen und alle Berechtigungen in einer anfänglichen Autorisierungsanforderung erfragen. Wenn Ihre Anwendung eine große Anzahl von Berechtigungen benötigt, können Sie diese Berechtigungen vom Benutzer inkrementell sammeln, während sie versuchen, bestimmte Features der Anwendung im Laufe der Zeit zu verwenden.

Von Bedeutung

Die dynamische Einwilligung kann komfortabel sein. Sie stellt aber eine wichtige Herausforderung in Bezug auf Berechtigungen dar, für die die Administratoreinwilligung erforderlich ist. Die Administratoreinwilligungserfahrung auf den Blättern App-Registrierungen und Enterprise-Anwendungen im Portal hat zur Einwilligungszeit keine Kenntnis von diesen dynamischen Berechtigungen. Es wird empfohlen, dass ein Entwickler alle Administratorberechtigungen auflistet, die von der Anwendung im Portal benötigt werden.

Dadurch können Mandantenadministratoren im Auftrag aller ihrer Benutzer einmalig im Portal einwilligen. Benutzer müssen die Einwilligungserfahrung für diese Berechtigungen bei der Anmeldung nicht durchlaufen. Die Alternative besteht darin, die dynamische Zustimmung für diese Berechtigungen zu verwenden. Um der Administratorzustimmung zu gewähren, meldet sich ein einzelner Administrator bei der App an, löst eine Zustimmungsaufforderung für die entsprechenden Berechtigungen aus und wählt die Zustimmung für meine gesamte Organisation im Zustimmungsdialog aus.

In einer OpenID Connect- oder OAuth 2.0-Autorisierungsanforderung kann eine Anwendung die erforderlichen Berechtigungen mithilfe des scope Abfrageparameters anfordern. Wenn sich beispielsweise ein Benutzer bei einer App anmeldet, sendet die Anwendung eine Anforderung wie das folgende Beispiel. (Zeilenumbrüche werden zur Lesbarkeit hinzugefügt).

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=
https%3A%2F%2Fgraph.microsoft.com%2Fcalendars.read%20
https%3A%2F%2Fgraph.microsoft.com%2Fmail.send
&state=12345

Der scope Parameter ist eine durch Leerzeichen getrennte Liste delegierter Berechtigungen, die die Anwendung anfordert. Die einzelnen Berechtigungen werden jeweils durch Anfügen des Berechtigungswerts an den Ressourcenbezeichner (Anwendungs-ID-URI) angegeben. Im Anforderungsbeispiel benötigt die Anwendung die Berechtigung, den Kalender des Benutzers zu lesen und E-Mails als Benutzer zu senden.

Nach der Anmeldung sucht die Microsoft Identity Platform nach einer vorhandenen Benutzereinwilligung. Wenn der Benutzer die angeforderten Berechtigungen nicht genehmigt und ein Administrator sie nicht genehmigt, fordert die Plattform den Benutzer auf, die Einwilligung zu erteilen.

Im folgenden Beispiel werden die Berechtigungen offline_access („Zugriff auf Daten erhalten, auf die Sie Zugriff gewährt haben“) und User.Read („Anmelden und Ihr Profil lesen“) automatisch in die erste Einwilligung für eine Anwendung aufgenommen. Diese Berechtigungen sind für die ordnungsgemäße Anwendungsfunktionalität erforderlich.

Die offline_access Berechtigung gewährt der Anwendung Zugriff auf Aktualisierungstoken, die für systemeigene Apps und Web-Apps wichtig sind. Die User.Read Berechtigung gewährt Zugriff auf den sub Anspruch. Er ermöglicht es dem Client oder der Anwendung, den Benutzer im Laufe der Zeit korrekt zu identifizieren und auf rudimentäre Benutzerinformationen zuzugreifen.

Beispielfoto, in dem die Zustimmung des Geschäftskontos angezeigt wird.

Wenn der Benutzer die Berechtigungsanforderung genehmigt, wird die Zustimmung aufgezeichnet. Der Benutzer muss nicht erneut zustimmen, wenn er sich später bei der Anwendung anmeldet.

Für die Anforderung der Zustimmung für einen gesamten Mandanten ist die Administratorzustimmung erforderlich. Die Administratorzustimmung im Namen einer Organisation erfordert die für die App registrierten statischen Berechtigungen. Legen Sie diese Berechtigungen im App-Registrierungsportal fest, wenn Sie einen Administrator benötigen, um die Zustimmung im Namen der gesamten Organisation zu erteilen.

Wenn Ihre App delegierte Berechtigungen anfordert , die eine Administratoreinwilligung erfordern, wird Benutzern ein Fehler „Nicht autorisiert zur Zustimmung” angezeigt und ein Administrator zur Zugriffsberechtigung aufgefordert. Sobald ein Administrator die Einwilligung für den gesamten Mandanten erteilt hat, werden Benutzer nicht erneut aufgefordert, es sei denn, die Einwilligung wird widerrufen oder neue Berechtigungen hinzugefügt.

Administratoren, die dieselbe Anwendung verwenden, wird die Aufforderung zur Administratoreinwilligung angezeigt. Die Zustimmungsaufforderung des Administrators stellt ein Kontrollkästchen bereit, mit dem sie der Anwendung Zugriff auf die angeforderten Daten im Namen der Benutzer für den gesamten Mandanten gewähren können. Weitere Informationen zur Benutzer- und Administratorzustimmung finden Sie unter Anwendungszustimmung.

Beispiele für delegierte Berechtigungen für Microsoft Graph, die Administratorzustimmung erfordern, sind:

  • Lesen der vollständigen Profile aller Benutzer mit „User.Read.All“
  • Schreiben von Daten in das Verzeichnis einer Organisation mit „Directory.ReadWrite.All“
  • Lesen aller Gruppen im Verzeichnis einer Organisation mit „Groups.Read.All“

Die vollständige Liste der Microsoft Graph-Berechtigungen finden Sie in der Referenz zu Microsoft Graph-Berechtigungen.

Sie können auch Berechtigungen für Ihre eigenen Ressourcen konfigurieren, um die Administratorzustimmung zu verlangen. Weitere Informationen zum Hinzufügen von Bereichen, die eine Administratorzustimmung erfordern, finden Sie unter Hinzufügen eines Bereichs, der eine Administratorzustimmung erfordert.

Einige Organisationen ändern möglicherweise die Standardrichtlinie für die Benutzereinwilligung für den Mandanten. Wenn Ihre Anwendung den Zugriff auf Berechtigungen anfordert, werden sie anhand dieser Richtlinien ausgewertet. Der Benutzer muss möglicherweise die Administratoreinwilligung anfordern, auch wenn diese nicht standardmäßig erforderlich ist. Informationen dazu, wie Administratoren Zustimmungsrichtlinien für Anwendungen verwalten, finden Sie unter Verwalten von Richtlinien für die App-Zustimmung.

Hinweis

In Microsoft Identity Platform-Autorisierungs-, Token- oder Einwilligungsanforderungen wird der Ressourcenbezeichner in den scope Parameterstandardeinstellungen für Microsoft Graph weggelassen. Beispielsweise wird scope=User.Read als https://graph.microsoft.com/User.Read behandelt.

Anwendungsberechtigungen erfordern immer die Administratorzustimmung. Anwendungsberechtigungen verfügen nicht über einen Benutzerkontext, und die Zustimmungserteilung erfolgt nicht im Namen eines bestimmten Benutzers. Stattdessen werden der Clientanwendung direkt Berechtigungen gewährt. Diese Berechtigungstypen werden nur von Daemondiensten und anderen nicht interaktiven Anwendungen verwendet, die im Hintergrund ausgeführt werden. Administratoren müssen die Berechtigungen vorab konfigurieren und über das Microsoft Entra Admin Center die Administratorzustimmung erteilen .

Falls die Anwendung, die die Berechtigung anfordert, eine mehrinstanzenfähige Anwendung ist, ist die Anwendungsregistrierung nur in dem Mandanten vorhanden, in dem sie erstellt wurde. Daher können Berechtigungen nicht im lokalen Mandanten konfiguriert werden. Wenn die Anwendung Berechtigungen anfordert, die eine Administratorzustimmung erfordern, muss der Administrator im Namen der Benutzer zustimmen. Um diesen Berechtigungen zuzustimmen, müssen sich die Administratoren selbst bei der Anwendung anmelden, damit die Anmeldeoberfläche für die Administratoreinwilligung angezeigt wird. Informationen zum Einrichten der Administratoreinwilligung für mehrinstanzenfähige Anwendungen finden Sie unter Aktivieren von mehrinstanzenfähigen Anmeldungen.

Ein Administrator kann eine Zustimmung für eine Anwendung mit den folgenden Optionen erteilen.

Wenn Sie eine Anwendung erstellen, die eine Administratorzustimmung erfordert, benötigt die Anwendung eine Seite oder Ansicht, in der der Administrator die Berechtigungen der App genehmigen kann. Diese Seite kann wie folgt sein:

  • Teil des Registrierungsablaufs der App.
  • Teil der App-Einstellungen.
  • Dedizierter Verbindungsfluss

In vielen Fällen ist es sinnvoll, dass die Anwendung diese „Verbindungsansicht“ erst anzeigt, wenn ein Benutzer sich mit einem Geschäfts-, Schul- oder Unikonto von Microsoft angemeldet hat.

Wenn Sie den Benutzer bei Ihrer App anmelden, können Sie die Organisation identifizieren, zu der der Administrator gehört, bevor Sie ihn bitten, die erforderlichen Berechtigungen zu genehmigen. Obwohl dieser Schritt nicht unbedingt erforderlich ist, kann es Ihnen helfen, eine intuitivere Benutzeroberfläche für Ihre Organisationsbenutzer zu schaffen.

Gehen Sie gemäß den Tutorials zum Microsoft Identity Platform-Protokoll vor, um den Benutzer anzumelden.

Anfordern der Berechtigungen im App-Registrierungsportal

Im App-Registrierungsportal können Anwendungen die erforderlichen Berechtigungen auflisten, einschließlich delegierter Berechtigungen und Anwendungsberechtigungen. Dieses Setup ermöglicht die Verwendung des .default-Bereichs und der Option Administratoreinwilligung erteilen im Microsoft Entra Admin Center.

Im Allgemeinen sollten die Berechtigungen für eine bestimmte Anwendung statisch definiert werden. Dabei sollte es sich um eine übergeordnete Gruppe der Berechtigungen handeln, die von der Anwendung dynamisch oder inkrementell angefordert werden.

Hinweis

Anwendungsberechtigungen können nur mithilfe von .default angefordert werden. Wenn Ihre Anwendung also Anwendungsberechtigungen benötigt, stellen Sie sicher, dass sie im App-Registrierungsportal aufgeführt sind.

So konfigurieren Sie die Liste der statisch angeforderten Berechtigungen für eine Anwendung:

  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens als Cloudanwendungsadministrator an.
  2. Navigieren Sie zu Entra ID>App-Registrierungen>Alle Anwendungen.
  3. Wählen Sie eine Anwendung aus, oder erstellen Sie eine App , sofern noch nicht geschehen.
  4. Wählen Sie auf der Seite "Übersicht " der Anwendung unter "Verwalten" die Option "API-Berechtigungen>hinzufügen" aus.
  5. Wählen Sie Microsoft Graph aus der Liste der verfügbaren APIs aus. Fügen Sie dann die Berechtigungen hinzu, die Ihre Anwendung benötigt.
  6. Klicken Sie auf Berechtigungen hinzufügen.

Erfolgreiche Antwort

Wenn der Administrator die Berechtigungen für Ihre App genehmigt, sieht die erfolgreiche Antwort wie folgt aus:

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
Parameter BESCHREIBUNG
tenant Der Verzeichnismandant, der Ihrer Anwendung die angeforderten Berechtigungen im GUID-Format erteilt hat.
state Ein in der Anforderung enthaltener Wert, der in der Tokenantwort zurückgegeben wird. Es kann sich um eine Zeichenfolge mit jedem beliebigen Inhalt handeln. Der Zustand wird verwendet, um Informationen zum Status des Benutzers in der Anwendung zu codieren, bevor die Authentifizierungsanforderung aufgetreten ist, z. B. die Seite oder die Ansicht, auf der sie sich befanden.
admin_consent Ist auf True festgelegt.

Nachdem Sie eine erfolgreiche Antwort vom Endpunkt für die Administratoreinwilligung erhalten, erhält Ihre Anwendung die Berechtigungen, die sie angefordert hat. Als Nächstes können Sie ein Token für die gewünschte Ressource anfordern.

Fehlerantwort

Wenn der Administrator die Berechtigungen für Ihre App nicht genehmigt, sieht die fehlgeschlagene Antwort wie folgt aus:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Parameter BESCHREIBUNG
error Eine Fehlercodezeichenfolge, die verwendet werden kann, um Fehlertypen zu klassifizieren, die auftreten. Sie kann auch verwendet werden, um auf Fehler zu reagieren.
error_description Eine bestimmte Fehlermeldung, die einem Entwickler helfen kann, die Ursache eines Fehlers zu identifizieren.

Nachdem der Benutzer den Berechtigungen für Ihre App zugestimmt hat, kann Ihre Anwendung Zugriffstoken abrufen, die die Berechtigung der App für den Zugriff auf eine Ressource in einer bestimmten Kapazität darstellen. Ein Zugriffstoken kann nur für eine einzelne Ressource verwendet werden. Allerdings ist darin jede Berechtigung codiert, die Ihrer Anwendung für diese Ressource erteilt wurde. Um ein Zugriffstoken zu erhalten, kann Ihre Anwendung eine Anforderung an den Microsoft Identity Platform-Tokenendpunkt senden, z. B.:

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "scope": "https://microsoft.graph.com/Mail.Read https://microsoft.graph.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "A1bC2dE3f..."  // NOTE: Only required for web apps
}

Sie können das resultierende Zugriffstoken in HTTP-Anforderungen für die Ressource verwenden. Sie weist zuverlässig auf die Ressource hin, dass Ihre Anwendung über die richtige Berechtigung zum Ausführen eines bestimmten Vorgangs verfügt.

Weitere Informationen zum OAuth 2.0-Protokoll und zum Abrufen von Zugriffstoken finden Sie in der Microsoft Identity Platform-Endpunktprotokollreferenz.

Verwandte Inhalte

  • Last updated on