Freigeben über

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

  • Artikel

In der folgenden Schnellstartanleitung wird ein Codebeispiel verwendet, 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 WPF-App (Windows Presentation Foundation), um zu veranschaulichen, wie Sie ein Zugriffstoken für den Zugriff auf eine Web-API anfordern.

Voraussetzungen

Klonen oder Herunterladen des Beispiels

Das Codebeispiel kann auf zwei Arten abgerufen werden:

  • Clonen von der Shell oder der Befehlszeile:

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

  • Herunterladen als ZIP-Datei.

Tipp

Es wird empfohlen, das Archiv in ein Verzeichnis in der Nähe des Stammverzeichnisses Ihres Laufwerks zu extrahieren, um Fehler zu vermeiden, die durch Beschränkungen der Pfadlänge unter Windows verursacht werden.

Registrieren der Web-API (TodoListService)

Tipp

Die Schritte in diesem Artikel können je nach dem Portal, mit dem Sie beginnen, geringfügig variieren.

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

  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens als Cloudanwendungsadministrator an.

  2. Wenn Sie Zugriff auf mehrere Mandanten haben, verwenden Sie das Symbol für Einstellungen im oberen Menü, um zum Mandanten zu wechseln, in dem Sie die Anwendung über das Menü Verzeichnisse + Abonnements registrieren möchten.

  3. Wechseln Sie zu Identität>Anwendungen>App-Registrierungen, und 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 Lösung in Visual Studio und öffnen Sie dann im Stammverzeichnis des TodoListService-Projekts die Datei appsettings.json.

  2. Ersetzen Sie den Wert von Enter_the_Application_Id_here durch den Wert der Client-ID (Anwendungs-ID) der Anwendung, die Sie im Portal App-Registrierungen für die Eigenschaften ClientID und Audience 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}.

Hinweis

Stellen Sie sicher, das für die Anwendungs-ID das folgende Format verwendet wird: api://{TodoListService-Application-ID}/access_as_user (hierbei ist {TodoListService-Application-ID} die GUID, die für die Anwendungs-ID der TodoListService-App steht).

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. Melden Sie sich beim Microsoft Entra Admin Center mindestens als Cloudanwendungsadministrator an.

  2. Wechseln Sie zu Identität>Anwendungen>App-Registrierungen, und wählen Sie Neue Registrierung aus.

  3. Wählen Sie Neue Registrierung aus.

  4. 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.

  5. 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.

  6. 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. Für Visual Studio-Benutzer:

  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.

Um anzugeben, wer sich bei Ihrer Anwendung anmelden kann, ändern Sie die Eigenschaft TenantId in der Datei appsettings.json.

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:

Geschützte Web-API: Tutorial