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

Van toepassing op: Werknemerstenants Externe tenants (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. Het voorbeeld maakt gebruik van de Microsoft Authentication Library (MSAL) om verificatie en autorisatie af te handelen.

Vereiste voorwaarden

• Een Azure-account met een actief abonnement. Maak gratis een account.
• Registreer een nieuwe app in het Microsoft Entra-beheercentrum en noteer de id's van de app-overzichtspagina . Zie Een toepassing registreren voor meer informatie.
  • Naam: NewWebAPI1
  • Ondersteunde accounttypen: alleen accounts in deze organisatiemap (één tenant)

ASP.NET

• Visual Studio 2022. Download Visual Studio gratis.

ASP.NET Core

• Visual Studio Code

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

ASP.NET

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

   1. Voer bij Naam van het bereikaccess_as_user in.
   2. Voor wie toestemming kan geven, moet u ervoor zorgen dat de optie Beheerders en gebruikers is geselecteerd.
   3. Voer in het vak Weergavenaam van beheerderstoestemming de naam in Access TodoListService as a user.
   4. Voer in het vak Beschrijving van beheerderstoestemming het volgende in Accesses the TodoListService web API as a user.
   5. Voer in het vak Weergavenaam van gebruikerstoestemming in Access TodoListService as a user.
   6. Voer in het vak Beschrijving van gebruikerstoestemming de tekst in Accesses the TodoListService web API as a user.
   7. Houd ingeschakeld voor status.

2. Klik op Bereik toevoegen.

ASP.NET Core

Gedelegeerde machtigingen toevoegen (bereiken)

Een API moet minimaal één "scope", ook wel Gedelegeerde machtiging genoemd, publiceren zodat de client-applicaties met succes een toegangstoken voor een gebruiker kunnen verkrijgen. Voer de volgende stappen uit om een reikwijdte te publiceren:

1. Selecteer op de pagina App-registraties de API-toepassing die u hebt gemaakt (ciam-ToDoList-api) om de overzichtspagina te openen.

2. Selecteer onder Behereneen API beschikbaar maken.

3. Selecteer boven aan de pagina, naast de URI van de toepassings-id, de koppeling Toevoegen om een URI te genereren die uniek is voor deze app.

4. Accepteer de voorgestelde URI voor de toepassings-id, zoals api://{clientId}, en selecteer Opslaan. Wanneer uw webtoepassing een toegangstoken voor de web-API aanvraagt, wordt de URI toegevoegd als het voorvoegsel voor elk bereik dat u voor de API definieert.

5. Selecteer Onder Bereiken die door deze API zijn gedefinieerd, een bereik toevoegen.

6. Voer de volgende waarden in waarmee een leestoegang tot de API wordt gedefinieerd en selecteer vervolgens Bereik toevoegen om uw wijzigingen op te slaan:

   Vastgoed	Waarde
   Scopenaam	ToDoList.Lezen
   Wie kan toestemming geven	Alleen beheerders
   Beheerderstoestemmingweergavenaam	ToDo-lijst met gebruikers lezen met behulp van de TodoListApi
   Beschrijving van beheerderstoestemming	Sta toe dat de app de Takenlijst van de gebruiker kan lezen met behulp van de TodoListApi.
   Staat	Ingeschakeld

7. Selecteer Opnieuw een bereik toevoegen en voer de volgende waarden in waarmee een bereik voor lees- en schrijftoegang tot de API wordt gedefinieerd. Selecteer Bereik toevoegen om uw wijzigingen op te slaan:

   Vastgoed	Waarde
   Scopenaam	ToDoList.ReadWrite
   Wie kan toestemming geven	Alleen beheerders
   Beheerderstoestemmingweergavenaam	Lees en schrijf de ToDo-lijst van gebruikers met behulp van de ToDoListApi
   Beschrijving van beheerderstoestemming	Toestaan dat de app de Takenlijst van de gebruiker kan lezen en schrijven met behulp van de ToDoListApi
   Staat	Ingeschakeld

Meer informatie over het principe van minimale bevoegdheden bij het publiceren van machtigingen voor een web-API.

Toepassingsmachtigingen toevoegen (app-rollen)

Een API moet minimaal één app-rol publiceren voor toepassingen, ook wel toepassingsmachtiging genoemd, zodat de client-apps zelf een toegangstoken kunnen verkrijgen. Toepassingsmachtigingen zijn het type machtigingen dat API's moeten publiceren wanneer ze clienttoepassingen in staat willen stellen zich als zichzelf te verifiëren en geen gebruikers hoeven aan te melden. Voer de volgende stappen uit om een toepassingsmachtiging te publiceren:

1. Selecteer op de pagina App-registraties de toepassing die u hebt gemaakt (zoals ciam-ToDoList-api) om de overzichtspagina te openen.

2. Ga naar Beheren en selecteer app-rollen.

3. Selecteer App-rol maken en voer vervolgens de volgende waarden in en selecteer Toepassen om uw wijzigingen op te slaan:

   Vastgoed	Waarde
   Weergavenaam	ToDoList.Read.All
   Toegestane ledensoorten	Toepassingen
   Waarde	ToDoList.Read.All
   Beschrijving	Toestaan dat de app de Takenlijst van elke gebruiker kan lezen met behulp van de TodoListApi
   Wilt u deze app-rol inschakelen?	Houd deze ingeschakeld

4. Selecteer De app-rol opnieuw maken en voer vervolgens de volgende waarden in voor de tweede app-rol en selecteer Toepassen om uw wijzigingen op te slaan:

   Vastgoed	Waarde
   Weergavenaam	ToDoList.ReadWrite.All
   Toegestane ledensoorten	Toepassingen
   Waarde	ToDoList.ReadWrite.All
   Beschrijving	Toestaan dat de app de Takenlijst van elke gebruiker kan lezen en schrijven met behulp van de ToDoListApi
   Wilt u deze app-rol inschakelen?	Houd deze ingeschakeld

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.

Hint

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 wortel van uw schijf.

ASP.NET Core

git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.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 appsettings.json bestand onder de hoofdmap van het TodoListService-project.

2. Vervang de waarde van de Enter_the_Application_Id_here door de Client-id (toepassings-id) van de toepassing die u hebt geregistreerd in de portal app-registraties, zowel in de ClientID als 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 het app.configbestand in de hoofdmap van het TodoListClient-project.

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.

Opmerking

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 webapplicatie registreren (TodoListClient)

Registreer uw TodoListClient-app in app-registraties in het Microsoft Entra-beheercentrum 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 Entra> en selecteer Nieuwe registratie.

3. Selecteer Nieuwe registratie.

4. Wanneer de pagina Een toepassing 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 accounttypen selecteert u Accounts in een organisatiemap.
   3. Selecteer Registreren om de toepassing te maken.

   Opmerking

   In het todoListClient-project app.config bestand is de standaardwaarde 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 in een organisatiemap in een vorige stap hebt geselecteerd).
   • organizations: U kunt zich aanmelden met een werk- of schoolaccount.
   • consumers: u kunt zich alleen aanmelden met een persoonlijk Microsoft-account.

5. Selecteer verificatie op de pagina Overzicht van de app en voer vervolgens de volgende stappen uit om een platform toe te voegen:

   1. Selecteer onder Platformconfiguraties de knop Een platform toevoegen .
   2. Voor mobiele toepassingen en desktoptoepassingen selecteert u Mobile- en desktoptoepassingen.
   3. Schakel het selectievakje in voor https://login.microsoftonline.com/common/oauth2/nativeclient.
   4. Selecteer Configureren.

6. Selecteer API-machtigingen en 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 AppModelv2-NativeClient-DotNet-TodoListService API of de naam die u hebt ingevoerd voor de web-API in de lijst met API's.
   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 portal app-registraties op de pagina Overzicht de waarde van de toepassings-id (client).

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

ASP.NET Core

1. Open in uw IDE de projectmap ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI, met het voorbeeld.

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

   {
     "AzureAd": {
       "Instance": "Enter_the_Authority_URL_Here", //For external tenants, use instance in the form of "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"
       "TenantId": "Enter_the_Tenant_Id_Here",
       "ClientId": "Enter_the_Application_Id_Here",
       "Scopes": {
         "Read": ["ToDoList.Read", "ToDoList.ReadWrite"],
         "Write": ["ToDoList.ReadWrite"]
       },
       "AppPermissions": {
         "Read": ["ToDoList.Read.All", "ToDoList.ReadWrite.All"],
         "Write": ["ToDoList.ReadWrite.All"]
       }
     },
     "Logging": {...},
     "AllowedHosts": "*"
   }
   

   Zoek de volgende waarden:

   • ClientId : de id van de toepassing, ook wel de client genoemd. Vervang de value tekst tussen aanhalingstekens door de toepassings-id (client) 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 tussen aanhalingstekens door de Directory (tenant) ID die eerder is vastgelegd op de Overzicht-pagina van de geregistreerde toepassing.
   • Instance - Hiermee wordt de map opgegeven waaruit de Microsoft Authentication Library (MSAL) tokens kan aanvragen. Vervang Enter_the_Authority_URL_Here door een van de volgende waarden, afhankelijk van uw scenario:
     • Voor personeelstenants gebruikt u https://login.microsoftonline.com/ als instantie.
     • Voor externe tenants voegt u een instantie-URL toe in de vorm van https://<Enter_the_Tenant_Subdomain_Here>.ciamlogin.com/

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 eigenschappenhet opstartproject en vervolgens meerdere opstartprojecten.

3. Voor beide projecten kiest u Starten als de 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 aanmelden en meld u 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 manipuleren, vraagt de aanmeldprocedure ook een toegangstoken aan 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 geverifieerde toepassingen voor uw web-API. Door een vooraf geverifieerde client toe te voegen, kunt u gebruikers toegang geven tot uw web-API zonder toestemming te hoeven geven.

1. Open in de portal app-registraties de eigenschappen van uw TodoListService-app.
2. Selecteer in de sectie Een API beschikbaarmaken onder Geautoriseerde clienttoepassingende optie Een clienttoepassing toevoegen.
3. Plak in het vak Client-id de toepassings-id van de TodoListClient-app.
4. Selecteer in de sectie Geautoriseerde bereiken 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 in de rechterbovenhoek Aanmelden en meld u vervolgens 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 TenantId eigenschap in het bestandappsettings.json .

ASP.NET Core

1. Voer de volgende opdracht uit vanuit de hoofdmap van uw web-API-project om de app te starten:

   dotnet run
   

2. Als alles correct werkt, wordt in de terminal een uitvoer weergegeven die vergelijkbaar is met de volgende:

    Building...
        info: Microsoft.Hosting.Lifetime[14]
              Now listening on: https://localhost:{port}
        info: Microsoft.Hosting.Lifetime[0]
              Application started. Press Ctrl+C to shut down.
        info: Microsoft.Hosting.Lifetime[0]
              Hosting environment: Development
   ...
   

   Noteer het poortnummer in de https://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 -k -X GET https://localhost:<your-api-port>/api/todolist -w "%{http_code}\n"
   

   Het verwachte antwoord is 401 Niet geautoriseerd.

Volgende stappen

Meer informatie over het beveiligen van een ASP.NET Core-web-API met het Microsoft Identity Platform.

Zelfstudie: Een ASP.NET Core-web-API bouwen en beveiligen met het Microsoft Identity Platform