Share via

Een ASP.NET Core web-API aanroepen met slapeloosheid

  • Artikel

In dit artikel leest u hoe u een beveiligde ASP.NET Core-web-API aanroept met behulp van slapeloosheid. Slapeloosheid is een toepassing waarmee u HTTP-aanvragen naar een web-API kunt verzenden om het autorisatie- en toegangsbeheerbeleid (verificatiebeleid) te testen. 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 slapeloosheid.

In dit artikel leest u hoe u een beveiligde ASP.NET Core-web-API aanroept met behulp van slapeloosheid. Slapeloosheid is een toepassing waarmee u HTTP-aanvragen naar een web-API kunt verzenden om het autorisatie- en toegangsbeheerbeleid (verificatiebeleid) te testen. 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 slapeloosheid.

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 Slapeloosheid. U gebruikt Slapeloosheid om een toegangstoken te verkrijgen voor uw API-aanvragen.
  • Een minimale vereiste van .NET 8.0 SDK.

Een toepassing registreren

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. U kunt het deelvenster Overzicht van de toepassing zien wanneer de registratie is voltooid. Noteer de map-id (tenant) en de toepassings-id (client-id ) die in latere stappen moeten worden gebruikt.

    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 is niet voldoende om een web-API te hebben. U hebt ook een web-app nodig om een toegangstoken te verkrijgen voor toegang tot de web-API.

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.

U kunt het deelvenster Overzicht van de toepassing zien wanneer de registratie is voltooid. 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.

Zie Best practices voor geheimenbeheer in Key Vault voor meer informatie over het veilig opslaan van uw clientgeheim.

Machtigingen toevoegen voor toegang tot uw web-API

Door de bereiken van een web-API op te geven, kan de web-app een toegangstoken verkrijgen dat de bereiken bevat die worden geleverd door het Microsoft Identity Platform. 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 van de client voor de web-API te configureren:

  1. Selecteer in het deelvenster Overzicht van uw toepassing onder Beheren DE API-machtigingen>Een machtigings-API's>toevoegen die door mijn organisatie worden 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

Volg deze stappen om ervoor te zorgen dat uw API operationeel is en klaar is voor het verwerken van aanvragen:

  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 en open appsettings.json, vervang de {APPLICATION_CLIENT_ID} en {DIRECTORY_TENANT_ID} door de volgende waarden:

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

  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

Volg deze stappen om ervoor te zorgen dat uw API operationeel is en klaar is voor het verwerken van aanvragen:

  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

  3. 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 geautoriseerde aanvraag configureren voor de web-API in Slapeloosheid

Voer de volgende stappen uit om een toegangstoken voor uw API-aanvragen te verkrijgen:

  1. Start de toepassing Slapeloosheid .

  2. Selecteer Nieuwe HTTP-aanvraag of u kunt Ctrl+N gebruiken om een nieuwe HTTP-aanvraag te maken.

  3. Selecteer in de modale nieuwe aanvraag een GET-methode in de vervolgkeuzelijst.

  4. Voer voor de aanvraag-URL de URL in van het eindpunt dat wordt weergegeven door de web-API. https://localhost:{port}/weatherforecast

  5. Selecteer OAuth 2.0 in de vervolgkeuzelijst Verificatie. Hiermee wordt het formulier OAuth 2.0 weergegeven.

  6. Voer de volgende waarden in het formulier OAuth 2.0 in:

    Instelling Weergegeven als
    TOEKENNINGSTYPE Autorisatiecode selecteren
    AUTORISATIE-URL https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
    Vervangen door {tenantId} de map-id (tenant)
    URL VAN TOEGANGSTOKEN https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
    Vervangen door {tenantId} de map-id (tenant)
    CLIENT-ID De waarde van de toepassings-id (client) van uw web-app-registratie
    CLIENTGEHEIM De waarde van het clientgeheim van de registratie van uw web-app
    OMLEIDINGS-URL Enter http://localhost, waarmee de OMLEIDINGS-URL wordt ingesteld op de omleidings-URI die is geregistreerd bij Microsoft Entra-id.
    Bereik geavanceerde opties> api://{application_client_id}/Forecast.Read
    Navigeer naar de registratie van uw web-app, selecteer API-machtigingen onder Beheren en selecteer vervolgens Forecast.Read
    Kopieer de waarde in het tekstvak, die de bereikwaarde bevat

Een toegangstoken ophalen en een aanvraag verzenden naar de web-API

  1. Zodra deze waarden zijn ingevoerd, selecteert u Tokens ophalen aan het einde van het formulier. Hiermee opent u een venster van de slapeloosheidsbrowser waarin u zich verifieert met uw gebruikersreferenties. Zorg ervoor dat pop-ups van de toepassing Slapeloosheid in de browser worden toegestaan.
  2. Nadat u de verificatie hebt uitgevoerd, selecteert u Verzenden om de aanvraag naar het beveiligde web-API-eindpunt te verzenden.

Met een geldig toegangstoken dat is opgenomen in de aanvraag, is het verwachte antwoord 200 OK met uitvoer vergelijkbaar met:

[
  {
    "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
  }
]

Gerelateerde inhoud

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