Schnellstart: Konfigurieren einer Clientanwendung für den Zugriff auf eine Web-APIQuickstart: Configure a client application to access a web API

In dieser Schnellstartanleitung stellen Sie eine bei der Microsoft Identity Platform registrierte Client-App mit bereichsbezogenem, berechtigungsbasiertem Zugriff auf Ihre eigene Web-API bereit.In this quickstart, you provide a client app registered with the Microsoft identity platform with scoped, permissions-based access to your own web API. Außerdem ermöglichen Sie der Client-App den Zugriff auf Microsoft Graph.You also provide the client app access to Microsoft Graph.

Wenn Sie die Bereiche einer Web-API in der Registrierung Ihrer Client-App angeben, kann die Client-App ein Zugriffstoken mit diesen Bereichen von der Microsoft Identity Platform abrufen.By specifying a web API's scopes in your client app's registration, the client app can obtain an access token containing those scopes from the Microsoft identity platform. Innerhalb des Codes kann die Web-API dann berechtigungsbasierten Zugriff auf die zugehörigen Ressourcen basierend auf den im Zugriffstoken enthaltenen Bereichen bereitstellen.Within its code, the web API can then provide permission-based access to its resources based on the scopes found in the access token.

VoraussetzungenPrerequisites

Hinzufügen von Berechtigungen für den Zugriff auf Ihre Web-APIAdd permissions to access your web API

Im ersten Szenario gewähren Sie einer Client-App Zugriff auf Ihre eigene Web-API. Sie müssen sowohl die Client-App als auch die Web-API als Teil der Voraussetzungen registriert haben.In the first scenario, you grant a client app access to your own web API, both of which you should have registered as part of the prerequisites. Wenn Sie noch nicht sowohl eine Client-App als auch eine Web-API registriert haben, führen Sie die unter Voraussetzungen beschriebenen Schritte aus.If you don't yet have both a client app and a web API registered, complete the steps in the two Prerequisites articles.

Im folgenden Diagramm ist dargestellt, wie die beiden App-Registrierungen zueinander in Beziehung stehen.This diagram shows how the two app registrations relate to one another. In diesem Abschnitt fügen Sie der Registrierung der Client-App Berechtigungen hinzu.In this section, you add permissions to the client app's registration.

Liniendiagramm mit einer Web-API mit verfügbar gemachten Bereichen auf der rechten Seite und einer Client-App auf der linken Seite mit diesen als Berechtigungen ausgewählten Bereichen

Nachdem Sie sowohl die Client-App als auch die Web-API registriert und die API durch das Erstellen von Bereichen verfügbar gemacht haben, können Sie die Berechtigungen der Client-App für die API konfigurieren, indem Sie die folgenden Schritte ausführen:Once you've registered both your client app and web API and you've exposed the API by creating scopes, you can configure the client's permissions to the API by following these steps:

  1. Melden Sie sich beim Azure-Portal an.Sign in to the Azure portal.

  2. Wenn Sie Zugriff auf mehrere Mandanten haben, verwenden Sie im oberen Menü den Filter Verzeichnis + Abonnement  , um den Mandanten auszuwählen, der die Registrierung der Client-App enthält.

  3. Wählen Sie Azure Active Directory > App-Registrierungen aus, und wählen Sie dann Ihre Client Anwendung aus (nicht Ihre Web-API).Select Azure Active Directory > App registrations, and then select your client application (not your web API).

  4. Wählen Sie über die Option API-Berechtigungen > Berechtigung hinzufügen > Meine APIs aus.Select API permissions > Add a permission > My APIs.

  5. Wählen Sie die Web-API aus, die Sie als Teil der Voraussetzungen registriert haben.Select the web API you registered as part of the prerequisites.

    Die Option Delegierte Berechtigungen ist standardmäßig ausgewählt.Delegated permissions is selected by default. Delegierte Berechtigungen sind für Client-Apps geeignet, die als angemeldeter Benutzer auf eine Web-API zugreifen und deren Zugriff auf die Berechtigungen beschränkt werden sollte, die Sie im nächsten Schritt auswählen.Delegated permissions are appropriate for client apps that access a web API as the signed-in user, and whose access should be restricted to the permissions you select in the next step. Übernehmen Sie für dieses Beispiel die ausgewählte Option Delegierte Berechtigungen.Leave Delegated permissions selected for this example.

    Anwendungsberechtigungen sind für Anwendungen vom Typ „Dienst“ oder „Daemon“ vorgesehen, die als solche auf eine Web-API zugreifen müssen, ohne dass eine Benutzerinteraktion für die Anmeldung oder Zustimmung erforderlich ist.Application permissions are for service- or daemon-type applications that need to access a web API as themselves, without user interaction for sign-in or consent. Sofern Sie keine Anwendungsrollen für Ihre Web-API definiert haben, ist diese Option deaktiviert.Unless you've defined application roles for your web API, this option is disabled.

  6. Erweitern Sie unter Berechtigungen auswählen die Ressource, deren Bereiche Sie für Ihre Web-API definiert haben, und wählen Sie die Berechtigungen aus, über die die Client-App im Namen des angemeldeten Benutzers verfügen soll.Under Select permissions, expand the resource whose scopes you defined for your web API, and select the permissions the client app should have on behalf of the signed-in user.

    Wenn Sie die im vorherigen Schnellstart angegebenen Beispielbereichsnamen verwendet haben, sollten Employees.Read.All und Employees.Write.All angezeigt werden.If you used the example scope names specified in the previous quickstart, you should see Employees.Read.All and Employees.Write.All. Wählen Sie Employees.Read.All oder eine andere Berechtigung aus, die Sie ggf. beim Ausführen der Schritte für die Voraussetzungen erstellt haben.Select Employees.Read.All or another permission you might have created when completing the prerequisites.

  7. Wählen Sie Berechtigungen hinzufügen aus, um den Vorgang abzuschließen.Select Add permissions to complete the process.

Nachdem Sie Ihrer API Berechtigungen hinzugefügt haben, sollten die ausgewählten Berechtigungen unter Konfigurierte Berechtigungen angezeigt werden.After adding permissions to your API, you should see the selected permissions under Configured permissions. In der folgenden Abbildung sehen Sie beispielhaft, dass die delegierte Berechtigung Employees.Read.All zur Registrierung der Client-App hinzugefügt wurde.The following image shows the example Employees.Read.All delegated permission added to the client app's registration.

Der Bereich „Konfigurierte Berechtigungen“ im Azure-Portal mit der neu hinzugefügten Berechtigung

Möglicherweise sehen Sie auch die Berechtigung User.Read für die Microsoft Graph-API.You might also notice the User.Read permission for the Microsoft Graph API. Diese Berechtigung wird automatisch hinzugefügt, wenn Sie eine App im Azure-Portal registrieren.This permission is added automatically when you register an app in the Azure portal.

Hinzufügen von Berechtigungen für den Zugriff auf Microsoft GraphAdd permissions to access Microsoft Graph

Zusätzlich zum Zugriff auf Ihre eigene Web-API im Namen des angemeldeten Benutzers muss Ihre Anwendung möglicherweise auch auf die in Microsoft Graph gespeicherten Daten des Benutzers (oder andere Daten) zugreifen oder diese ändern.In addition to accessing your own web API on behalf of the signed-in user, your application might also need to access or modify the user's (or other) data stored in Microsoft Graph. Möglicherweise verfügen Sie auch über eine Dienst- oder Daemon-App, die als solche auf Microsoft Graph zugreifen muss und Vorgänge ohne Benutzerinteraktion ausführt.Or you might have service or daemon app that needs to access Microsoft Graph as itself, performing operations without any user interaction.

Delegierte Berechtigung für Microsoft GraphDelegated permission to Microsoft Graph

Konfigurieren Sie die delegierte Berechtigung für Microsoft Graph, damit Ihre Clientanwendung Vorgänge im Namen des angemeldeten Benutzers ausführen kann, z. B. das Lesen seiner E-Mail oder das Ändern seines Profils.Configure delegated permission to Microsoft Graph to enable your client application to perform operations on behalf of the logged-in user, for example reading their email or modifying their profile. Standardmäßig werden die Benutzer Ihrer Client-App bei der Anmeldung aufgefordert, den delegierten Berechtigungen zuzustimmen, die Sie für die App konfiguriert haben.By default, users of your client app are asked when they sign in to consent to the delegated permissions you've configured for it.

  1. Melden Sie sich beim Azure-Portal an.Sign in to the Azure portal.

  2. Wenn Sie Zugriff auf mehrere Mandanten haben, verwenden Sie im oberen Menü den Filter Verzeichnis + Abonnement  , um den Mandanten auszuwählen, der die Registrierung der Client-App enthält.

  3. Wählen Sie Azure Active Directory > App-Registrierungen aus, und wählen Sie dann Ihre Client Anwendung aus.Select Azure Active Directory > App registrations, and then select your client application.

  4. Wählen Sie API-Berechtigungen > Berechtigung hinzufügen > Microsoft Graph aus.Select API permissions > Add a permission > Microsoft Graph

  5. Wählen Sie Delegierte Berechtigungen aus.Select Delegated permissions. Microsoft Graph macht viele Berechtigungen verfügbar, wobei die am häufigsten verwendeten Berechtigungen am Anfang der Liste angezeigt werden.Microsoft Graph exposes many permissions, with the most commonly used shown at the top of the list.

  6. Wählen Sie unter Berechtigungen auswählen die folgenden Berechtigungen aus:Under Select permissions, select the following permissions:

    BerechtigungPermission BESCHREIBUNGDescription
    email Anzeigen der E-Mail-Adresse des BenutzersView users' email address
    offline_access Zugriff auf Daten beibehalten, für die Sie der App Zugriff erteilt habenMaintain access to data you have given it access to
    openid Anmelden von BenutzernSign users in
    profile Anzeigen des grundlegenden BenutzerprofilsView users' basic profile
  7. Wählen Sie Berechtigungen hinzufügen aus, um den Vorgang abzuschließen.Select Add permissions to complete the process.

Wenn Sie Berechtigungen konfigurieren, werden die Benutzer Ihrer App bei der Anmeldung aufgefordert, ihre Zustimmung zu erteilen, damit Ihre App in ihrem Namen auf die Ressourcen-API zugreifen kann.Whenever you configure permissions, users of your app are asked at sign-in for their consent to allow your app to access the resource API on their behalf.

Als Administrator können Sie auch die Zustimmung im Namen aller Benutzer erteilen, damit diese nicht dazu aufgefordert werden.As an admin, you can also grant consent on behalf of all users so they're not prompted to do so. Die Administratoreinwilligung wird weiter unten im Abschnitt Weitere Informationen zu API-Berechtigungen und zur Administratoreinwilligung dieses Artikels erläutert.Admin consent is discussed later in the More on API permissions and admin consent section of this article.

Anwendungsberechtigung für Microsoft GraphApplication permission to Microsoft Graph

Konfigurieren Sie Anwendungsberechtigungen für eine Anwendung, die sich ohne Benutzerinteraktion oder Zustimmung als sie selbst authentifizieren muss.Configure application permissions for an application that needs to authenticate as itself without user interaction or consent. Anwendungsberechtigungen werden in der Regel von Hintergrunddiensten oder Daemon-Apps verwendet, die „monitorlos“ auf eine API zugreifen, und von Web-APIs, die auf eine andere (nachgeschaltete) API zugreifen.Application permissions are typically used by background services or daemon apps that access an API in a "headless" manner, and by web APIs that access another (downstream) API.

In den folgenden Schritten erteilen Sie die Berechtigung für die Microsoft Graph-Berechtigung Files.Read.All als Beispiel.In the following steps, you grant permission to Microsoft Graph's Files.Read.All permission as an example.

  1. Melden Sie sich beim Azure-Portal an.Sign in to the Azure portal.

  2. Wenn Sie Zugriff auf mehrere Mandanten haben, verwenden Sie im oberen Menü den Filter Verzeichnis + Abonnement  , um den Mandanten auszuwählen, der die Registrierung der Client-App enthält.

  3. Wählen Sie Azure Active Directory > App-Registrierungen aus, und wählen Sie dann Ihre Client Anwendung aus.Select Azure Active Directory > App registrations, and then select your client application.

  4. Wählen Sie API-Berechtigungen > Berechtigung hinzufügen > Microsoft Graph > Anwendungsberechtigungen aus.Select API permissions > Add a permission > Microsoft Graph > Application permissions.

  5. Alle von Microsoft Graph verfügbar gemachten Berechtigungen werden unter Berechtigungen auswählen angezeigt.All permissions exposed by Microsoft Graph are shown under Select permissions.

  6. Wählen Sie die Berechtigung(en) aus, die Sie Ihrer Anwendung erteilen möchten.Select the permission or permissions you want to grant your application. Beispielsweise verfügen Sie möglicherweise über eine Daemon-App, die Dateien in Ihrer Organisation überprüft und bei bestimmten Dateitypen oder -namen eine Warnung ausgibt.As an example, you might have a daemon app that scans files in your organization, alerting on a specific file type or name.

    Erweitern Sie unter Berechtigungen auswählen die Option Dateien, und wählen Sie dann die Berechtigung Files.Read.All aus.Under Select permissions, expand Files, and then select the Files.Read.All permission.

  7. Wählen Sie Berechtigungen hinzufügen aus.Select Add permissions.

Einige Berechtigungen (wie z. B. die Microsoft Graph-Berechtigung Files.Read.All) erfordern die Zustimmung des Administrators.Some permissions, like Microsoft Graph's Files.Read.All permission, require admin consent. Sie erteilen die Administratoreinwilligung, indem Sie die Schaltfläche Administratoreinwilligung erteilen auswählen, die weiter unten im Abschnitt Schaltfläche „Administratorzustimmung“ erläutert wird.You grant admin consent by selecting the Grant admin consent button, discussed later in the Admin consent button section.

Konfigurieren von ClientanmeldeinformationenConfigure client credentials

Apps, die Anwendungsberechtigungen verwenden, authentifizieren sich mit ihren eigenen Anmeldeinformationen als sie selbst, ohne dass eine Benutzerinteraktion erforderlich ist.Apps that use application permissions authenticate as themselves by using their own credentials, without requiring any user interaction. Bevor Ihre Anwendung (oder API) auf Microsoft Graph, Ihre eigene Web-API oder eine andere API mithilfe von Anwendungsberechtigungen zugreifen kann, müssen Sie die Anmeldeinformationen dieser Client-App konfigurieren.Before your application (or API) can access Microsoft Graph, your own web API, or another API by using application permissions, you must configure that client app's credentials.

Weitere Informationen zum Konfigurieren der Anmeldeinformationen einer App finden Sie im Abschnitt Hinzufügen von Anmeldeinformationen des Schnellstarts: Registrieren einer Anwendung bei der Microsoft Identity Platform.For more information about configuring an app's credentials, see the Add credentials section of Quickstart: Register an application with the Microsoft identity platform.

Der Bereich API-Berechtigungen einer App-Registrierung enthält eine Tabelle Konfigurierte Berechtigungen und möglicherweise auch eine Tabelle Weitere gewährte Berechtigungen.The API permissions pane of an app registration contains a Configured permissions table, and might also contain an Other permissions granted table. Beide Tabellen sowie die Schaltfläche „Administratorzustimmung“ werden in den folgenden Abschnitten beschrieben.Both tables and the Admin consent button are described in the following sections.

Konfigurierte BerechtigungenConfigured permissions

Die Tabelle Konfigurierte Berechtigungen im Bereich API-Berechtigungen enthält die Liste der Berechtigungen, die Ihre Anwendung zum Ausführen grundlegender Vorgänge benötigt: die Liste erforderlicher Ressourcenzugriff (Required Resource Access, RRA).The Configured permissions table on the API permissions pane shows the list of permissions that your application requires for basic operation - the required resource access (RRA) list. Benutzer oder ihre Administratoren müssen diesen Berechtigungen zustimmen, bevor sie Ihre App verwenden können.Users, or their admins, will need to consent to these permissions before using your app. Andere optionale Berechtigungen können später zur Laufzeit (mit dynamischer Zustimmung) angefordert werden.Other, optional permissions can be requested later at runtime (using dynamic consent).

Dies ist die Liste der Mindestberechtigungen, denen die Benutzer für Ihre App zustimmen müssen.This is the minimum list of permissions people will have to consent to for your app. Es gibt möglicherweise weitere Berechtigungen, aber diese hier werden immer benötigt.There could be more, but these will always be required. Aus Sicherheitsgründen und um die Verwendung Ihrer App für Benutzer und Administratoren angenehmer zu gestalten, sollten Sie nie etwas anfordern, das Sie nicht benötigen.For security and to help users and admins feel more comfortable using your app, never ask for anything you don’t need.

Sie können die in dieser Tabelle angezeigten Berechtigungen hinzufügen oder entfernen, indem Sie die oben beschriebenen Schritte ausführen oder aus Weitere gewährte Berechtigungen (im nächsten Abschnitt beschrieben).You can add or remove the permissions that appear in this table by using the steps outlined above or from Other permissions granted (described in the next section). Als Administrator können Sie die Administratorzustimmung für den vollständigen Satz der in der Tabelle aufgeführten Berechtigungen einer API erteilen und die Zustimmung für einzelne Berechtigungen widerrufen.As an admin, you can grant admin consent for the full set of an API's permissions that appear in the table, and revoke consent for individual permissions.

Weitere gewährte BerechtigungenOther permissions granted

Möglicherweise wird im Bereich API-Berechtigungen auch eine Tabelle mit dem Titel Weitere gewährte Berechtigungen für {Mandant} angezeigt.You might also see a table entitled Other permissions granted for {your tenant} on the API permissions pane. In der Tabelle Weitere gewährte Berechtigungen für {Mandant} werden Berechtigungen angezeigt, die dem Mandanten erteilt, aber nicht explizit für das Anwendungsobjekt konfiguriert wurden.The Other permissions granted for {your tenant} table shows permissions granted for the tenant that haven't been explicitly configured on the application object. Diese Berechtigungen wurden dynamisch angefordert und gewährt.These permissions were dynamically requested and consented to. Dieser Abschnitt wird nur angezeigt, wenn mindestens eine entsprechende Berechtigung vorhanden ist.This section appears only if there is at least one permission that applies.

Sie können den vollständigen Satz der Berechtigungen einer API oder einzelne Berechtigungen, die in dieser Tabelle enthalten sind, zur Tabelle Konfigurierte Berechtigungen hinzufügen.You can add the full set of an API's permissions or individual permissions appearing this table to the Configured permissions table. Als Administrator können Sie in diesem Abschnitt die Administratoreinwilligung für APIs oder einzelne Berechtigungen widerrufen.As an admin, you can revoke admin consent for APIs or individual permissions in this section.

Mithilfe der Schaltfläche Administratoreinwilligung erteilen für {Mandant} kann ein Administrator eine Administratoreinwilligung für die Berechtigungen erteilen, die für die Anwendung konfiguriert sind.The Grant admin consent for {your tenant} button allows an admin to grant admin consent to the permissions configured for the application. Wenn Sie die Schaltfläche auswählen, wird ein Dialogfeld angezeigt, in dem Sie die Einwilligungsaktion bestätigen müssen.When you select the button, a dialog is shown requesting that you confirm the consent action.

Hervorgehobene Schaltfläche „Administratoreinwilligung erteilen“ im Bereich „Konfigurierte Berechtigungen“ im Azure-Portal

Nachdem Sie die Einwilligung erteilt haben, werden die Berechtigungen, für die eine Administratoreinwilligung erforderlich ist, als erteilt angezeigt:After granting consent, the permissions that required admin consent are shown as having consent granted:

Tabelle „Konfigurierte Berechtigungen“ im Azure-Portal mit erteilter Administratoreinwilligung für die Berechtigung „Files.Read.All“

Die Schaltfläche Administratoreinwilligung erteilen ist deaktiviert, wenn Sie kein Administrator sind oder für die Anwendung keine Berechtigungen konfiguriert wurden.The Grant admin consent button is disabled if you aren't an admin or if no permissions have been configured for the application. Wenn Sie über Berechtigungen verfügen, die erteilt, aber noch nicht konfiguriert wurden, werden Sie nach dem Auswählen der Schaltfläche für die Administratoreinwilligung aufgefordert, zu entscheiden, wie mit diesen Berechtigungen verfahren werden soll.If you have permissions that have been granted but not yet configured, the admin consent button prompts you to handle these permissions. Sie können diese Berechtigungen den konfigurierten Berechtigungen hinzufügen oder entfernen.You can add them to configured permissions or remove them.

Nächste SchritteNext steps

In der nächsten Schnellstartanleitung der Reihe erfahren Sie, wie Sie konfigurieren, welche Kontotypen auf Ihre Anwendung zugreifen können.Advance to the next quickstart in the series to learn how to configure which account types can access your application. Beispielsweise möchten Sie den Zugriff auf die Benutzer in Ihrer Organisation (ein Mandant) beschränken oder Benutzer in anderen Azure AD-Mandanten (mehrere Mandanten) und diejenigen mit persönlichen Microsoft-Konten (MSA) zulassen.For example, you might want to limit access only to those users in your organization (single-tenant) or allow users in other Azure AD tenants (multi-tenant) and those with personal Microsoft accounts (MSA).