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

  • Artikel

In diesem Artikel erfahren Sie, wie Sie eine geschützte ASP.NET Core-Web-API mit Client-URL (cURL) aufrufen. cURL ist ein Befehlszeilentool, mit dem Entwickler Daten an und von einem Server übertragen. 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 cURL 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 Client-URL (cURL) aufrufen. cURL ist ein Befehlszeilentool, mit dem Entwickler Daten an und von einem Server übertragen. 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 cURL 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 und installieren Sie cURL auf Ihrer Arbeitsstation.
  • Mindestanforderung: .NET 6.0 SDK.

Registrieren einer Anwendung bei Microsoft Identity Platform

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 den Namen und den Typ der Anwendung und die Anmeldegruppe 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:

  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens mit der Rolle Anwendungsentwickler 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. Browsen Sie zu Identität>Anwendungen>App-Registrierungen.

  4. Wählen Sie Neue Registrierung aus.

  5. Geben Sie einen Namen für die Anwendung ein, z. B. NewWebAPI1.

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

  7. Wählen Sie Registrieren.

    Screenshot: Eingeben eines Namens und Auswählen des Kontotyps

  8. Der Bereich Übersicht der Anwendung wird angezeigt, wenn die Registrierung abgeschlossen ist. Notieren Sie sich die Verzeichnis-ID (Mandant) und die Anwendungs-ID (Client), die im Quellcode Ihrer Anwendung verwendet werden sollen.

    Screenshot: Bezeichnerwerte auf der Übersichtsseite

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.

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

  2. Wählen Sie Bereich hinzufügen aus. Wenn der Bereich ordnungsgemäß eingegeben wurde, wird er im Bereich Eine API verfügbar machen aufgeführt.

    Screenshot: Feldwerte beim Hinzufügen des Bereichs zu einer API

Registrieren der Web-App

Eine Web-API ist jedoch nicht ausreichend, da eine Web-App außerdem ein Zugriffstoken für den Zugriff auf die von Ihnen erstellte Web-API benötigt.

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

  1. Klicken Sie auf Startseite, um zur Startseite zurückzukehren. Navigieren Sie zu Identität>Anwendungen>App-Registrierungen.
  2. Wählen Sie Neue Registrierung aus.
  3. Geben Sie einen Namen für die Anwendung ein, z. B. web-app-calls-web-api.
  4. 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.
  5. Wählen Sie unter Umleitungs-URI (optional) die Option Web aus, und geben Sie http://localhost in das URL-Textfeld ein.
  6. Wählen Sie Registrieren aus.
  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens mit der Rolle Anwendungsentwickler 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. Browsen Sie zu Identität>Anwendungen>App-Registrierungen.
  4. Wählen Sie Neue Registrierung aus.
  5. Geben Sie einen Namen für die Anwendung ein, z. B. web-app-calls-web-api.
  6. 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.
  7. Wählen Sie unter Umleitungs-URI (optional) die Option Web aus, und geben Sie http://localhost in das URL-Textfeld ein.
  8. Wählen Sie Registrieren aus.

Wenn die Registrierung abgeschlossen ist, wird die App-Registrierung im Bereich Übersicht angezeigt. 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:

  1. Wählen Sie im Bereich Übersicht unter Verwalten die Option Zertifikate & Geheimnisse>Geheime Clientschlüssel>Neuer geheimer Clientschlüssel aus.

  2. Fügen Sie eine Beschreibung für Ihren geheimen Clientschlüssel hinzu, z. B. Mein geheimer Clientschlüssel.

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

  4. Wählen Sie Hinzufügen.

  5. Notieren Sie sich unbedingt den Wert des geheimen Clientschlüssels. Dieser Geheimniswert kann nach Verlassen dieser Seite nicht erneut angezeigt werden.

Hinzufügen von Anwendungsberechtigungen für den Zugriff auf eine Web-API

Wenn Sie die Bereiche einer Web-API in der Registrierung der Web-App 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 Web-App-Berechtigungen für die Web-API zu konfigurieren:

  1. Wählen Sie im Bereich Übersicht Ihrer Web-App (web-app-that-calls-web-api) unter Verwalten die Option API-Berechtigungen>Berechtigung hinzufügen>Meine APIs aus.
  2. Wählen Sie NewWebAPI1 oder die API aus, der Sie Berechtigungen hinzufügen möchten.
  3. 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.
  4. 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

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

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

  2. Navigieren Sie zum Ordner ms-identity-docs-code-dotnet/web-api, öffnen Sie die Datei ./appsettings.json, und ersetzen Sie {APPLICATION_CLIENT_ID} und {DIRECTORY_TENANT_ID} wie folgt:

    • {APPLICATION_CLIENT_ID} ist die Anwendungs-ID (Client), die im Bereich Übersicht der Web-API unter App-Registrierungen angezeigt wird.
    • {DIRECTORY_TENANT_ID} ist die Verzeichnis-ID (Mandant), die im Bereich Übersicht der Web-API unter App-Registrierungen angezeigt wird.

  3. Führen Sie den folgenden Befehl aus, um die App zu starten:

    dotnet run

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

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

  2. Öffnen Sie ein neues Terminal-Fenster, und navigieren Sie zu dem Ordner, in dem sich das WEB-API-Projekt befindet.

  1. Führen Sie den folgenden Befehl aus, um die App zu starten:

    dotnet run

  1. 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}
...

Anfordern eines Autorisierungscodes

Der Autorisierungscodefluss beginnt damit, dass der Client den Benutzer auf den /authorize -Endpunkt leitet. In dieser Anforderung fordert der Client die Berechtigung Forecast.Read vom Benutzer an.

https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize?client_id={web-app-calls-web-api_application_client_id}&response_type=code&redirect_uri=http://localhost&response_mode=query&scope=api://{web_API_application_client_id}/Forecast.Read

  1. Kopieren Sie die URL, ersetzen Sie die folgenden Parameter, und fügen Sie sie in Ihren Browser ein:

    • {tenant_id} ist die Verzeichnis-ID (Mandant) der Web-App.
    • {web-app-calls-web-api_application_client_id} ist die Anwendungs-ID (Client) im Bereich Übersicht der Web-App (web-app-calls-web-api).
    • {web_API_application_client_id} ist die Anwendungs-ID (Client) im Bereich Übersicht der Web-API (NewWebAPI1).

  2. Melden Sie sich als Benutzer bzw. Benutzerin bei dem Microsoft Entra-Mandanten an, in dem die Apps registriert sind. Stimmen Sie allen Zugriffsanforderungen zu, falls erforderlich.

  3. Ihr Browser wird zu http://localhost/ umgeleitet. Gehen Sie zur Navigationsleiste Ihres Browsers, und kopieren Sie den {authorization_code}, um ihn in den folgenden Schritten zu verwenden. Die URL hat die Form des folgenden Schnipsels:

    http://localhost/?code={authorization_code}

Verwenden eines Autorisierungscodes und cURL zum Abrufen eines Zugriffstokens

cURL kann jetzt verwendet werden, um ein Zugriffstoken von der Microsoft Identity Platform anzufordern.

  1. Kopieren Sie den URL-Befehl im folgenden Codeschnipsel. Ersetzen Sie die Werte in Klammern durch die folgenden Parameter für Ihr Terminal. Entfernen Sie unbedingt die Klammern:

    curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token \
-d 'client_id={web-app-calls-web-api_application_client_id}' \
-d 'api://{web_API_application_client_id}/Forecast.Read' \
-d 'code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}' \
-d 'redirect_uri=http://localhost' \
-d 'grant_type=authorization_code' \
-d 'client_secret={client_secret}'
    • {tenant_id} ist die Verzeichnis-ID (Mandant) der Web-App.
    • client_id={web-app-calls-web-api_application_client_id} und session_state={web-app-calls-web-api_application_client_id} ist die Anwendungs-ID (Client) im Bereich Übersicht der Web-App (web-app-calls-web-api).
    • api://{web_API_application_client_id}/Forecast.Read ist die Anwendungs-ID (Client) im Bereich Übersicht der Web-API (NewWebAPI1).
    • code={authorization_code} ist der Autorisierungscode, der unter Anfordern eines Autorisierungscodes bereitgestellt wurde. Dadurch kann das cURL-Tool ein Zugriffstoken anfordern.
    • client_secret={client_secret} ist der Wert des geheimen Clientschlüssels, den Sie sich unter Hinzufügen eines geheimen Clientschlüssels notiert haben.

  2. Führen Sie den cURL-Befehl aus.Wenn Sie ihn richtig eingegeben haben, sollten Sie eine JSON-Antwort ähnlich der folgenden Ausgabe erhalten:

    {
   "token_type": "Bearer",
   "scope": "api://{web_API_application_client_id}/Forecast.Read",
   "expires_in": 3600,
   "ext_expires_in": 3600,
   "access_token": "{access_token}"
}

Aufrufen der Web-API mit Zugriffstoken

Durch Ausführen des vorherigen cURL-Befehls hat die Microsoft Identity Platform ein Zugriffstoken bereitgestellt. Das erworbene Token kann jetzt als Bearer in einer HTTP-Anforderung zum Aufrufen der Web-API verwendet werden.

  1. Um die Web-API aufzurufen, kopieren Sie den folgenden cURL-Befehl, ersetzen Sie die folgenden Werte in Klammern, und fügen Sie ihn in Ihr Terminal ein:

    curl -X GET https://localhost:{port}/weatherforecast -ki \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}"
    • {access_token} ist der Zugriffstokenwert, den Sie aus der JSON-Ausgabe im vorherigen Abschnitt aufgezeichnet haben.
    • {port} die Portnummer der Web-API, die Sie beim Ausführen der API im Terminal aufgezeichnet haben. Stellen Sie sicher, dass es sich um die https-Portnummer handelt.

  2. Wenn ein gültiges Zugriffstoken in der Anforderung enthalten ist, wird HTTP/2 200 als erwartete Antwort ähnlich der folgenden Ausgabe ausgegeben:

    HTTP/2 200
content-type: application/json; charset=utf-8
date: Day, DD Month YYYY HH:MM:SS
server: Kestrel
[{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":36,"summary":"Hot","temperatureF":96},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":43,"summary":"Warm","temperatureF":109},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":18,"summary":"Warm","temperatureF":64},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":50,"summary":"Chilly","temperatureF":121},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":3,"summary":"Bracing","temperatureF":37}]

Nächste Schritte

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