Anfordern von Berechtigungen durch Einwilligung

  • Artikel

Anwendungen im Microsoft Identity Platform-Endpunkt benötigen eine Einwilligung, um auf erforderliche Ressourcen oder APIs zuzugreifen. Für die unterschiedlichen Anwendungsszenarios sind verschiedene Arten der Einwilligung am besten geeignet. Wenn Sie den besten Ansatz bei der Einwilligung für Ihre App auswählen, wird sie dadurch bei Benutzer*innen und Organisationen beliebter.

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

Beim Szenario mit statischer Benutzereinwilligung müssen Sie im Microsoft Entra Admin Center in der Konfiguration der App alle erforderlichen Berechtigungen angeben. Wenn der*die Benutzer*in (bzw. Administrator*in) die Einwilligung für diese App nicht erteilt hat, wird der*die Benutzer*in vom Microsoft Identity Platform-Endpunkt aufgefordert, die Einwilligung jetzt zu erteilen.

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. Dies kann Benutzer*innen und Administrator*innen davon abhalten, die Zugriffsanforderung Ihrer App zu genehmigen.

Mit dem Endpunkt der Microsoft-Identitätsplattform können Sie die in den App-Registrierungsinformationen im Microsoft Entra Admin Center definierten statischen Berechtigungen ignorieren. 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 zusätzliche 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 noch nicht seine Zustimmung zu den neuen Bereichen gegeben hat, die der Anforderung hinzugefügt wurden, wird er aufgefordert, seine Zustimmung nur für die neuen Berechtigungen zu erteilen. Die inkrementelle oder dynamische Einwilligung gilt nur für delegierte Berechtigungen und nicht für Anwendungsberechtigungen.

Wenn es für eine Anwendung zugelassen wird, Berechtigungen dynamisch über den scope-Parameter anzufordern, erhalten Entwickler*innen die vollständige Kontrolle über die Benutzeroberfläche. Sie können die Zustimmungserfahrung 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 die Berechtigungen inkrementell von dem*der Benutzer*in einholen, während er*sie im Laufe der Zeit versucht, bestimmte Funktionen der Anwendung zu nutzen.

Wichtig

Die dynamische Einwilligung kann komfortabel sein. Sie stellt aber eine große Herausforderung in Bezug auf Berechtigungen dar, für die die Zustimmung durch einen Administrator 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*e Entwickler*in 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 Einwilligung für diese Berechtigungen zu verwenden. Um die Administratoreinwilligung zu erteilen, meldet sich ein einzelner Administrator bei der App an, löst eine Einwilligungsaufforderung für die entsprechenden Berechtigungen aus und wählt Einwilligung für meine gesamte Organisation im Einwilligungsdialogfeld aus.

In einer Autorisierungsanforderung von OpenID Connect oder OAuth 2.0 kann eine Anwendung die erforderlichen Berechtigungen mithilfe des scope-Abfrageparameters anfordern. Wenn sich ein*e Benutzer*in beispielsweise bei einer Anwendung anmeldet, sendet die App eine Anforderung wie die folgende. (Zur besseren Lesbarkeit wurden Zeilenumbrüche eingefü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 von delegierten Berechtigungen, die von der Anwendung angefordert werden. Die einzelnen Berechtigungen werden jeweils durch Anfügen des Berechtigungswerts an den Ressourcenbezeichner (Anwendungs-ID-URI) angegeben. Im Anforderungsbeispiel benötigt die Anwendung eine Berechtigung zum Lesen des Kalenders des Benutzers und Senden von E-Mails als Benutzer.

Nachdem der Benutzer seine Anmeldeinformationen eingegeben hat, überprüft Microsoft Identity Platform, ob es einen übereinstimmenden Eintrag für die Benutzerzustimmung gibt. Wenn der Benutzer in der Vergangenheit für keine der angeforderten Berechtigungen seine Zustimmung erteilt und der Administrator im Namen der gesamten Organisation diesen Berechtigungen nicht zugestimmt hat, wird der Benutzer durch Microsoft Identity Platform aufgefordert, die angeforderten Berechtigungen zu gewähren.

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 Funktionalität der Anwendung erforderlich. Die Berechtigung offline_access ermöglicht der Anwendung den Zugriff auf Aktualisierungstoken, die für native Apps und Web-Apps von entscheidender Bedeutung sind. Die Berechtigung User.Read ermöglicht den Zugriff auf den Anspruch sub. Dadurch kann der Client oder die Anwendung den Benutzer im Laufe der Zeit korrekt identifizieren und auf rudimentäre Benutzerinformationen zugreifen.

Screenshot eines Beispiels für die Einwilligung im Arbeitskonto

Wenn der Benutzer die Berechtigungsanforderung genehmigt, wird die Einwilligung erfasst. Dadurch ist bei nachfolgenden Anmeldevorgängen keine erneute Einwilligung des Benutzers erforderlich.

Das Anfordern der Einwilligung für einen gesamten Mandanten erfordert die Administratoreinwilligung. Die im Namen einer Organisation erteilte Administratorgenehmigung erfordert weiterhin die für die App registrierten statischen Berechtigungen. Legen Sie diese Berechtigungen im Portal für die App-Registrierung fest, wenn ein*e Administrator*in die Einwilligung im Namen der gesamten Organisation erteilen muss.

Wenn Ihre Anwendung delegierte Berechtigungen anfordert, die eine Administratoreinwilligung erfordern, erhält der*die Benutzer*in eine Fehlermeldung, die besagt, dass er*sie nicht berechtigt ist, die Berechtigungen für Ihre Anwendung zu genehmigen. Der*Die Benutzer*in muss den*die Administrator*in um Zugriff auf die App bitten. Wenn der*die Administrator*in die Einwilligung für den gesamten Mandanten erteilt, wird den Benutzer*innen der Organisation keine Einwilligungsseite für die Anwendung angezeigt, es sei denn, die zuvor erteilten Berechtigungen werden widerrufen oder die Anwendung fordert inkrementell eine neue Berechtigung an.

Administrator*innen, die dieselbe Anwendung verwenden, wird die Aufforderung zur Administratoreinwilligung angezeigt. Die Aufforderung zur Administratoreinwilligung enthält ein Kontrollkästchen, mit dem sie der Anwendung im Namen der Benutzer für den gesamten Mandanten Zugriff auf die angeforderten Daten gewähren können. Weitere Informationen zur Benutzer- und Administratoreinwilligung finden Sie unter Benutzeroberfläche für die Anwendungseinwilligung.

Hier finden Sie Beispiele für delegierte Berechtigungen für Microsoft Graph, die eine Administratoreinwilligung erfordern:

  • 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, sodass die Administratoreinwilligung erforderlich ist. Weitere Informationen zum Hinzufügen von Bereichen, die eine Administratoreinwilligung erfordern, finden Sie unterHinzufügen eines Bereichs, der die Administratoreinwilligung erfordert.

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

Hinweis

Wenn bei Anforderungen an die Autorisierungs-, Token- oder Zustimmungsendpunkte für die Microsoft Identity Platform der Ressourcenbezeichner im Bereichsparameter weggelassen wird, wird angenommen, dass Microsoft Graph die Ressource ist. scope=User.Read entspricht beispielsweise https://graph.microsoft.com/User.Read.

Anwendungsberechtigungen erfordern immer die Administratoreinwilligung. Anwendungsberechtigungen haben keinen Benutzerkontext, und die Einwilligungsserteilung erfolgt nicht im Namen eines bestimmten Benutzers oder einer bestimmten Benutzerin. Stattdessen werden der Clientanwendung direkt Berechtigungen erteilt. Diese Arten von Berechtigungen werden nur von Daemondiensten und anderen nicht interaktiven Anwendungen verwendet, die im Hintergrund ausgeführt werden. Administratoren müssen die Berechtigungen im Voraus konfigurieren und die Administratoreinwilligung über das Microsoft Entra Admin Center 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 Administratoreinwilligung erfordern, muss der*die Administrator*in im Namen der Benutzer*innen zustimmen. Um diesen Berechtigungen zuzustimmen, müssen sich die Administrator*innen 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*e Administrator*in kann eine Einwilligung für eine Anwendung mit den folgenden Optionen erteilen.

Wenn Sie eine Anwendung erstellen, die die Administratorzustimmung erfordert, benötigt die Anwendung in der Regel eine Seite oder Ansicht, auf der der*die Administrator*in die Berechtigungen für die Anwendung genehmigen kann. Bei dieser Seite kann es sich um Folgendes handeln:

  • Komponente des Registrierungsflusses der App
  • Teil der App-Einstellungen
  • Dedizierter Verbindungsfluss

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

Durch die Anmeldung des Benutzers bzw. der Benutzerin bei der App können Sie die Organisation identifizieren, der der*die Administrator*in angehört, bevor Sie sie zur Genehmigung der nötigen Berechtigungen auffordern. Dieser Schritt ist zwar nicht unbedingt erforderlich, kann aber dazu beitragen, eine intuitivere Benutzeroberfläche für Ihre Organisationsbenutzer zu erstellen.

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 von ihnen benötigten 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 über .defaultangefordert werden. Wenn Ihre Anwendung Anwendungsberechtigungen benötigt, müssen Sie sicherstellen, dass diese im App-Registrierungsportal aufgeführt sind.

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

  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens als Cloudanwendungsadministrator an.
  2. Browsen Sie zu Identität>Anwendungen>App-Registrierungen>Alle Anwendungen.
  3. Wählen Sie eine Anwendung aus, oder erstellen Sie ggf. eine App.
  4. Wählen Sie auf der Seite Übersicht der Anwendung unter Verwalten Folgendes aus: API-Berechtigungen>Berechtigung hinzufügen.
  5. Wählen Sie in der Liste der verfügbaren APIs die Option Microsoft Graph aus. Fügen Sie dann die von Ihrer Anwendung benötigten Berechtigungen hinzu.
  6. Klicken Sie auf Berechtigungen hinzufügen.

Erfolgreiche Antwort

Wenn der Administrator die Berechtigungen für Ihre Anwendung genehmigt, lautet die erfolgreiche Antwort wie folgt:

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 erteilt hat, im GUID-Format.
state Ein in der Anforderung enthaltener Wert, der auch in der Tokenantwort zurückgegeben wird. Es kann sich um eine Zeichenfolge mit jedem beliebigen Inhalt handeln. Der Status wird verwendet, um Informationen über den Status des Benutzers in der Anwendung zu codieren, bevor die Authentifizierungsanforderung aufgetreten ist, z. B. Informationen zu der Seite oder Ansicht, die der*die Benutzer*in besucht hat.
admin_consent Wird auf True festgelegt.

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

Fehlerantwort

Wenn der Administrator die Berechtigungen für Ihre App nicht genehmigt, lautet die Fehlerantwort wie folgt:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Parameter Beschreibung
error Eine Zeichenfolge mit einem Fehlercode, die zum Klassifizieren der auftretenden Fehlertypen verwendet werden kann. Sie kann auch verwendet werden, um auf Fehler zu reagieren.
error_description Eine spezifische Fehlermeldung, mit der ein Entwickler die Grundursache eines Fehlers identifizieren kann.

Nachdem der*die Benutzer*in die Berechtigungen für Ihre Anwendung genehmigt hat, kann Ihre App Zugriffstoken abrufen, die die Berechtigung der App darstellen, in irgendeiner Weise auf die Ressource zuzugreifen. 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. Beispiel:

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 an die Ressource verwenden. Es zeigt der Ressource zuverlässig, dass die Anwendung über die erforderliche Berechtigung für eine bestimmte Aufgabe verfügt.

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

Weitere Informationen