Share via

Een ASP.NET Core-web-API aanroepen met cURL

  • Artikel

In dit artikel leest u hoe u een beveiligde ASP.NET Core-web-API aanroept met behulp van client-URL (cURL). cURL is een opdrachtregelprogramma dat ontwikkelaars gebruiken om gegevens over te dragen van en naar een server. In dit artikel registreert u een web-app en een web-API in een tenant. De web-app wordt gebruikt om een toegangstoken op te halen dat wordt gegenereerd door het Microsoft Identity Platform. Vervolgens gebruikt u het token om een geautoriseerde aanroep naar de web-API te maken met behulp van cURL.

In dit artikel leest u hoe u een beveiligde ASP.NET Core-web-API aanroept met behulp van client-URL (cURL). cURL is een opdrachtregelprogramma dat ontwikkelaars gebruiken om gegevens over te dragen van en naar een server. Verderop in de zelfstudie: Een beveiligd eindpunt implementeren in uw API, waar u een beveiligde API hebt gemaakt, moet u een webtoepassing registreren bij het Microsoft Identity Platform om een toegangstoken te genereren. Vervolgens gebruikt u het token om een geautoriseerde aanroep naar de API te maken met behulp van cURL.

Vereisten

  • Een Azure-account met een actief abonnement. Gratis een account maken
  • Dit Azure-account moet machtigingen hebben voor het beheren van toepassingen. Een van de volgende Microsoft Entra-rollen omvat de vereiste machtigingen:
    • Toepassingsbeheerder
    • Toepassingsontwikkelaar
    • Beheerder van de cloudtoepassing
  • Download en installeer cURL op uw werkstationcomputer.
  • Een minimale vereiste van .NET 8.0 SDK.

Een toepassing registreren bij het Microsoft-identiteitsplatform

Voor het Microsoft Identity Platform moet uw toepassing worden geregistreerd voordat u identiteits- en toegangsbeheerservices levert. Met de toepassingsregistratie kunt u de naam en het type van de toepassing en de aanmeldingsdoelgroep opgeven. De aanmeldingsdoelgroep geeft aan welke typen gebruikersaccounts zich mogen aanmelden bij een bepaalde toepassing.

De web-API registreren

Tip

Stappen in dit artikel kunnen enigszins variëren op basis van de portal waaruit u begint.

Volg deze stappen om de web-API-registratie te maken:

  1. Meld u als toepassingsontwikkelaar aan bij het Microsoft Entra-beheercentrum.

  2. Als u toegang hebt tot meerdere tenants, gebruikt u het pictogram Instellingen in het bovenste menu om over te schakelen naar de tenant waarin u de toepassing wilt registreren in het menu Mappen en abonnementen.

  3. Blader naar identiteitstoepassingen>> App-registraties.

  4. Selecteer Nieuwe registratie.

  5. Voer een naam in voor de toepassing, zoals NewWebAPI1.

  6. Bij Ondersteunde accounttypen selecteert u Enkel accounts in deze organisatieadreslijst. Selecteer De optie Help mij kiezen voor informatie over verschillende accounttypen.

  7. Selecteer Registreren.

    Schermopname die laat zien hoe u een naam invoert en het accounttype selecteert.

  8. Het deelvenster Overzicht van de toepassing wordt weergegeven wanneer de registratie is voltooid. Noteer de map-id (tenant) en de toepassings-id (client) die moet worden gebruikt in de broncode van uw toepassing.

    Schermopname van de id-waarden op de overzichtspagina.

Notitie

De ondersteunde accounttypen kunnen worden gewijzigd door te verwijzen naar De accounts wijzigen die door een toepassing worden ondersteund.

De API beschikbaar maken

Zodra de API is geregistreerd, kunt u de machtiging ervan configureren door de bereiken te definiëren die de API beschikbaar maakt voor clienttoepassingen. Clienttoepassingen vragen toestemming om bewerkingen uit te voeren door een toegangstoken samen met de aanvragen door te geven aan de beveiligde web-API. De web-API voert vervolgens de aangevraagde bewerking alleen uit als het toegangstoken dat wordt ontvangen geldig is.

  1. Selecteer onder Beheren de optie Een API > beschikbaar maken en een bereik toevoegen. Accepteer de voorgestelde URI(api://{clientId}) voor de toepassings-id door Opslaan te selecteren en door te gaan. Dit {clientId} is de waarde die is vastgelegd op de pagina Overzicht . Voer vervolgens de volgende gegevens in:

    1. Voer bij Bereiknaam de naam inForecast.Read.
    2. Zorg ervoor dat de optie Beheerders en gebruikers is geselecteerd voor Wie kan toestemming verlenen?
    3. Voer in het vak Weergavenaam van beheerderstoestemming de naam in Read forecast data.
    4. Voer in het vak Beschrijving van beheerderstoestemming het volgende in Allows the application to read weather forecast data.
    5. Voer in het vak Weergavenaam van gebruikerstoestemming de tekst in Read forecast data.
    6. Voer in het vak Beschrijving van gebruikerstoestemming de tekst in Allows the application to read weather forecast data.
    7. Zorg ervoor dat de status is ingesteld op Ingeschakeld.

  2. Selecteer Bereik toevoegen. Als het bereik correct is ingevoerd, wordt dit weergegeven in het deelvenster Een API beschikbaar maken.

    Schermopname van de veldwaarden bij het toevoegen van het bereik aan een API.

De web-app registreren

Het hebben van een web-API is echter niet voldoende, omdat er ook een web-app nodig is om een toegangstoken te verkrijgen voor toegang tot de web-API die u hebt gemaakt.

Volg deze stappen om de registratie van de web-app te maken:

  1. Selecteer Start om terug te keren naar de startpagina. Blader naar identiteitstoepassingen>> App-registraties.
  2. Selecteer Nieuwe registratie.
  3. Voer een naam in voor de toepassing, zoals web-app-calls-web-api.
  4. Bij Ondersteunde accounttypen selecteert u Enkel accounts in deze organisatieadreslijst. Selecteer de optie Help mij kiezen voor informatie over verschillende accounttypen.
  5. Selecteer onder Omleidings-URI (optioneel) de optie Web en voer http://localhost het tekstvak URL in.
  6. Selecteer Registreren.
  1. Meld u als toepassingsontwikkelaar aan bij het Microsoft Entra-beheercentrum.
  2. Als u toegang hebt tot meerdere tenants, gebruikt u het pictogram Instellingen in het bovenste menu om over te schakelen naar de tenant waarin u de toepassing wilt registreren in het menu Mappen en abonnementen.
  3. Blader naar identiteitstoepassingen>> App-registraties.
  4. Selecteer Nieuwe registratie.
  5. Voer een naam in voor de toepassing, zoals web-app-calls-web-api.
  6. Bij Ondersteunde accounttypen selecteert u Enkel accounts in deze organisatieadreslijst. Selecteer de optie Help mij kiezen voor informatie over verschillende accounttypen.
  7. Selecteer onder Omleidings-URI (optioneel) de optie Web en voer http://localhost het tekstvak URL in.
  8. Selecteer Registreren.

Wanneer de registratie is voltooid, wordt de app-registratie weergegeven in het deelvenster Overzicht . Noteer de map-id (tenant) en de toepassings-id (client-id ) die in latere stappen moeten worden gebruikt.

Een clientgeheim toevoegen

Een clientgeheim is een tekenreekswaarde die uw app kan gebruiken om zichzelf te identificeren en wordt ook wel een toepassingswachtwoord genoemd. De web-app gebruikt het clientgeheim om de identiteit te bewijzen wanneer tokens worden aangevraagd.

Volg deze stappen om een clientgeheim te configureren:

  1. Selecteer in het deelvenster Overzicht onder Beheren de optie Certificaten en geheimen Clientgeheimen>>Nieuw clientgeheim.

  2. Voeg een beschrijving toe voor uw clientgeheim, bijvoorbeeld Mijn clientgeheim.

  3. Selecteer een vervaldatum voor het geheim of geef een aangepaste levensduur op.

    • De levensduur van een clientgeheim is beperkt tot twee jaar (24 maanden) of minder. U kunt geen aangepaste levensduur opgeven die langer is dan 24 maanden.
    • Microsoft raadt u aan een verloopwaarde van minder dan 12 maanden in te stellen.

  4. Selecteer Toevoegen.

  5. Zorg ervoor dat u de waarde van het clientgeheim opneemt. De waarde van het geheim wordt nooit meer weergegeven nadat u deze pagina hebt verlaten.

Toepassingsmachtigingen toevoegen om toegang tot een web-API toe te staan

Door de bereiken van een web-API op te geven in de registratie van de web-app, kan de web-app een toegangstoken verkrijgen dat de bereiken bevat die door het Microsoft Identity Platform worden geleverd. Binnen de code kan de web-API vervolgens toegang bieden op basis van machtigingen tot de resources op basis van de bereiken in het toegangstoken.

Volg deze stappen om de machtigingen voor de web-app te configureren voor de web-API:

  1. Selecteer in het deelvenster Overzicht van uw webtoepassing (web-app-die-aanroepen-web-API) onder Beheren DE API-machtigingen Een machtigings-API>>toevoegen die door mijn organisatie wordt gebruikt.
  2. Selecteer NewWebAPI1 of de API waaraan u machtigingen wilt toevoegen.
  3. Schakel onder Machtigingen selecteren het selectievakje naast Forecast.Read in. Mogelijk moet u de lijst met machtigingen uitvouwen. Hiermee selecteert u de machtigingen die de client-app moet hebben namens de aangemelde gebruiker.
  4. Selecteer Machtigingen toevoegen om het proces te voltooien.

Nadat u deze machtigingen aan uw API hebt toegevoegd, ziet u de geselecteerde machtigingen onder Geconfigureerde machtigingen.

U ziet mogelijk ook de machtiging User.Read voor de Microsoft Graph API. Deze machtiging wordt automatisch toegevoegd wanneer u een app registreert.

De web-API testen

  1. Kloon de opslagplaats ms-identity-docs-code-dotnet .

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

  2. Navigeer naar ms-identity-docs-code-dotnet/web-api de map en open ./appsettings.json het bestand, vervang de {APPLICATION_CLIENT_ID} en {DIRECTORY_TENANT_ID} door:

    • {APPLICATION_CLIENT_ID}is de web-API-toepassings-id (client) in het deelvenster Overzicht van de app App-registraties.
    • {DIRECTORY_TENANT_ID}is de web-API Directory-id (tenant) in het deelvenster Overzicht van de app App-registraties.

  3. Voer de volgende opdracht uit om de app te starten:

    dotnet run

  4. Er wordt een uitvoer weergegeven die lijkt op het volgende. Noteer het poortnummer in de https://localhost:{port} URL.

    ... 
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...

De web-API testen

  1. Navigeer naar de web-API die is gemaakt in de zelfstudie: Maak een ASP.NET Core-project en configureer de API, bijvoorbeeld NewWebAPILocal, en open de map.

  2. Open een nieuw terminalvenster en navigeer naar de map waarin het web-API-project zich bevindt.

  1. Voer de volgende opdracht uit om de app te starten:

    dotnet run

  1. Er wordt een uitvoer weergegeven die lijkt op het volgende. Noteer het poortnummer in de https://localhost:{port} URL.

    ... 
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...

Een autorisatiecode aanvragen

De autorisatiecodestroom begint met de client die de gebruiker naar het /authorize eindpunt leidt. In deze aanvraag vraagt de client de Forecast.Read machtiging van de gebruiker aan.

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. Kopieer de URL, vervang de volgende parameters en plak deze in uw browser:

    • {tenant_id}is de map-id (tenant) van de web-app.
    • {web-app-calls-web-api_application_client_id}is de toepassings-id (client) in het overzichtsvenster van de web-app (web-app-calls-web-api).
    • {web_API_application_client_id}is de toepassings-id (client) in het deelvenster Overzicht van de web-API (NewWebAPI1).

  2. Meld u aan als gebruiker in de Microsoft Entra-tenant waarin de apps zijn geregistreerd. Geef indien nodig toestemming voor toegangsaanvragen.

  3. Uw browser wordt omgeleid naar http://localhost/. Raadpleeg de navigatiebalk van uw browser en kopieer de {authorization_code} navigatiebalk die u wilt gebruiken in de volgende stappen. De URL heeft de vorm van het volgende fragment:

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

Een autorisatiecode en cURL gebruiken om een toegangstoken op te halen

cURL kan nu worden gebruikt om een toegangstoken aan te vragen via het Microsoft Identity Platform.

  1. Kopieer de cURL-opdracht in het volgende fragment. Vervang de waarden tussen haakjes door de volgende parameters aan uw terminal. Verwijder de haakjes:

    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}is de map-id (tenant) van de web-app.
    • client_id={web-app-calls-web-api_application_client_id}en session_state={web-app-calls-web-api_application_client_id} is de toepassings-id (client) in het overzichtsvenster van de webtoepassing (web-app-calls-web-api).
    • api://{web_API_application_client_id}/Forecast.Readis de toepassings-id (client) in het deelvenster Overzicht van de web-API (NewWebAPI1).
    • code={authorization_code} is de autorisatiecode die is ontvangen in Een autorisatiecode aanvragen. Hierdoor kan het cURL-hulpprogramma een toegangstoken aanvragen.
    • client_secret={client_secret}is de waarde van het clientgeheim die is vastgelegd in Een clientgeheim toevoegen.

  2. Voer de cURL-opdracht uit en als deze correct is ingevoerd, ontvangt u een JSON-antwoord dat lijkt op de volgende uitvoer:

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

Web-API aanroepen met toegangstoken

Door de vorige cURL-opdracht uit te voeren, heeft het Microsoft Identity Platform een toegangstoken opgegeven. Het verkregen token kan nu worden gebruikt als bearer in een HTTP-aanvraag om de web-API aan te roepen.

  1. Als u de web-API wilt aanroepen, kopieert u de volgende cURL-opdracht, vervangt u de volgende waarden tussen haakjes en plakt u deze in uw terminal:

    curl -X GET https://localhost:{port}/weatherforecast -ki \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}"
    • {access_token} de waarde van het toegangstoken die is vastgelegd in de JSON-uitvoer in de vorige sectie.
    • {port} het poortnummer van de web-API geregistreerd bij het uitvoeren van de API in de terminal. Zorg ervoor dat dit het https poortnummer is.

  2. Met een geldig toegangstoken dat is opgenomen in de aanvraag, heeft het verwachte antwoord uitvoer die vergelijkbaar is HTTP/2 200 met de volgende uitvoer:

    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}]

Volgende stappen

Zie voor meer informatie over OAuth 2.0-autorisatiecodestroom en toepassingstypen: