Aufrufen einer ASP.NET Core-Web-API mit Insomnia

Artikel
05/27/2024

In diesem Artikel erfahren Sie, wie Sie eine geschützte ASP.NET Core-Web-API mit Insomnia aufrufen. Insomnia ist eine Anwendung, mit der Sie HTTP-Anforderungen an eine Web-API senden können, um deren Richtlinien für Autorisierung und Zugriffssteuerung (Authentifizierung) zu testen. In diesem Artikel registrieren Sie eine Web-App und eine Web-API in einem Mandanten. Die Web-App wird verwendet, um ein Zugriffstoken abzurufen, das von der Microsoft Identity Platform generiert wird. Als Nächstes verwenden Sie das Token, um mithilfe von Insomnia einen autorisierten Aufruf der Web-API zu tätigen.

In diesem Artikel erfahren Sie, wie Sie eine geschützte ASP.NET Core-Web-API mit Insomnia aufrufen. Insomnia ist eine Anwendung, mit der Sie HTTP-Anforderungen an eine Web-API senden können, um deren Richtlinien für Autorisierung und Zugriffssteuerung (Authentifizierung) zu testen. Nach dem Tutorial: Implementieren eines geschützten Endpunkts in Ihrer API, in dem Sie eine geschützte API erstellt haben, müssen Sie eine Web-App bei der Microsoft Identity Platform registrieren, um ein Zugriffstoken zu generieren. Als Nächstes verwenden Sie das Token, um mithilfe von Insomnia einen autorisierten Aufruf der API zu tätigen.

Voraussetzungen

Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
Dieses Azure-Konto muss über die Berechtigung zum Verwalten von Anwendungen verfügen. Zu den folgenden Microsoft Entra-Rollen gehören die erforderlichen Berechtigungen:
- Anwendungsadministrator
- Anwendungsentwickler
- Cloudanwendungsadministrator
Laden Sie Insomnia herunter, und installieren Sie Insomnia. Sie verwenden Insomnia, um ein Zugriffstoken für Ihre API-Anforderungen zu erhalten.
Mindestanforderung: .NET 8.0 SDK

Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
Dieses Azure-Konto muss über die Berechtigung zum Verwalten von Anwendungen verfügen. Zu den folgenden Microsoft Entra-Rollen gehören die erforderlichen Berechtigungen:
- Anwendungsadministrator
- Anwendungsentwickler
- Cloudanwendungsadministrator
Abschluss der Tutorialreihe:
Laden Sie Insomnia herunter, und installieren Sie Insomnia.

Eine Anwendung registrieren

Die Microsoft Identity Platform erfordert, dass Ihre Anwendung registriert wird, bevor Identitäts- und Zugriffsverwaltungsdienste bereitgestellt werden können. Mit der Anwendungsregistrierung können Sie Name und Typ der Anwendung sowie die Zielgruppe für die Anmeldung angeben. Die Anmeldegruppe gibt an, welche Arten von Benutzerkonten sich bei einer bestimmten Anwendung anmelden dürfen.

Registrieren der Web-API

Tipp

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

Führen Sie die folgenden Schritte aus, um die Web-API-Registrierung zu erstellen:

Melden Sie sich beim Microsoft Entra Admin Center mindestens mit der Rolle Anwendungsentwickler an.
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.
Browsen Sie zu Identität>Anwendungen>App-Registrierungen.
Wählen Sie Neue Registrierung aus.
Geben Sie einen Namen für die Anwendung ein, z. B. NewWebAPI1.
Wählen Sie für Unterstützte Kontotypen die Option Nur Konten in diesem Organisationsverzeichnis aus. Wenn Sie Informationen zu den verschiedenen Kontotypen wünschen, wählen Sie Entscheidungshilfe aus.
Wählen Sie Registrieren.
Sie können den Bereich Übersicht der Anwendung sehen, wenn die Registrierung abgeschlossen ist. Notieren Sie sich die Verzeichnis-ID (Mandant) und die Anwendungs-ID (Client), die in späteren Schritten verwendet werden sollen.

Hinweis

Die unterstützten Kontotypen können geändert werden (sieheÄndern der von einer Anwendung unterstützten Konten).

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 gültig ist.

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. {clientId} ist der Wert, den Sie auf der Seite Übersicht aufgezeichnet haben. Geben Sie anschließend die folgenden Informationen ein:
1. Geben Sie access_as_user als Forecast.Read ein.
2. Stellen Sie sicher, dass unter Zum Einwilligen berechtigte Personen die Option Administratoren und Benutzer ausgewählt ist.
3. Geben Sie Read forecast data im Feld Anzeigename der Administratorzustimmung ein.
4. Geben Sie Allows the application to read weather forecast data im Feld Beschreibung der Administratorzustimmung ein.
5. Geben Sie Read forecast data im Feld Anzeigename der Benutzereinwilligung ein.
6. Geben Sie Allows the application to read weather forecast data im Feld Beschreibung der Benutzereinwilligung ein.
7. Stellen Sie sicher, dass Status auf Aktiviert eingestellt ist.
Wählen Sie Bereich hinzufügen aus. Wenn der Bereich ordnungsgemäß eingegeben wurde, wird er unter Eine API verfügbar machen angezeigt.

Registrieren der Web-App

Es reicht nicht aus, über eine Web-API zu verfügen, die Web-App muss auch ein Zugriffstoken für den Zugriff auf die Web-API abrufen.

Führen Sie die folgenden Schritte aus, um die Web-App-Registrierung zu erstellen:

Klicken Sie auf Startseite, um zur Startseite zurückzukehren. Navigieren Sie zu Identität>Anwendungen>App-Registrierungen.
Wählen Sie Neue Registrierung aus.
Geben Sie einen Namen für die Anwendung ein, z. B. web-app-calls-web-api.
Wählen Sie für Unterstützte Kontotypen die Option Nur Konten in diesem Organisationsverzeichnis aus. Wenn Sie Informationen zu den verschiedenen Kontotypen benötigen, wählen Sie Entscheidungshilfe aus.
Wählen Sie unter Umleitungs-URI (optional) die Option Web aus, und geben Sie http://localhost in das URL-Textfeld ein.
Wählen Sie Registrieren aus.

Melden Sie sich beim Microsoft Entra Admin Center mindestens mit der Rolle Anwendungsentwickler an.
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.
Browsen Sie zu Identität>Anwendungen>App-Registrierungen.
Wählen Sie Neue Registrierung aus.
Geben Sie einen Namen für die Anwendung ein, z. B. web-app-calls-web-api.
Wählen Sie für Unterstützte Kontotypen die Option Nur Konten in diesem Organisationsverzeichnis aus. Wenn Sie Informationen zu den verschiedenen Kontotypen benötigen, wählen Sie Entscheidungshilfe aus.
Wählen Sie unter Umleitungs-URI (optional) die Option Web aus, und geben Sie http://localhost in das URL-Textfeld ein.
Wählen Sie Registrieren aus.

Sie können den Bereich Übersicht der Anwendung sehen, wenn die Registrierung abgeschlossen ist. Notieren Sie sich die Verzeichnis-ID (Mandant) und die Anwendungs-ID (Client), die in späteren Schritten verwendet werden sollen.

Geheimen Clientschlüssel hinzufügen

Ein geheimer Clientschlüssel (manchmal auch als Anwendungskennwort bezeichnet) ist ein Zeichenfolgenwert, den Ihre App für die Identifizierung verwenden kann. Die Web-App verwendet den geheimen Clientschlüssel beim Anfordern von Token als Identitätsnachweis.

Führen Sie die folgenden Schritte aus, um einen geheimen Clientschlüssel zu konfigurieren:

Wählen Sie im Bereich Übersicht unter Verwalten die Option Zertifikate & Geheimnisse>Geheime Clientschlüssel>Neuer geheimer Clientschlüssel aus.
Fügen Sie eine Beschreibung für Ihren geheimen Clientschlüssel hinzu, z. B. Mein geheimer Clientschlüssel.
Wählen Sie für das Geheimnis eine Ablauffrist aus, oder geben Sie eine benutzerdefinierte Lebensdauer an.
- Die Lebensdauer eines geheimen Clientschlüssels ist auf maximal zwei Jahre (24 Monate) begrenzt. Das bedeutet, dass keine benutzerdefinierte Lebensdauer angegeben werden kann, die über die 24 Monate hinausgeht.
- Microsoft empfiehlt, den Wert für die Ablauffrist auf maximal 12 Monate festzulegen.
Wählen Sie Hinzufügen.
Notieren Sie sich unbedingt den Wert des geheimen Clientschlüssels. Dieser Geheimniswert kann nach Verlassen dieser Seite nicht erneut angezeigt werden.

Weitere Informationen zum sicheren Speichern Ihres geheimen Clientschlüssels finden Sie unter Bewährte Methoden für die Verwaltung geheimer Schlüssel im Key Vault.

Hinzufügen von Berechtigungen für den Zugriff auf Ihre Web-API

Wenn Sie die Bereiche einer Web-API angeben, kann die Web-App ein Zugriffstoken mit diesen Bereichen von der Microsoft Identity Platform abrufen. Innerhalb des Codes kann die Web-API dann berechtigungsbasierten Zugriff auf die zugehörigen Ressourcen basierend auf den im Zugriffstoken enthaltenen Bereichen bereitstellen.

Führen Sie die folgenden Schritte aus, um die Berechtigungen des Clients für die Web-API zu konfigurieren:

Wählen Sie im Bereich Übersicht Ihrer Anwendung unter Verwalten die Option API-Berechtigungen>Berechtigung hinzufügen>APIs meiner Organisation aus.
Wählen Sie NewWebAPI1 oder die API aus, der Sie Berechtigungen hinzufügen möchten.
Aktivieren Sie unter Berechtigungen auswählen das Kontrollkästchen neben Forecast.Read. Möglicherweise müssen Sie die Liste Berechtigung erweitern. Dadurch werden die Berechtigungen ausgewählt, die die Client-App im Namen des angemeldeten Benutzers besitzen soll.
Wählen Sie Berechtigungen hinzufügen aus, um den Vorgang abzuschließen.

Nachdem Sie Ihrer API diese Berechtigungen hinzugefügt haben, sollten die ausgewählten Berechtigungen unter Konfigurierte Berechtigungen angezeigt werden.

Möglicherweise sehen Sie auch die Berechtigung User.Read für die Microsoft Graph-API. Diese Berechtigung wird automatisch hinzugefügt, wenn Sie eine App registrieren.

Testen der Web-API

Führen Sie die folgenden Schritte aus, um sicherzustellen, dass Ihre API betriebsbereit und bereit für die Verarbeitung von Anforderungen ist:

Klonen Sie das Repository ms-identity-docs-code-dotnet.

git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git

Navigieren Sie zu ms-identity-docs-code-dotnet/web-api und öffnen Sie appsettings.json, ersetzen Sie {APPLICATION_CLIENT_ID} und {DIRECTORY_TENANT_ID} durch die folgenden Werte:
- {APPLICATION_CLIENT_ID} ist die Anwendungs-ID (Client) der Web-API, die im Bereich Übersicht der App angezeigt wird.
- {DIRECTORY_TENANT_ID} ist die Verzeichnis-ID (Mandant) der Web-API, die im Bereich Übersicht der App angezeigt wird.
Führen Sie den folgenden Befehl aus, um die App zu starten:
```
dotnet run
```
Die Ausgabe sieht in etwa wie folgt aus. Notieren Sie sich die Portnummer in der https://localhost:{port}-URL.
```
...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...
```

Testen der Web-API

Führen Sie die folgenden Schritte aus, um sicherzustellen, dass Ihre API betriebsbereit und bereit für die Verarbeitung von Anforderungen ist:

Navigieren Sie zur Web-API, die im Tutorial: Erstellen eines ASP.NET Core-Projekts und Konfigurieren der API erstellt wurde, z. B. NewWebAPILocal, und öffnen Sie den Ordner.
Öffnen Sie ein neues Terminal-Fenster, und navigieren Sie zu dem Ordner, in dem sich das WEB-API-Projekt befindet.
- .NET 6.0
- .NET 7.0
1. Führen Sie den folgenden Befehl aus, um die App zu starten:
```
dotnet run
```
1. Öffnen Sie ein neues Terminal, und führen Sie den folgenden Befehl aus, um die App im Profil https zu starten:
```
dotnet run -launch-profile https`
```
Die Ausgabe sieht in etwa wie folgt aus. Notieren Sie sich die Portnummer in der https://localhost:{port}-URL.
```
...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...
```

Konfigurieren einer autorisierten Anforderung an die Web-API in Insomnia

Führen Sie die folgenden Schritte aus, um ein Zugriffstoken für Ihre API-Anforderungen abzurufen:

Starten Sie die Anwendung Insomnia.
Wählen Sie Neue HTTP-Anforderung aus, oder verwenden Sie STRG+ N, um eine neue HTTP-Anforderung zu erstellen.
Wählen Sie in der Neuen modalen Anforderung eine GET-Methode aus der Dropdownliste aus.
Geben Sie für die Anforderungs-URL die URL des Endpunkts ein, der von der Web-API verfügbar gemacht wird: https://localhost:{port}/weatherforecast.
Wählen Sie im Dropdownmenü Authentifizierung die Option OAuth 2.0 aus. Dadurch wird OAuth 2.0-Formular angezeigt.

Geben Sie die folgenden Werte in das OAuth 2.0-Formular ein:

Einstellung	Wert
GEWÄHRUNGSTYP	Wählen Sie Autorisierungscode aus.
AUTORISIERUNGS-URL	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize` Ersetzen Sie `{tenantId}` durch Verzeichnis-ID (Mandant).
ZUGRIFFSTOKEN-URL	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token` Ersetzen Sie `{tenantId}` durch Verzeichnis-ID (Mandant).
CLIENT-ID	Der Wert Anwendungs-ID (Client) Ihrer Web-App-Registrierung
GEHEIMER CLIENTSCHLÜSSEL	Der Wert des geheimen Clientschlüssels Ihrer Web-App-Registrierung
UMLEITUNGS-URL	Geben Sie `http://localhost` ein, wodurch die UMLEITUNGS-URL auf den bei Microsoft Entra ID registrierten Umleitungs-URI festgelegt wird.
Erweiterten Optionen>BEREICH	`api://{application_client_id}/Forecast.Read` Navigieren Sie zu Ihrer Web-App-Registrierung. Wählen Sie unter Verwalten die Option API-Berechtigungen und dann Forecast.Read aus. Kopieren Sie den Wert in das Textfeld, das den Wert Bereich enthält.

Abrufen eines Zugriffstokens und Senden einer Anforderung an die Web-API

Nachdem diese Werte eingegeben wurden, wählen Sie Token abrufen am Ende des Formulars aus. Dadurch wird ein Insomnia-Browserfenster gestartet, in dem Sie sich mit Ihren Benutzeranmeldeinformationen authentifizieren. Achten Sie darauf, Popups aus der Insomnia-Anwendung im Browser zuzulassen.
Wählen Sie nach der Authentifizierung Senden aus, um die Anforderung an den geschützten Web-API-Endpunkt zu senden.

Wenn ein gültiges Zugriffstoken in der Anforderung enthalten ist, wird „200 OK“ als erwartete Antwort ähnlich wie in der folgenden Ausgabe ausgegeben:

[
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": -16,
    "summary": "Scorching",
    "temperatureF": 4
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 1,
    "summary": "Sweltering",
    "temperatureF": 33
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 26,
    "summary": "Freezing",
    "temperatureF": 78
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 54,
    "summary": "Mild",
    "temperatureF": 129
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 11,
    "summary": "Bracing",
    "temperatureF": 51
  }
]

Weitere Informationen zum OAuth 2.0-Autorisierungscodeflow und den Anwendungstypen finden Sie unter:

Freigeben über

Aufrufen einer ASP.NET Core-Web-API mit Insomnia

Voraussetzungen