Schnellstart: Aufrufen einer durch Microsoft Identity Platform geschützten ASP.NET-Web-API

In dieser Schnellstartanleitung laden Sie ein Codebeispiel herunter und führen es aus, das zeigt, wie Sie eine ASP.NET-Web-API schützen, indem Sie den Zugriff auf die Ressourcen ausschließlich auf autorisierte Konten beschränken. Das Beispiel unterstützt die Autorisierung von persönlichen Microsoft-Konten sowie Konten in einer beliebigen Microsoft Entra-Organisation.

Der Artikel verwendet auch eine Windows Presentation Foundation (WPF)-App, um zu veranschaulichen, wie Sie ein Zugriffstoken für den Zugriff auf eine Web-API anfordern können.

Voraussetzungen

• Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
• Visual Studio 2017 oder 2019. Laden Sie Visual Studio kostenlos herunter.

Klonen oder Herunterladen des Beispiels

Zum Abrufen des Beispiels gibt es zwei Möglichkeiten:

• Clonen von der Shell oder der Befehlszeile:

  git clone https://github.com/AzureADQuickStarts/AppModelv2-NativeClient-DotNet.git
  

• Herunterladen als ZIP-Datei.

Registrieren der Web-API (TodoListService)

Registrieren Sie Ihre Web-API im Azure-Portal unter App-Registrierungen.

1. Melden Sie sich beim Microsoft Entra Admin Center mindestens mit der Rolle Anwendungsadministrator an.

2. Navigieren Sie zu Identität>Anwendungen>App-Registrierungen.

3. Wählen Sie Neue Registrierung aus.

4. Geben Sie unter Name einen Namen für Ihre Anwendung ein (beispielsweise AppModelv2-NativeClient-DotNet-TodoListService). Benutzern Ihrer App wird wahrscheinlich dieser Namen angezeigt. Sie können ihn später ändern.

5. Wählen Sie unter Unterstützte Kontotypen die Option Konten in einem beliebigen Organisationsverzeichnis aus.

6. Wählen Sie Registrieren aus, um die Anwendung zu erstellen.

7. Suchen Sie auf der Seite Übersicht für die App den Wert von Anwendungs-ID (Client) , und notieren Sie ihn zur späteren Verwendung. Sie benötigen diesen Wert, um die Visual Studio-Konfigurationsdatei für dieses Projekt (d. h. ClientId in der Datei TodoListService\Web.config) zu konfigurieren.

8. Wählen Sie unter Verwalten die Optionen Eine API verfügbar machen>Bereich hinzufügen aus. Übernehmen Sie den vorgeschlagenen Anwendungs-ID-URI (api://{clientId}> ), indem Sie Speichern und fortfahren auswählen. Geben Sie dann die folgenden Informationen ein:

   1. Geben Sie access_as_user als access_as_user ein.
   2. Stellen Sie sicher, dass unter Zum Einwilligen berechtigte Personen die Option Administratoren und Benutzer ausgewählt ist.
   3. Geben Sie Access TodoListService as a user im Feld Anzeigename der Administratorzustimmung ein.
   4. Geben Sie Accesses the TodoListService web API as a user im Feld Beschreibung der Administratorzustimmung ein.
   5. Geben Sie Access TodoListService as a user im Feld Anzeigename der Benutzereinwilligung ein.
   6. Geben Sie Accesses the TodoListService web API as a user im Feld Beschreibung der Benutzereinwilligung ein.
   7. Übernehmen Sie Aktiviert als Status.

9. Wählen Sie Bereich hinzufügen aus.

Konfigurieren des Dienstprojekts

Konfigurieren Sie das Dienstprojekt für die registrierte Web-API.

1. Öffnen Sie die Projektmappe in Visual Studio, und öffnen Sie dann im Stammverzeichnis des TodoListService-Projekts die Datei Web.config.

2. Ersetzen Sie den Wert des ida:ClientId-Parameters durch den Wert der Client-ID (Anwendungs-ID) der Anwendung, die Sie im Portal unter App-Registrierungen registriert haben.

Hinzufügen des neuen Bereichs zur Datei „app.config“

Führen Sie die folgenden Schritte aus, um den neuen Bereich zur Datei app.config des TodoListClient-Projekts hinzuzufügen:

1. Öffnen Sie im Stammordner des TodoListClient-Projekts die Datei app.config.

2. Fügen Sie die Anwendungs-ID aus der Anwendung ein, die Sie im TodoListServiceScope-Parameter für das TodoListService-Projekt registriert haben, und ersetzen Sie dabei die Zeichenfolge {Enter the Application ID of your TodoListService from the app registration portal}.

Registrieren der Web-App (TodoListClient)

Registrieren Sie im Azure-Portal unter App-Registrierungen die TodoListClient-App, und konfigurieren Sie dann den Code im TodoListClient-Projekt. Wenn Client und Server als ein und dieselbe Anwendung betrachtet werden, können Sie die Anwendung wiederverwenden, die Sie in Schritt 2 registriert haben. Verwenden Sie dieselbe Anwendung, wenn sich Ihre Benutzer mit einem persönlichen Microsoft-Konto anmelden sollen.

Registrieren der App

Führen Sie die folgenden Schritte aus, um die TodoListClient-App zu registrieren:

1. Navigieren Sie in Microsoft Identity Platform für Entwickler zum Portal App-Registrierungen.

2. Wählen Sie Neue Registrierung aus.

3. Wenn die Seite Anwendung registrieren geöffnet wird, geben Sie die Registrierungsinformationen Ihrer Anwendung ein:

   1. Geben Sie im Abschnitt Name einen aussagekräftigen Anwendungsnamen ein, der den Benutzern der App angezeigt wird (z. B. NativeClient-DotNet-TodoListClient).
   2. Wählen Sie unter Unterstützte Kontotypen die Option Konten in einem beliebigen Organisationsverzeichnis aus.
   3. Wählen Sie Registrieren aus, um die Anwendung zu erstellen.

   Hinweis

   In der Datei app.config des TodoListClient-Projekts ist der Standardwert für ida:Tenant auf common festgelegt. Mögliche Werte sind:

   • common: Sie können sich mit einem Geschäfts-, Schul- oder Unikonto oder einem persönlichen Microsoft-Konto anmelden (aufgrund der Auswahl von Konten in einem beliebigen Organisationsverzeichnis in einem vorherigen Schritt).
   • organizations: Sie können sich mit einem Geschäfts-, Schul- oder Unikonto anmelden.
   • consumers: Sie können sich nur mit einem persönlichen Microsoft-Konto anmelden.

4. Wählen Sie auf der Seite Übersicht der App die Option Authentifizierung aus, und führen Sie dann die folgenden Schritte aus, um eine Plattform hinzuzufügen:

   1. Wählen Sie unter Plattformkonfigurationen die Schaltfläche Plattform hinzufügen aus.
   2. Wählen Sie unter Mobilgerät- und Desktopanwendungen die Option Mobilgerät- und Desktopanwendungen aus.
   3. Aktivieren Sie unter Umleitungs-URIs das Kontrollkästchen https://login.microsoftonline.com/common/oauth2/nativeclient .
   4. Wählen Sie Konfigurierenaus.

5. Wählen Sie API-Berechtigungen aus, und führen Sie dann die folgenden Schritte aus, um Berechtigungen hinzuzufügen:

   1. Wählen Sie die Schaltfläche Berechtigung hinzufügen.
   2. Wählen Sie die Registerkarte Meine APIs aus.
   3. Wählen Sie in der API-Liste den Namen AppModelv2-NativeClient-DotNet-TodoListService API bzw. den Namen aus, den Sie für die Web-API eingegeben haben.
   4. Aktivieren Sie das Kontrollkästchen für die Berechtigung access_as_user, falls es nicht bereits aktiviert ist. Verwenden Sie bei Bedarf das Suchfeld.
   5. Wählen Sie die Schaltfläche Berechtigungen hinzufügen aus.

Konfigurieren des Projekts

Konfigurieren Sie Ihr TodoListClient-Projekt, indem Sie die Anwendungs-ID zur Datei app.config hinzufügen.

1. Kopieren Sie im Portal App-Registrierungen auf der Seite Übersicht den Wert von Anwendungs-ID (Client) .

2. Öffnen Sie die Datei app.config, die sich im Stammordner des TodoListClient-Projekts befindet, und fügen Sie dann den Wert der Anwendungs-ID in den ida:ClientId-Parameter ein.

Ihre Projekte ausführen

Starten Sie beide Projekte. Wenn Sie Visual Studio verwenden:

1. Klicken Sie mit der rechten Maustaste auf die Visual Studio-Lösung und wählen Sie Eigenschaften aus.

2. Wählen Sie unter Allgemeine Eigenschaften die Option Startprojekt und dann Mehrere Startprojekte aus.

3. Wählen Sie für beide Projekte Start als Aktion aus.

4. Stellen Sie sicher, dass der Dienst TodoListService zuerst gestartet wird, indem Sie ihn mit dem Pfeil nach oben an die erste Position in der Liste setzen.

Melden Sie sich an, um Ihr TodoListClient-Projekt auszuführen.

1. Drücken Sie F5, um das Projekt zu starten. Die Dienstseite und die Desktopanwendung werden geöffnet.

2. Wählen Sie unter TodoListClient oben rechts die Option Anmelden aus, und melden Sie sich mit den gleichen Anmeldeinformationen an, die Sie zum Registrieren der Anwendung verwendet haben. Sie können sich aber auch als Benutzer im selben Verzeichnis anmelden.

   Wenn Sie sich zum ersten Mal anmelden, werden Sie möglicherweise aufgefordert, der TodoListServiceWeb-API zuzustimmen.

   Mit der Anmeldung wird auch ein Zugriffstoken für den Bereich access_as_user angefordert, damit Sie auf die TodoListService-Web-API zugreifen und die To-Do-Liste bearbeiten können.

Vorautorisieren der Clientanwendung

Sie können Benutzern aus anderen Verzeichnissen den Zugriff auf Ihre Web-API gestatten, indem Sie die Clientanwendung vorab für den Zugriff auf Ihre Web-API autorisieren. Dazu fügen Sie die Anwendungs-ID aus der Client-App zur Liste der vorautorisierten Anwendungen für Ihre Web-API hinzu. Durch das Hinzufügen eines vorautorisierten Clients gestatten Sie Benutzern den Zugriff auf Ihre Web-API, ohne ihre Zustimmung erteilen zu müssen.

1. Öffnen Sie im Portal App-Registrierungen die Eigenschaften Ihrer TodoListService-App.
2. Wählen Sie im Abschnitt Eine API verfügbar machen unter Autorisierte Clientanwendungen die Option Clientanwendung hinzufügen aus.
3. Fügen Sie im Feld Client-ID die Anwendungs-ID der TodoListClient-App ein.
4. Wählen Sie im Abschnitt Autorisierte Bereiche den Bereich api://<Application ID>/access_as_user für die Web-API aus.
5. Wählen Sie Anwendung hinzufügen aus.

Ausführen des Projekts

1. Drücken Sie F5, um das Projekt auszuführen. Ihre TodoListClient-App wird geöffnet.
2. Wählen Sie oben rechts die Option Anmelden aus, und melden Sie sich mit einem persönlichen Microsoft-Konto (z. B. live.com oder hotmail.com) oder einem Geschäfts-, Schul- oder Unikonto an.

Optional: Beschränken des Anmeldezugriffs auf bestimmte Benutzer

Alle persönlichen Konten (z. B. outlook.com oder live.com) oder Geschäfts-, Schul- oder Unikonten von in Microsoft Entra integrierten Organisationen können standardmäßig Token anfordern und auf Ihre Web-API zugreifen.

Verwenden Sie eine der folgenden Optionen, um anzugeben, wer sich bei Ihrer Anwendung anmelden kann:

Option 1: Beschränken des Zugriffs auf eine einzelne Organisation (einzelner Mandant)

Sie können den Anmeldezugriff für Ihre Anwendung auf bestimmte Benutzerkonten beschränken, die in einem einzelnen Microsoft Entra-Mandanten vorhanden sind, einschließlich Gastkonten dieses Mandanten. Dieses Szenario wird häufig für Branchenanwendungen eingesetzt.

1. Öffnen Sie die Datei App_Start\Startup.Auth, und ändern Sie dann den Wert des Metadatenendpunkts, der an den OpenIdConnectSecurityTokenProvider übergeben wird, in https://login.microsoftonline.com/{Tenant ID}/v2.0/.well-known/openid-configuration. Sie können auch den Mandantennamen verwenden, beispielsweise contoso.onmicrosoft.com.
2. Legen Sie in der gleichen Datei die Eigenschaft ValidIssuer für TokenValidationParameters auf https://sts.windows.net/{Tenant ID}/ und das Argument ValidateIssuer auf true fest.

Option 2: Überprüfen von Ausstellern mithilfe einer benutzerdefinierten Methode

Sie können eine benutzerdefinierte Methode implementieren, um Aussteller mit dem Parameter IssuerValidator zu überprüfen. Weitere Informationen zur Verwendung dieses Parameters finden Sie unter TokenValidationParameters-Klasse.

Hilfe und Support

Wenn Sie Hilfe benötigen, ein Problem melden möchten oder sich über Ihre Supportoptionen informieren möchten, finden Sie weitere Informationen unter Hilfe und Support für Entwickler.

Nächste Schritte

Erfahren Sie mehr, indem Sie in der folgenden Tutorial-Serie eine geschützte ASP.NET Core Web-API erstellen: