Quickstart: Een web-API aanroepen die wordt beveiligd door het Microsoft Identity Platform

Van toepassing op: Workforce-huurders Externe huurders (meer informatie)

In deze quickstart gebruikt u een voorbeeldweb-app om u te laten zien hoe u een ASP.NET web-API beveiligt met behulp van het Microsoft Identity Platform. In het voorbeeld wordt MSAL- (Microsoft Authentication Library) gebruikt om verificatie af te handelen.

Voorwaarden

• Een Azure-account met een actief abonnement. Maak gratis een account.
• Visual Studio 2022. Download Visual Studio voor gratis.

Web-API-toepassing registreren

Als u de registratie wilt voltooien, geeft u de toepassing een naam op en geeft u de ondersteunde accounttypen op. Nadat de toepassing is geregistreerd, worden op de Overzicht pagina de identificators weergegeven die nodig zijn in de broncode van de toepassing.

1. Meld u aan bij het Microsoft Entra-beheercentrum als ten minste een Applicatieontwikkelaar.

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 Identity>Applications>App-registraties.

4. Selecteer Nieuwe registratie.

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

6. Voor ondersteunde accounttypenselecteert u Accounts in deze organisatiemap alleen. Voor informatie over verschillende accounttypen selecteert u Help mij optie te kiezen.

7. Selecteer registreren.

   

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

   

Notitie

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

Een 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 de aangevraagde bewerking alleen uit als het toegangstoken dat het ontvangt de vereiste machtigingen bevat.

ASP.NET

1. Selecteer onder BeherenEen API beschikbaar maken>Een scope toevoegen. Accepteer de voorgestelde URI voor de toepassings-id (api://{clientId}) door Opslaan te selecteren en door te gaanen voer vervolgens de volgende gegevens in:

   1. Voer voor bereiknaamaccess_as_userin.
   2. Voor Wie kantoestemming geven, moet u ervoor zorgen dat de optie beheerders en gebruikers is geselecteerd.
   3. Voer Access TodoListService as a userin het vak weergavenaam voor beheerderstoestemming Access TodoListService as a userin.
   4. In het vak Beschrijving van de beheerderstoestemming, voer Accesses the TodoListService web API as a userin.
   5. Voer Access TodoListService as a userin het vak weergave naam van gebruikerstoestemming in.
   6. Typ Accesses the TodoListService web API as a userin het vak beschrijving van gebruikerstoestemming.
   7. Voor statushoudt u ingeschakeld.

2. Selecteer Bereik toevoegen.

ASP.NET CORE

1. Onder Beheren, selecteer Een API blootstellen > Een bereik toevoegen. Accepteer de voorgestelde URI voor toepassings-id(api://{clientId}) door Opslaan te selecteren en door te gaan. De {clientId} is de waarde die is vastgelegd op de overzichtspagina . Voer vervolgens de volgende gegevens in:

   1. Voer voor bereiknaamForecast.Readin.
   2. Voor Wie toestemming kan geven, zorg ervoor dat de optie Beheerders en Gebruikers is geselecteerd.
   3. Voer in het vak weergavenaam voor beheerderstoestemmingRead forecast datain.
   4. Voer in het veld beheerderstoestemmingsbeschrijvingAllows the application to read weather forecast datain.
   5. Voer Read forecast datain het vak weergavenaam van gebruikerstoestemming in.
   6. Typ Allows the application to read weather forecast datain het vak beschrijving van gebruikerstoestemming.
   7. Zorg ervoor dat de status is ingesteld op ingeschakeld.

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

   

De voorbeeldtoepassing klonen of downloaden

Als u de voorbeeldtoepassing wilt verkrijgen, kunt u deze klonen vanuit GitHub of downloaden als een .zip-bestand.

ASP.NET

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

• download het als een ZIP-bestand.

Tip

Om fouten te voorkomen die worden veroorzaakt door padlengtebeperkingen in Windows, raden we u aan het archief uit te pakken of de repository te klonen in een map dicht bij de hoofdmap van uw schijf.

ASP.NET CORE

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

• Download het .zip bestand. Pak het uit naar een bestandspad waarbij de lengte van de naam minder dan 260 tekens is.

De voorbeeldtoepassing configureren

Configureer het codevoorbeeld zodat het overeenkomt met de geregistreerde web-API.

ASP.NET

1. Open de oplossing in Visual Studio en open het bestand appsettings.json onder de hoofdmap van het TodoListService-project.

2. Vervang de waarde van Enter_the_Application_Id_here door de Client ID (toepassings-id) waarde van de toepassing die u hebt geregistreerd in de app-registraties portal, zowel in de eigenschappen ClientID als Audience.

Voeg het nieuwe bereik toe aan het app.config-bestand

Voer de volgende stappen uit om het nieuwe bereik toe te voegen aan het bestand TodoListClient app.config:

1. Open in de hoofdmap van het TodoListClient-project het app.config-bestand.

2. Plak de toepassings-id uit de toepassing die u hebt geregistreerd voor uw TodoListService-project in de parameter TodoListServiceScope, waarbij u de {Enter the Application ID of your TodoListService from the app registration portal} tekenreeks vervangt.

Notitie

Zorg ervoor dat de toepassings-id de volgende indeling gebruikt: api://{TodoListService-Application-ID}/access_as_user (waarbij {TodoListService-Application-ID} de GUID is die de toepassings-id voor uw TodoListService-app vertegenwoordigt).

De web-app registreren (TodoListClient)

Registreer uw TodoListClient-app in App-registraties in Azure Portal en configureer vervolgens de code in het TodoListClient-project. Als de client en server als dezelfde toepassing worden beschouwd, kunt u de toepassing die is geregistreerd in stap 2 opnieuw gebruiken. Gebruik dezelfde toepassing als u wilt dat gebruikers zich aanmelden met een persoonlijk Microsoft-account.

De app registreren

Volg deze stappen om de TodoListClient-app te registreren:

1. Meld je aan bij het Microsoft Entra-beheercentrum als ten minste een cloud-toepassingsbeheerder.

2. Blader naar Identity>Applications>App-registraties en selecteer Nieuwe registratie.

3. Selecteer Nieuwe registratie.

4. Wanneer de Een toepassingspagina registreren wordt geopend, voert u de registratiegegevens van uw toepassing in:

   1. Voer in de sectie Naam een beschrijvende toepassingsnaam in die wordt weergegeven aan gebruikers van de app (bijvoorbeeld NativeClient-DotNet-TodoListClient).
   2. Voor ondersteunde accounttypenselecteert u Accounts in een organisatiemap.
   3. Selecteer registreren om de toepassing te maken.

   Notitie

   In het todoListClient-project app.config bestand is de standaardwaarde van ida:Tenant ingesteld op common. De mogelijke waarden zijn:

   • common: u kunt zich aanmelden met een werk- of schoolaccount of een persoonlijk Microsoft-account (omdat u Accounts hebt geselecteerd in een organisatiemap in een vorige stap).
   • organizations: U kunt zich aanmelden met een werk- of schoolaccount.
   • consumers: u kunt zich alleen aanmelden met een persoonlijk Microsoft-account.

5. Selecteer op de pagina Overzicht de optie Authenticatieen voer vervolgens de volgende stappen uit om een platform toe te voegen:

   1. Selecteer onder Platformconfiguratiesde knop Een platform toevoegen.
   2. Selecteer voor Mobile- en desktoptoepassingende optie Mobile- en desktoptoepassingen.
   3. Voor de omleidings-URI's , selecteer het selectievakjehttps://login.microsoftonline.com/common/oauth2/nativeclient.
   4. Selecteer configureren.

6. Selecteer API-machtigingenen voer vervolgens de volgende stappen uit om machtigingen toe te voegen:

   1. Selecteer de knop Een machtiging toevoegen.
   2. Selecteer het tabblad Mijn API's.
   3. Selecteer in de lijst met API's AppModelv2-NativeClient-DotNet-TodoListService API- of de naam die u hebt ingevoerd voor de web-API.
   4. Selecteer het selectievakje toegang_als_gebruiker machtiging als het nog niet is geselecteerd. Gebruik indien nodig het zoekvak.
   5. Selecteer de knop Machtigingen toevoegen.

Uw project configureren

Configureer uw TodoListClient-project door de toepassings-id toe te voegen aan het app.config-bestand.

1. Kopieer in de app-registraties portal op de pagina Overzicht de waarde van de Toepassings-id (client)-id.

2. Open in de hoofdmap van het TodoListClient-project het app.config bestand en plak de waarde van de toepassings-id in de parameter ida:ClientId.

ASP.NET CORE

1. Open in uw IDE de projectmap ms-identity-docs-code-dotnet/web-apimet het voorbeeld.

2. Open appsettings.json bestand dat het volgende codefragment bevat:

   {
     "AzureAd": {
       "Instance": "https://login.microsoftonline.com/", //For external tenants, use instance in the form of "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"
       "TenantId": "Enter the tenant ID obtained from the Microsoft Entra admin center",
       "ClientId": "Enter the client ID obtained from the Microsoft Entra admin center",
       "Scopes": "Forecast.Read"
     },
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning"
       }
     },
     "AllowedHosts": "*"
   }
   

   Zoek de volgende key:

   • ClientId : de id van de toepassing, ook wel de client genoemd. Vervang de value tekst tussen aanhalingstekens door Application-id (client)-id die eerder is vastgelegd op de pagina Overzicht van de geregistreerde toepassing.
   • TenantId: de id van de tenant waar de toepassing is geregistreerd. Vervang de value tekst binnen aanhalingstekens door de waarde van de Directory (tenant) ID die eerder is vastgelegd op de Overzichtpagina van de geregistreerde toepassing.

De voorbeeldtoepassing uitvoeren

ASP.NET

Start beide projecten. Voor Visual Studio-gebruikers;

1. Klik met de rechtermuisknop op de Visual Studio-oplossing en selecteer Eigenschappen

2. Selecteer in de Algemene eigenschappenopstartproject en vervolgens meerdere opstartprojecten.

3. Kies voor beide projecten starten als actie

4. Zorg ervoor dat de TodoListService-service eerst wordt gestart door deze met de pijl-omhoog naar de eerste positie in de lijst te verplaatsen.

Meld u aan om uw TodoListClient-project uit te voeren.

1. Druk op F5 om de projecten te starten. De servicepagina wordt geopend, evenals de bureaubladtoepassing.

2. Selecteer in de TodoListClient rechtsboven Aanmeldenen meld u vervolgens aan met dezelfde referenties die u hebt gebruikt om uw toepassing te registreren of meld u aan als een gebruiker in dezelfde map.

   Als u zich voor de eerste keer aanmeldt, wordt u mogelijk gevraagd om toestemming te geven voor de Web-API todoListService.

   Om u te helpen toegang te krijgen tot de TodoListService-web-API en de Takenlijst te bewerken, vraagt de aanmeldprocedure ook om een toegangstoken voor het access_as_user bereik.

Uw clienttoepassing vooraf autoriseren

U kunt gebruikers uit andere mappen toegang geven tot uw web-API door de clienttoepassing vooraf te autoriseren voor toegang tot uw web-API. U doet dit door de toepassings-id van de client-app toe te voegen aan de lijst met vooraf geautoriseerde toepassingen voor uw web-API. Door een vooraf geautoriseerde client toe te voegen, kunt u gebruikers toegang geven tot uw web-API zonder toestemming te hoeven geven.

1. Open in de App-registraties portal de eigenschappen van uw TodoListService-app.
2. Selecteer in de sectie Een API- beschikbaar maken onder geautoriseerde clienttoepassingende optie Een clienttoepassing toevoegen.
3. Plak in het vak Client-id de toepassings-id van de TodoListClient-app.
4. Selecteer in het gedeelte Geautoriseerde scopes de scope voor de api://<Application ID>/access_as_user web-API.
5. Selecteer Toepassing toevoegen.

Uw project uitvoeren

1. Druk op F5- om uw project uit te voeren. Uw TodoListClient-app wordt geopend.
2. Selecteer rechtsboven Aanmeldenen meld u aan met een persoonlijk Microsoft-account, zoals een live.com- of hotmail.com-account of een werk- of schoolaccount.

Optioneel: Aanmeldingstoegang beperken tot bepaalde gebruikers

Standaard kunnen persoonlijke accounts, zoals outlook.com- of live.com-accounts, of werk- of schoolaccounts van organisaties die zijn geïntegreerd met Microsoft Entra-id tokens aanvragen en toegang krijgen tot uw web-API.

Als u wilt opgeven wie zich kan aanmelden bij uw toepassing, wijzigt u de eigenschap TenantId in het appsettings.json-bestand.

ASP.NET CORE

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

   dotnet run
   

2. Er wordt een uitvoer weergegeven zoals in het volgende voorbeeld:

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

   Noteer het poortnummer in de http://localhost:{port}-URL.

3. Als u wilt controleren of het eindpunt is beveiligd, werkt u de basis-URL bij in de volgende cURL-opdracht zodat deze overeenkomt met de url die u in de vorige stap hebt ontvangen en voert u de opdracht uit:

   curl -X GET https://localhost:5001/weatherforecast -ki
   

   Het verwachte antwoord is 401 Niet geautoriseerd met uitvoer die vergelijkbaar is met:

   user@host:~$ curl -X GET https://localhost:5001/weatherforecast -ki
   HTTP/2 401
   date: Fri, 23 Sep 2023 23:34:24 GMT
   server: Kestrel
   www-authenticate: Bearer
   content-length: 0
   

Volgende stappen

ASP.NET

Leer meer door te leren hoe je een beveiligde ASP.NET Core-web-API bouwt in de volgende reeks tutorials.

Zelfstudie beveiligde web-API

ASP.NET CORE

Ga verder met het volgende artikel voor meer informatie over het aanroepen van de beveiligde web-API met behulp van cURL.

Instructies: een ASP.NET Core-web-API aanroepen met cURL-