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

In de volgende quickstart wordt een codevoorbeeld gebruikt dat laat zien hoe u een ASP.NET web-API beveiligt door de toegang tot de bijbehorende resources te beperken tot alleen geautoriseerde accounts. Het voorbeeld ondersteunt autorisatie van persoonlijke Microsoft-accounts en -accounts in elke Microsoft Entra-organisatie.

In het artikel wordt ook een WPF-app (Windows Presentation Foundation) gebruikt om te laten zien hoe u een toegangstoken aanvraagt voor toegang tot een web-API.

Voorwaarden

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

Het voorbeeld klonen of downloaden

Het codevoorbeeld kan op twee manieren worden verkregen:

• Kloon het vanuit uw shell of commandoregel.

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

• download het als een ZIP-bestand.

Fooi

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

De web-API registreren (TodoListService)

Registreer uw web-API in Appregistraties in de Azure-portal.

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

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 en selecteer Nieuwe registratie.

4. Voer een naam in voor uw toepassing, bijvoorbeeld AppModelv2-NativeClient-DotNet-TodoListService. Gebruikers van uw app zien deze naam mogelijk en u kunt deze later wijzigen.

5. Voor ondersteunde accounttypenselecteert u Accounts in een organisatiemap.

6. Klik op Registreer om de toepassing te maken.

7. Zoek op de pagina Overzicht de toepassings-id (client) en noteer deze voor later gebruik. U hebt het nodig om het Visual Studio-configuratiebestand voor dit project te configureren (dat wil gezegd, ClientId in de TodoListService-\appsettings.jsop bestand).

8. Selecteer onder Beheren, Maak een API beschikbaar>Voeg een scope toe. 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 in het vak weergavenaam voor beheerderstoestemmingAccess TodoListService as a userin.
   4. Voer in de beschrijving van de beheerderstoestemming Accesses the TodoListService web API as a userin.
   5. Voer Access TodoListService as a userin het vak Gebruikersnaam voor toestemming in.
   6. Typ Accesses the TodoListService web API as a userin het vak beschrijving van gebruikerstoestemming.
   7. Voor statushoudt u ingeschakeld.

9. Selecteer Voer bereik toe.

Het serviceproject configureren

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

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 de Enter_the_Application_Id_here door de waarde van de client-id (toepassings-id) van de toepassing die u hebt geregistreerd in de App-registraties portal, zowel in de ClientID als in de Audience eigenschappen.

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 u aan bij het Microsoft Entra-beheercentrum als ten minste een Cloudtoepassingsbeheerder.

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 Register en Categorie om de toepassing te creëren.

   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 overzichtverificatieen 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 desktoptoepassingenMobile- en desktoptoepassingen.
   3. Voor doorstuur-URI's, vink het selectievakje https://login.microsoftonline.com/common/oauth2/nativeclient aan.
   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. Schakel het selectievakje access_as_user machtiging in als dit nog niet is ingeschakeld. 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.

Uw projecten uitvoeren

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 eigenschappen de optie opstartproject en kies vervolgens meerdere opstartprojecten.

3. Kies Start als actie voor beide projecten

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 de TodoListService-web-API te openen en de Takenlijst te bewerken, vraagt het aanmeldproces ook om een toegangstoken voor de access_as_user scope.

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 bereik het bereik 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.

Help en ondersteuning

Als u hulp nodig hebt, een probleem wilt melden of meer wilt weten over uw ondersteuningsopties, raadpleegt u Help en ondersteuning voor ontwikkelaars.

Volgende stappen

Meer te weten komen door een beveiligde ASP.NET Core-web-API te bouwen in de volgende tutorialreeks:

Zelfstudie beveiligde web-API