Freigeben über

Bereiche und Berechtigungen in Microsoft Identity Platform

The Microsoft identity platform implements the OAuth 2.0 authorization protocol. 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 die Funktionalität der Ressource in kleinere Einheiten teilen. As an example, Microsoft Graph defines permissions to do the following tasks, among others:

  • 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, these types of permission sets are called scopes. They're also often referred to as permissions. 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.

Admin-restricted permissions

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: Lesen Sie die vollständigen Profile aller Benutzer
  • Directory.ReadWrite.All: Daten in das Verzeichnis einer Organisation schreiben
  • Groups.Read.All: Alle Gruppen im Verzeichnis einer Organisation lesen

Note

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.

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. Instead, the client application is granted permissions directly. 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. Diese Bereiche sind manchmal optional und gelten für die ID-Tokenanreicherung. Diese Bereiche werden nicht immer in separaten Zeilen in einer Zustimmungsaufforderung für einen Benutzer angezeigt.

If you request the OpenID Connect scopes and a token, you get a token to call the UserInfo endpoint.

Der openid-Bereich

If an app signs in by using OpenID Connect, it must request the openid scope. Der Bereich openid wird auf der Einwilligungsseite des Arbeitskontos als Berechtigung Anmeldung in Ihrem Namen angezeigt.

Eine App verwendet diese Berechtigung, um einen eindeutigen Identifikator für den Benutzer in Form des SPNs zu erhalten. sub Anspruch. 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.

Für eine vollständige Liste der profile Ansprüche verfügbar in der id_tokens für einen bestimmten Benutzer, siehe die id_tokens Referenz.

Der offline_access-Bereich

Die offline_access Reservierungsumfang gibt Ihrer Anwendung für einen längeren Zeitraum Zugriff auf Ressourcen im Namen des Benutzers. Auf der Einwilligungsseite wird dieser Bereich als Berechtigung Zugriff auf Daten erhalten, auf die Sie Zugriff gewährt haben angezeigt.

Wenn delegierte Berechtigungen erteilt werden, wird offline_access implizit erteilt. Sie können davon ausgehen, dass die Anwendung offline_access hat, wenn delegierte Berechtigungen erteilt wurden. Aktualisierungstoken sind langlebig. Ihrer App kann neue Zugriffstoken abrufen, wenn ältere ablaufen.

Note

This permission currently appears on all consent pages, even for flows that don't provide a refresh token (such as the implicit flow). Durch dieses Setup werden Szenarien abgedeckt, in denen ein Client im impliziten Fluss beginnt und anschließend mit dem Codefluss fortfährt, in dem ein Aktualisierungstoken erwartet wird.

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 ein Zugriffstoken.

Das Zugriffstoken ist 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 90 Tage gültig. Weitere Informationen zum Abrufen und Verwenden von Aktualisierungstoken finden Sie in der Microsoft Identity Platform-Protokollreferenz.

Die Aufnahme des Aktualisieren-Tokens in die Antwort kann von mehreren Faktoren abhängen, darunter die spezifische Konfiguration Ihrer Anwendung und die während des Autorisierungsprozesses angeforderten Reservierungsumfänge. Wenn Sie erwarten, ein Aktualisierungs-Token in der Antwort zu erhalten, dies aber nicht der Fall ist, sollten Sie die folgenden Faktoren berücksichtigen:

  • Scope requirements: Ensure that you're requesting the offline_access scopes along with any other necessary scopes.
  • Typ der Berechtigungserteilung: Das Aktualisierungs-Token wird bei der Verwendung des Berechtigungscode-Zuschuss-Typs bereitgestellt. Wenn Ihr Flow abweicht, kann die Antwort beeinflusst werden.
  • Client configuration: Check your application's settings in the identity platform. Bestimmte Konfigurationen können die Ausgabe 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).

The .default scope can be used in any OAuth 2.0 flow and to initiate admin consent. Its use is required in the On-Behalf-Of flow and client credentials flow.

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.

Die .default Der Reservierungsumfang-Parameter löst nur dann eine Zustimmungsaufforderung aus, wenn die Zustimmung für eine delegierte Berechtigung zwischen dem Client und der Ressource im Namen des angemeldeten Benutzers nicht 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. Alle delegierten Microsoft Graph-Berechtigungen, die für diesen Benutzer gewährt 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, der sich für die User.Read und Contacts.Read Berechtigungen und für den Reservierungsumfang von Azure Key Vault registriert https://vault.azure.net/user_impersonation.

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, zustimmen darf, wird ihm die Aufforderung zur Zustimmung angezeigt. (Wenn nicht, wird eine Fehlermeldung angezeigt oder die Admin-Zustimmungsanforderung Form). Beide Contacts.Read und Mail.Read sind in der Zustimmungsaufforderung. 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.

Neue Clients, die auf die Microsoft Identity Platform ausgerichtet sind, sollten dieses Setup nicht verwenden. Stellen Sie sicher, dass Sie Migrieren Sie zur Microsoft Authentifizierung Bibliothek (MSAL) von der Azure AD Authentifizierung Bibliothek (ADAL).

Zuweisungsflow für Clientanmeldeinformationen und .default

Another use of .default is to request app roles (also known as application permissions) in a non-interactive application like a daemon app that uses the client credentials grant flow to call a web API.

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

Client credentials requests in your client service must include scope={resource}/.default. Hier ist {resource} die Web-API, die Ihre Anwendung aufrufen möchte und für die ein Zugriffstoken abgerufen werden soll. Issuing a client credentials request by using individual application permissions (roles) is not supported. 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.

See also

  • Last updated on