Schnellstart: Aufrufen einer Web-API, die durch die Microsoft Identity Platform geschützt ist

Gilt für: Mitarbeitermandanten Externe Mandanten (weitere Informationen)

In dieser Schnellstartanleitung verwenden Sie eine Beispielweb-App, um Ihnen zu zeigen, wie Sie eine ASP.NET Web-API mithilfe der Microsoft Identity Platform schützen. Im Beispiel wird die Microsoft Authentication Library (MSAL) verwendet, um die Authentifizierung und Autorisierung zu verarbeiten.

Voraussetzungen

• Ein Azure-Konto mit einem aktiven Abonnement. Erstellen Sie kostenlos ein Konto.
• Registrieren Sie eine neue App im Microsoft Entra Admin Center , und notieren Sie ihre Bezeichner auf der Seite "App-Übersicht ". Weitere Informationen finden Sie unter Registrieren einer Anwendung.
  • Name: NewWebAPI1
  • Unterstützte Kontotypen: Nur Konten in diesem Organisationsverzeichnis (einzelner Mandant)

ASP.NET

• Visual Studio 2022. Laden Sie Visual Studio kostenlos herunter.

ASP.NET Core

• Visual Studio Code

Verfügbarmachen der API

Nachdem die API registriert wurde, können Sie ihre Berechtigung konfigurieren, indem Sie die Bereiche definieren, die die API für Clientanwendungen verfügbar macht. Clientanwendungen fordern die Berechtigung zum Ausführen von Vorgängen an, indem sie ein Zugriffstoken zusammen mit der Anforderung an die geschützte Web-API weiterleiten. Die Web-API führt anschließend den angeforderten Vorgang nur dann aus, wenn das empfangene Zugriffstoken die erforderlichen Bereiche enthält.

ASP.NET

1. Wählen Sie unter "Verwalten" die Option "API-Bereich>hinzufügen" aus. Akzeptieren Sie den vorgeschlagenen Anwendungs-ID-URI (api://{clientId}), indem Sie "Speichern" auswählen und den Vorgang fortsetzen, und geben Sie dann die folgenden Informationen ein:

   1. Für Bereichsname geben Sie access_as_user ein.
   2. Stellen Sie für Wer zustimmen kann sicher, dass die Option Administratoren und Benutzer ausgewählt ist.
   3. Geben Sie im Feld "Administratorzustimmung-Anzeigename" die Zeichenfolge ein.
   4. Geben Sie im Feld Accesses the TodoListService web API as a user ein.
   5. Geben Sie im Anzeigenamenfeld der BenutzereinwilligungAccess TodoListService as a user ein.
   6. Geben Sie im Feld Accesses the TodoListService web API as a user ein.
   7. Für Status belassen Sie Aktiviert.

2. Wählen Sie "Bereich hinzufügen" aus.

ASP.NET Core

Hinzufügen delegierter Berechtigungen (Bereiche)

Eine API muss mindestens einen Bereich veröffentlichen, der auch als delegierte Berechtigung bezeichnet wird, damit die Client-Apps ein Zugriffstoken für einen Benutzer erfolgreich abrufen können. Führen Sie diese Schritte aus, um einen Bereich zu veröffentlichen:

1. Wählen Sie auf der Seite " App-Registrierungen " die API-Anwendung aus, die Sie erstellt haben (ciam-ToDoList-api), um die zugehörige Übersichtsseite zu öffnen.

2. Wählen Sie unter "Verwalten" die Option "API verfügbar machen" aus.

3. Wählen Sie oben auf der Seite neben dem Anwendungs-ID-URI den Link "Hinzufügen" aus, um einen URI zu generieren, der für diese App eindeutig ist.

4. Akzeptieren Sie den vorgeschlagenen Anwendungs-ID-URI, wie z. api://{clientId}, und wählen Sie Speichern aus. Wenn Ihre Webanwendung ein Zugriffstoken für die Web-API anfordert, fügt sie diesen URI als Präfix für jeden Bereich hinzu, den Sie für die API definieren.

5. Wählen Sie unter den von dieser API definierten Bereichen"Bereich hinzufügen" aus.

6. Geben Sie die folgenden Werte ein, die einen Lesezugriff auf die API definieren, und wählen Sie dann "Bereich hinzufügen" aus, um Ihre Änderungen zu speichern:

   Eigentum	Wert
   Bereichsname	ToDoListe.Lesen
   Wer kann zustimmen?	Nur Administratoren
   Anzeigename der Administrationseinwilligung	Lesen der ToDo-Liste von Benutzern mithilfe der "TodoListApi"
   Beschreibung der Zustimmung des Administrators	Erlauben Sie der App, die ToDo-Liste des Benutzers mithilfe der "TodoListApi" zu lesen.
   Staat	Aktiviert

7. Wählen Sie erneut einen Bereich hinzufügen aus, und geben Sie die folgenden Werte ein, die einen Lese- und Schreibzugriffsbereich für die API definieren. Wählen Sie "Bereich hinzufügen" aus, um Ihre Änderungen zu speichern:

   Eigentum	Wert
   Bereichsname	ToDoList.ReadWrite
   Wer kann zustimmen?	Nur Administratoren
   Anzeigename der Administrationseinwilligung	Benutzer-ToDo-Liste lesen und schreiben mit der "ToDoListApi"
   Beschreibung der Zustimmung des Administrators	Zulassen, dass die App die ToDo-Liste des Benutzers mithilfe der "ToDoListApi" lesen und schreiben kann
   Staat	Aktiviert

Erfahren Sie mehr über das Prinzip der geringsten Berechtigungen beim Veröffentlichen von Berechtigungen für eine Web-API.

Hinzufügen von Anwendungsberechtigungen (App-Rollen)

Eine API muss mindestens eine App-Rolle oder Anwendungsberechtigung veröffentlichen, damit die Client-Apps ein Zugriffstoken für sich selbst erhalten können. Anwendungsberechtigungen sind der Typ von Berechtigungen, die APIs veröffentlichen sollten, wenn sie Clientanwendungen eine erfolgreiche Authentifizierung als sie selbst ermöglichen wollen und keine Benutzerinnen bzw. Benutzer anmelden müssen. Befolgen Sie die folgenden Schritte, um eine Anwendungsberechtigung zu veröffentlichen:

1. Wählen Sie auf der Seite " App-Registrierungen " die Anwendung aus, die Sie erstellt haben (z. B. ciam-ToDoList-api), um die Zugehörige Übersichtsseite zu öffnen.

2. Wählen Sie unter "Verwalten"Die App-Rollen aus.

3. Wählen Sie " App-Rolle erstellen" aus, und geben Sie dann die folgenden Werte ein, und wählen Sie dann "Übernehmen" aus, um Ihre Änderungen zu speichern:

   Eigentum	Wert
   Anzeigename	ToDoListe.Lesen.Alle
   Zulässige Mitgliedstypen	Anträge
   Wert	ToDoListe.Lesen.Alle
   BESCHREIBUNG	Zulassen, dass die App die ToDo-Liste jedes Benutzers mithilfe der "TodoListApi" lesen kann
   Möchten Sie diese App-Rolle aktivieren?	Aktiviert lassen

4. Wählen Sie erneut " App-Rolle erstellen " aus, und geben Sie dann die folgenden Werte für die zweite App-Rolle ein, und wählen Sie dann "Übernehmen" aus, um Ihre Änderungen zu speichern:

   Eigentum	Wert
   Anzeigename	ToDoList.ReadWrite.All
   Zulässige Mitgliedstypen	Anträge
   Wert	ToDoList.ReadWrite.All
   BESCHREIBUNG	Zulassen, dass die App die ToDo-Liste aller Benutzer mithilfe der "ToDoListApi" lesen und schreiben kann
   Möchten Sie diese App-Rolle aktivieren?	Aktiviert lassen

Klonen oder Herunterladen der Beispielanwendung

Um die Beispielanwendung zu erhalten, können Sie sie entweder von GitHub klonen oder als .zip Datei herunterladen.

ASP.NET

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

• Laden Sie sie als ZIP-Datei herunter.

Tipp

Um Fehler zu vermeiden, die durch Pfadlängenbeschränkungen in Windows verursacht werden, empfehlen wir, das Archiv zu extrahieren oder das Repository in ein Verzeichnis in der Nähe des Stamms Ihres Laufwerks zu klonen.

ASP.NET Core

git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.git

• Laden Sie die datei .zip herunter. Extrahieren Sie ihn in einen Dateipfad, in dem die Länge des Namens weniger als 260 Zeichen beträgt.

Konfigurieren der Beispielanwendung

Konfigurieren Sie das Codebeispiel so, dass es der registrierten Web-API entspricht.

ASP.NET

1. Öffnen Sie die Projektmappe in Visual Studio und öffnen Sie anschließend die Datei appsettings.json im Stammverzeichnis des Projekts TodoListService.

2. Ersetzen Sie den Wert des Enter_the_Application_Id_here durch den Client-ID -Wert (Anwendungs-ID) aus der Anwendung, die Sie im App-Registrierungsportal registriert haben, sowohl in den ClientID Eigenschaften als auch in den Audience Eigenschaften.

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

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

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

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 Ihre TodoListClient-App in App-Registrierungen im Microsoft Entra Admin Center, und konfigurieren Sie dann den Code im TodoListClient-Projekt. Wenn der Client und der Server als dieselbe Anwendung betrachtet werden, können Sie die in Schritt 2 registrierte Anwendung wiederverwenden. 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 mindestens als Cloudanwendungsadministrator beim Microsoft Entra Admin Center an.

2. Navigieren Sie zu Entra ID>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 Benutzern der App angezeigt wird (z. B. NativeClient-DotNet-TodoListClient).
   2. Wählen Sie für unterstützte Kontotypen"Konten" in einem beliebigen Organisationsverzeichnis aus.
   3. Wählen Sie "Registrieren" aus, um die Anwendung zu erstellen.

   Hinweis

   Im TodoListClient-Projekt app.config Datei wird der Standardwert ida:Tenant auf common. Mögliche Werte sind:

   • common: Sie können sich mit einem Geschäfts-, Schul- oder Unikonto oder einem persönlichen Microsoft-Konto anmelden (da Sie "Konten" in einem beliebigen Organisationsverzeichnis in einem vorherigen Schritt ausgewählt haben).
   • 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 "App-Übersicht " 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 für Mobile- und DesktopanwendungenMobile- und Desktopanwendungen aus.
   3. Aktivieren Sie für Umleitungs-URIs das https://login.microsoftonline.com/common/oauth2/nativeclient Kontrollkästchen.
   4. Wählen Sie "Konfigurieren" aus.

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 " aus.
   2. Wählen Sie die Registerkarte "Meine APIs " aus.
   3. Wählen Sie in der Liste der APIs "AppModelv2-NativeClient-DotNet-TodoListService-API " oder den Namen aus, den Sie für die Web-API eingegeben haben.
   4. Aktivieren Sie das Kontrollkästchen der Berechtigung access_as_user, wenn es noch nicht aktiviert ist. Verwenden Sie bei Bedarf das Suchfeld.
   5. Wählen Sie die Schaltfläche "Berechtigungen hinzufügen" aus.

Konfigurieren Sie Ihr Projekt

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

1. Kopieren Sie im App-Registrierungsportal auf der Seite "Übersicht " den Wert der Anwendungs-ID (Client-ID).

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

ASP.NET Core

1. Öffnen Sie in Ihrer IDE den Projektordner "ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI", das das Beispiel enthält.

2. Öffnen Sie die Datei appsettings.json, die den folgenden Codeschnipsel enthält:

   {
     "AzureAd": {
       "Instance": "Enter_the_Authority_URL_Here", //For external tenants, use instance in the form of "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"
       "TenantId": "Enter_the_Tenant_Id_Here",
       "ClientId": "Enter_the_Application_Id_Here",
       "Scopes": {
         "Read": ["ToDoList.Read", "ToDoList.ReadWrite"],
         "Write": ["ToDoList.ReadWrite"]
       },
       "AppPermissions": {
         "Read": ["ToDoList.Read.All", "ToDoList.ReadWrite.All"],
         "Write": ["ToDoList.ReadWrite.All"]
       }
     },
     "Logging": {...},
     "AllowedHosts": "*"
   }
   

   Suchen Sie die folgenden Werte:

   • ClientId – Der Bezeichner der Anwendung, auch als Client bezeichnet. Ersetzen Sie den value Text in Anführungszeichen durch die Anwendungs-ID (Client-ID), die zuvor auf der Seite "Übersicht" der registrierten Anwendung aufgezeichnet wurde.
   • TenantId – Der Bezeichner des Mandanten, in dem die Anwendung registriert ist. Ersetzen Sie den value Text in Anführungszeichen mit dem Wert der Verzeichnis-ID (Mandant), der zuvor von der Übersicht-Seite der registrierten Anwendung aufgezeichnet wurde.
   • Instance – Es gibt das Verzeichnis an, aus dem die Microsoft-Authentifizierungsbibliothek (MSAL) Token anfordern kann. Ersetzen Sie Enter_the_Authority_URL_Here je nach Szenario durch einen der folgenden Werte:
     • Verwenden Sie https://login.microsoftonline.com/ als Instanz für Mitarbeitendenmandanten.
     • Fügen Sie für externe Mandanten eine Autoritäts-URL in Form von https://<Enter_the_Tenant_Subdomain_Here>.ciamlogin.com/ hinzu.

Ausführen der Beispielanwendung

ASP.NET

Starten Sie beide Projekte. Für Visual Studio-Benutzer:

1. Klicken Sie mit der rechten Maustaste auf die Visual Studio-Projektmappe, und wählen Sie "Eigenschaften" aus.

2. Wählen Sie in den allgemeinen Eigenschaften"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 im TodoListClient oben rechts "Anmelden" aus, und melden Sie sich dann mit denselben Anmeldeinformationen an, die Sie zum Registrieren Ihrer Anwendung verwendet haben, oder melden Sie sich im selben Verzeichnis als Benutzer an.

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

   Damit Sie auf die TodoListService-Web-API zugreifen und die Aufgabenliste bearbeiten können, fordert die Anmeldung auch ein Zugriffstoken an den access_as_user Bereich an.

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 vordefinierten Anwendungen für Ihre Web-API hinzu. Indem Sie einen vorautorisierten Client hinzufügen, können Benutzer ohne Zustimmung auf Ihre Web-API zugreifen.

1. Öffnen Sie im Portal für App-Registrierungen die Eigenschaften Ihrer TodoListService-App.
2. Wählen Sie im Abschnitt "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 für die api://<Application ID>/access_as_user Web-API aus.
5. Wählen Sie "Anwendung hinzufügen" aus.

Führen Sie Ihr Projekt aus

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

Optional: Beschränken des Anmeldezugriffs auf bestimmte Benutzer

Standardmäßig können alle persönlichen Konten, z. B. outlook.com - oder live.com-Konten , Geschäfts-, Schul- oder Unikonten von Organisationen, die mit Microsoft Entra-ID integriert sind, Token anfordern und auf Ihre Web-API zugreifen.

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

ASP.NET Core

1. Führen Sie den folgenden Befehl aus dem Stammverzeichnis Ihres Web-API-Projektverzeichnisses aus, um die App zu starten:

   dotnet run
   

2. Wenn alles ordnungsgemäß funktioniert hat, zeigt Ihr Terminal eine Ausgabe ähnlich wie die folgenden an:

    Building...
        info: Microsoft.Hosting.Lifetime[14]
              Now listening on: https://localhost:{port}
        info: Microsoft.Hosting.Lifetime[0]
              Application started. Press Ctrl+C to shut down.
        info: Microsoft.Hosting.Lifetime[0]
              Hosting environment: Development
   ...
   

   Notieren Sie sich die Portnummer in der https://localhost:{port}-URL.

3. Um zu überprüfen, ob der Endpunkt geschützt ist, aktualisieren Sie die Basis-URL im folgenden cURL-Befehl so, dass sie mit derjenigen übereinstimmt, die Sie im vorherigen Schritt erhalten haben, und führen Sie den Befehl dann aus:

   curl -k -X GET https://localhost:<your-api-port>/api/todolist -w "%{http_code}\n"
   

   Die erwartete Antwort lautet 401 Nicht autorisiert.

Nächste Schritte

Erfahren Sie, wie Sie eine ASP.NET Core-Web-API mit der Microsoft Identity Platform schützen.

Lernprogramm: Erstellen und Sichern einer ASP.NET Core-Web-API mit der Microsoft Identity Platform