Bereiche und Berechtigungen in Microsoft Identity Platform

Die Microsoft Identity Platform implementiert das OAuth 2.0-Autorisierungsprotokoll. OAuth 2.0 ist eine Methode, über die eine Drittanbieter-App im Auftrag eines Benutzers auf im Web gehostete Ressourcen zugreifen kann. Alle im Web gehosteten Ressourcen, die in Microsoft Identity Platform integriert werden, verfügen über einen Ressourcenbezeichner bzw. Anwendungs-ID-URI.

In diesem Artikel erfahren Sie mehr über Bereiche und Berechtigungen in Microsoft Identity Platform.

Die folgende Liste enthält einige Beispiele für im Web gehostete Ressourcen von Microsoft:

• Microsoft Graph: https://graph.microsoft.com
• API für Microsoft 365-E-Mail: https://outlook.office.com
• Azure Key Vault: https://vault.azure.net

Dasselbe gilt für alle Ressourcen von Drittanbietern, die in die Microsoft Identity Platform integriert wurden. Diese Ressourcen können auch einen Satz von Berechtigungen definieren, die zum Unterteilen der Funktionalität der Ressource in kleinere Einheiten verwendet werden können. Beispielsweise verfügt Microsoft Graph über definierte Berechtigungen, um unter anderem folgende Aufgaben auszuführen:

• Lesen des Kalenders eines Benutzers
• Schreiben in den Kalender eines Benutzers
• Senden von E-Mails als Benutzer

Aufgrund dieser Arten von Berechtigungsdefinitionen kann die Ressource die Daten und die Art und Weise, wie API-Funktionen verfügbar gemacht werden, präzise steuern. Eine Drittanbieter-App kann diese Berechtigungen von Benutzern und Administratoren anfordern. Diese müssen die Anforderung dann genehmigen, bevor die App auf Daten zugreifen oder im Namen eines Benutzers agieren kann.

Die Unterteilung der Funktionen einer Ressource in kleinere Berechtigungssätze ermöglicht die Erstellung von Drittanbieter-Apps, von denen nur die spezifischen Berechtigungen angefordert werden, die diese Apps für ihr jeweilige Funktion benötigen. Benutzer und Administratoren können erkennen, auf welche Daten die App zugreifen kann. Und sie können mit höherer Wahrscheinlichkeit davon ausgehen, dass die App keine böswilligen Absichten verfolgt. Entwickler sollten sich immer an das Prinzip der geringsten Rechte halten und nur die Berechtigungen anfordern, die für die Funktion ihrer Anwendungen erforderlich sind.

In OAuth 2.0 werden diese Arten von Berechtigungssätzen Bereiche genannt. Oftmals werden sie auch als Berechtigungen bezeichnet. In Microsoft Identity Platform wird eine Berechtigung als Zeichenfolgenwert dargestellt. Eine App fordert die erforderlichen Berechtigungen an, indem sie die Berechtigung im scope -Anforderungsparameter angibt. Microsoft Identity Platform unterstützt mehrere klar definierte OpenID Connect-Bereiche sowie ressourcenbasierte Berechtigungen (jede Berechtigung wird durch Anfügen des Berechtigungswerts an den Bezeichner oder Anwendungs-ID-URI der Ressource angegeben). Beispielsweise wird die https://graph.microsoft.com/Calendars.Read-Berechtigungszeichenfolge verwendet, um die Berechtigung zum Lesen von Benutzerkalendern in der Microsoft Graph anzufordern.

Wenn in Anforderungen an den Autorisierungsserver für Microsoft Identity Platform der Bezeichner der Ressource im Bereichsparameter weggelassen wird, wird angenommen, dass die Ressource Microsoft Graph ist. scope=User.Read entspricht beispielsweise https://graph.microsoft.com/User.Read.

Auf den Administrator beschränkte Berechtigungen

Berechtigungen in Microsoft Identity Platform können auf Administratoren beschränkt festgelegt werden. Viele Berechtigungen für Microsoft Graph mit höheren Rechten erfordern beispielsweise die Genehmigung des Administrators. Wenn Ihre App auf Administratoren beschränkte Berechtigungen erfordert, muss der Administrator einer Organisation seine Einwilligung für diese Bereiche im Namen der Benutzer der Organisation erteilen. Im folgenden Abschnitt finden Sie Beispiele für diese Arten von Berechtigungen:

• User.Read.All: Vollständige Profile aller Benutzer*innen lesen
• Directory.ReadWrite.All: Daten in das Verzeichnis einer Organisation schreiben
• Groups.Read.All: Alle Gruppen im Verzeichnis einer Organisation lesen

Ein Endbenutzer kann einer Anwendung zwar ggf. Zugriff auf diese Daten gewähren, Organisationsbenutzer können allerdings keinen Zugriff auf die gleichen sensible Unternehmensdaten erteilen. Wenn Ihre Anwendung von einem Organisationsbenutzer Zugriff auf eine dieser Berechtigungen anfordert, wird dem Benutzer in einer Fehlermeldung mitgeteilt, dass er nicht befugt ist, den Berechtigungen Ihrer App zuzustimmen.

Wenn die Anwendung Anwendungsberechtigungen anfordert und ein Administrator diese Berechtigungen erteilt, erfolgt diese Erteilung nicht im Auftrag eines bestimmten Benutzers. Stattdessen werden der Clientanwendung direkt Berechtigungen gewährt. Diese Berechtigungstypen dürfen nur von Daemondiensten und anderen nicht interaktiven Anwendungen verwendet, die im Hintergrund ausgeführt werden. Weitere Informationen zum Szenario für direkten Zugriff finden Sie unter Zugriffsszenarien in Microsoft Identity Platform.

Eine Schritt-für-Schritt-Anleitung, wie Sie Bereiche in einer Web-API verfügbar machen können, finden Sie unter Konfigurieren einer Anwendung für das Verfügbarmachen einer Web-API.

OpenID Connect-Bereiche

Die Microsoft Identity Platform-Implementierung von OpenID Connect bietet einige klar definierte Bereiche, die ebenfalls in Microsoft Graph gehostet werden: openid, email, profile und offline_access. Die OpenID Connect-Bereiche address und phone werden nicht unterstützt.

Wenn Sie die OpenID Connect-Bereiche und ein Token anfordern, erhalten Sie ein Token zum Abrufen des UserInfo-Endpunkts.

Der openid-Bereich

Bei einer App-Anmeldung mit OpenID Connect muss der Bereich openid angefordert werden. Der Bereich openid wird auf der Einwilligungsseite des Arbeitskontos als Berechtigung Anmeldung in Ihrem Namen angezeigt.

Mit dieser Berechtigung kann eine App einen eindeutigen Bezeichner für den Benutzer in Form des Anspruchs sub empfangen. Die Berechtigung ermöglicht es der App außerdem, auf den Endpunkt mit den Benutzerinformationen (UserInfo) zuzugreifen. Der Bereich openid kann am Microsoft Identity Platform-Tokenendpunkt zum Abrufen von ID-Token verwendet werden. Diese Token können von der App wiederum für die Authentifizierung verwendet werden.

Der email-Bereich

Der Bereich email kann zusammen mit dem Bereich openid und weiteren Bereichen verwendet werden. Er gibt der App Zugriff auf die primäre E-Mail-Adresse des Benutzers in Form des Anspruchs email .

Der Anspruch email ist nur in einem Token enthalten, wenn dem Benutzerkonto eine E-Mail-Adresse zugewiesen ist (dies ist nicht immer der Fall). Wenn Ihre App den Bereich email verwendet, muss sie mit Szenarien umgehen können, in denen das Token keinen Anspruch vom Typ email enthält.

Der profile-Bereich

Der Bereich profile kann mit dem Bereich openid und mit beliebigen anderen Bereichen kombiniert werden. Er ermöglicht der App Zugriff auf eine Vielzahl von Benutzerinformationen. Dazu gehören u. a. Vorname, Nachname, bevorzugter Benutzername und Objekt-ID des Benutzers bzw. der Benutzerin.

Eine vollständige Liste der Ansprüche vom Typ profile, die im Parameter id_tokens für einen bestimmten Benutzer verfügbar sind, finden Sie in der Referenz zu id_tokens.

Der offline_access-Bereich

Mit dem offline_access-Bereich kann Ihre App im Auftrag des Benutzers für einen längeren Zeitraum auf Ressourcen zugreifen. Auf der Einwilligungsseite wird dieser Bereich als Berechtigung Zugriff auf Daten erhalten, auf die Sie Zugriff gewährt haben angezeigt.

Wenn ein Benutzer den offline_access-Bereich genehmigt, kann Ihre App Aktualisierungstoken vom Microsoft Identity Platform-Tokenendpunkt empfangen. Aktualisierungstoken sind langlebig. Ihrer App kann neue Zugriffstoken abrufen, wenn ältere ablaufen.

Im Rahmen von Microsoft Identity Platform (Anforderungen an den v2.0-Endpunkt) muss Ihre App explizit den Bereich offline_access anfordern, um Aktualisierungstoken zu erhalten. Beim Einlösen eines Autorisierungscodes im OAuth 2.0-Autorisierungscodefluss erhalten Sie vom Endpunkt /token also nur ein Zugriffstoken.

Das Zugriffstoken ist in der Regel für etwa eine Stunde gültig. Zu diesem Zeitpunkt muss Ihre App den/die Benutzer*in an den /authorize-Endpunkt zurückleiten, um einen neuen Autorisierungscode anzufordern. Je nach App-Typ muss der/die Benutzer*in während dieser Umleitung die Anmeldeinformationen möglicherweise erneut eingeben oder erneut in die Berechtigungen einwilligen.

Das Aktualisierungstoken hat einen längeren Ablauf als das Zugriffstoken und ist in der Regel für einen Tag gültig. Weitere Informationen zum Abrufen und Verwenden von Aktualisierungstoken finden Sie in der Microsoft Identity Platform-Protokollreferenz.

Die Einbeziehung des Aktualisierungstokens in die Antwort kann von mehreren Faktoren abhängen, einschließlich der spezifischen Konfiguration Ihrer Anwendung und der während des Autorisierungsprozesses angeforderten Bereiche. Wenn Sie erwarten, dass ein Aktualisierungstoken in der Antwort empfangen wird, aber nicht erfolgreich ist, berücksichtigen Sie die folgenden Faktoren:

• Umfangsanforderungen: Stellen Sie sicher, dass Sie die offline_access Bereiche zusammen mit anderen erforderlichen Bereichen anfordern.
• Autorisierungserteilungstyp: Das Aktualisierungstoken wird in der Regel bei Verwendung des Autorisierungscodegenehmigungstyps bereitgestellt. Wenn sich ihr Fluss unterscheidet, kann er sich auf die Antwort auswirken.
• Clientkonfiguration: Überprüfen Sie die Einstellungen Ihrer Anwendung in der Identitätsplattform. Bestimmte Konfigurationen können die Ausstellung von refresh_tokens einschränken.

Der .default-Bereich

Der .default Bereich wird verwendet, um in einer Anforderung generisch auf einen Ressourcendienst (API) zu verweisen, ohne bestimmte Berechtigungen zu identifizieren. Wenn die Zustimmung erforderlich ist, signalisiert die Verwendung von .default , dass die Zustimmung für alle erforderlichen Berechtigungen angefordert werden sollte, die in der Anwendungsregistrierung aufgeführt sind (für alle APIs in der Liste).

Der Bereichsparameterwert wird mithilfe des Bezeichner-URI für die Ressource und .default erstellt, getrennt durch einen Schrägstrich (/). Wenn der Bezeichner-URI der Ressource beispielsweise https://contoso.com ist, lautet der angeforderte Bereich https://contoso.com/.default. Informationen zu Fällen, in denen ein zweiter Schrägstrich erforderlich ist, damit das Token ordnungsgemäß angefordert wird, finden Sie im Abschnitt zu nachgestellten Schrägstrichen.

Die Verwendung von scope={resource-identifier}/.default ist funktional identisch mit resource={resource-identifier} auf dem v1.0-Endpunkt (wobei {resource-identifier} der Bezeichner-URI für die API ist, z. B. https://graph.microsoft.com für Microsoft Graph).

Der .default Bereich kann in jedem OAuth 2.0-Flow und zum Initiieren von Administratoreinwilligung verwendet werden. Im On-Behalf-Of-Fluss und im Flow für Clientanmeldeinformationen ist er jedoch erforderlich.

Clients können keine statische (.default) und dynamische Einwilligung in einer einzelnen Anforderung kombinieren. scope=https://graph.microsoft.com/.default Mail.Read führt daher zu einem Fehler, da hier Bereichstypen kombiniert werden.

.default, wenn der/die Benutzer*in bereits eingewilligt hat

Der Bereichsparameter .default löst nur dann eine Einwilligungsaufforderung aus, wenn für keine delegierte Berechtigung zwischen Client und Ressource im Auftrag des angemeldeten Benutzers eine Einwilligung erteilt wurde.

Wenn eine Einwilligung vorliegt, enthält das zurückgegebene Token alle Bereiche, die dem angemeldeten Benutzer für diese Ressource gewährt wurden. Wenn jedoch keine Berechtigung für die angeforderte Ressource erteilt wurde (oder wenn der Parameter prompt=consent angegeben wurde), wird eine Zustimmungsaufforderung für alle erforderlichen Berechtigungen angezeigt, die bei der Clientanwendungsregistrierung für alle APIs in der Liste konfiguriert wurden.

Wenn beispielsweise der Bereich https://graph.microsoft.com/.default angefordert wird, fordert Ihre Anwendung ein Zugriffstoken für die Microsoft Graph-API an. Wenn mindestens eine delegierte Berechtigung für Microsoft Graph im Namen des angemeldeten Benutzers erteilt wurde, wird die Anmeldung fortgesetzt, und alle delegierten Microsoft Graph-Berechtigungen, die diesem Benutzer erteilt wurden, werden in das Zugriffstoken aufgenommen. Wenn für die angeforderte Ressource keine Berechtigungen erteilt wurden (in diesem Beispiel Microsoft Graph), wird eine Zustimmungsaufforderung für alle erforderlichen Berechtigungen angezeigt, die für die Anwendung konfiguriert sind, für alle APIs in der Liste.

Beispiel 1: Der Benutzer oder Administrator des Mandanten hat die Berechtigungen erteilt.

In diesem Beispiel hat der Benutzer (oder ein Mandantenadministrator) dem Client die Microsoft Graph-Berechtigungen Mail.Read und User.Read erteilt.

Wenn der Client scope=https://graph.microsoft.com/.default anfordert, wird unabhängig vom Inhalt der für Microsoft Graph registrierten Berechtigungen der Clientanwendungen keine Einwilligungsaufforderung angezeigt. Das zurückgegebene Token enthält die Bereiche Mail.Read und User.Read.

Beispiel 2: Der Benutzer hat keine Berechtigungen zwischen dem Client und der Ressource erteilt.

In diesem Beispiel hat weder der Benutzer, noch der Administrator eine Einwilligung zwischen dem Client und Microsoft Graph erteilt. Der Client hat sich für die Berechtigungen User.Read und Contacts.Read registriert. Außerdem hat er sich für den Azure Key Vault-Bereich https://vault.azure.net/user_impersonation registriert.

Wenn der Client ein Token für scope=https://graph.microsoft.com/.default anfordert, sieht der Benutzer eine Zustimmungsseite für die Microsoft Graph-Bereiche User.Read und Contacts.Read sowie für den Azure Key Vault-Bereich user_impersonation. Das zurückgegebene Token enthält nur die User.Read und Contacts.Read Bereiche und kann nur für Microsoft Graph verwendet werden.

Beispiel 3: Der Benutzer hat eingewilligt, und der Client fordert zusätzliche Bereiche an.

In diesem Beispiel hat der Benutzer bereits in Mail.Read für den Client eingewilligt. Der Client hat sich für den Bereich Contacts.Read registriert.

Der Client führt zunächst eine Anmeldung mit scope=https://graph.microsoft.com/.default aus. Basierend auf dem scopes Parameter der Antwort erkennt der Code der Anwendung, dass nur Mail.Read gewährt wurde. Der Client initiiert dann eine zweite Anmeldung mithilfe von scope=https://graph.microsoft.com/.default, und dieses Mal erzwingt er die Zustimmung mithilfe von prompt=consent. Wenn der Benutzer für alle Berechtigungen, die die Anwendung registriert hat, seine Einwilligung geben darf, wird ihm die Einwilligungsaufforderung angezeigt. (Andernfalls wird eine Fehlermeldung oder das Formular zum Anfordern der Administratoreinwilligung angezeigt.) Sowohl Contacts.Read als auch Mail.Read werden in der Einwilligungsaufforderung angezeigt. Wenn die Zustimmung erteilt wird und die Anmeldung fortgesetzt wird, ist das zurückgegebene Token für Microsoft Graph und enthält Mail.Read und Contacts.Read.

Verwenden des Bereichs .default mit dem Client

In bestimmten Fällen kann ein Client seinen eigenen Bereich vom Typ .default anfordern. Das folgende Beispiel veranschaulicht dieses Szenario.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
    ?response_type=token            //Code or a hybrid flow is also possible here
    &client_id=00001111-aaaa-2222-bbbb-3333cccc4444
    &scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
    &redirect_uri=https%3A%2F%2Flocalhost
    &state=1234

In diesem Codebeispiel wird eine Einwilligungsseite für alle registrierten Berechtigungen generiert, wenn die obigen Beschreibungen von Einwilligung und .default für das Szenario gelten. Anschließend gibt der Code kein Zugriffstoken, sondern ein ID-Token (id_token) zurück.

Dieses Setup sollte nicht für neue Clients verwendet werden, die für Microsoft Identity Platform konzipiert sind. Stellen Sie sicher, dass Sie von der Azure AD-Authentifizierungsbibliothek (Azure AD Authentication Library, ADAL) zu MSAL (Microsoft Authentication Library) migrieren.

Zuweisungsflow für Clientanmeldeinformationen und .default

Eine weitere Verwendung von .default ist das Anfordern von Anwendungsrollen (auch bekannt als Anwendungsberechtigungen) in einer nicht interaktiven Anwendung wie einer Daemon-App, die den Zuweisungs-Flow für Client-Anmeldedaten verwendet, um eine Web-API aufzurufen.

Informationen zum Definieren von Anwendungsrollen (Anwendungsberechtigungen) für eine Web-API finden Sie unter Anwendungsrollen zu Ihrer Anwendung hinzufügen.

Anforderungen von Clientanmeldeinformationen in Ihrer Client-App müssenscope={resource}/.default enthalten. Hier ist {resource} die Web-API, die Ihre Anwendung aufrufen möchte und für die ein Zugriffstoken abgerufen werden soll. Das Erstellen einer Anforderung von Clientanmeldeinformationen mit individuellen Anwendungsberechtigungen (Rollen) wird nicht unterstützt. Alle Anwendungsrollen (Anwendungsberechtigungen), die dieser Web-API erteilt wurden, sind im zurückgegebenen Zugriffstoken enthalten.

Informationen zum Gewähren des Zugriffs auf die von Ihnen definierten Anwendungsrollen, einschließlich der Administratoreinwilligung für die Anwendung, finden Sie unter Konfigurieren einer Clientanwendung für den Zugriff auf eine Web-API.

Nachstehender Schrägstrich und .default

Einige Ressourcen-URIs enthalten einen nachgestellten Schrägstrich (beispielsweise https://contoso.com/ anstelle von https://contoso.com). Der nachgestellte Schrägstrich kann zu Problemen bei der Tokenüberprüfung führen. Probleme treten in erster Linie auf, wenn ein Token für Azure Resource Manager (https://management.azure.com/) angefordert wird.

In diesem Fall bedeutet ein nachgestellter Schrägstrich im Ressourcen-URI, dass der Schrägstrich vorhanden sein muss, wenn das Token angefordert wird. Wenn Sie also ein Token für https://management.azure.com/ anfordern möchten und dabei .default verwenden, müssen Sie https://management.azure.com//.default (mit doppeltem Schrägstrich) anfordern.

Im Allgemeinen gilt: Wenn Sie sich vergewissert haben, dass das Token ausgestellt wird, und das Token von der API abgelehnt wird, obwohl sie es eigentlich akzeptieren sollte, können Sie versuchen, einen zweiten Schrägstrich hinzufügen und den Vorgang zu wiederholen.

Siehe auch

• Anfordern von Berechtigungen über die Einwilligung in Microsoft Identity Platform
• Microsoft Identity Platform – ID-Token
• Microsoft Identity Platform – Zugriffstoken