Quickstart: gebruikers aanmelden en een web-API aanroepen in voorbeeld-Node.js web-app

Van toepassing op: Werknemerhuurders Externe huurders (meer informatie)

In deze quickstart leert u hoe u gebruikers aanmeldt en een web-API aanroept vanuit een Node.js-webtoepassing in uw externe tenant. De voorbeeldtoepassing roept een .NET API aan. De voorbeeldwebtoepassing maakt gebruik van MSAL- (Microsoft Authentication Library) voor Node om verificatie af te handelen.

Voorwaarden

• Voltooi de stappen en vereisten in het artikel "Quickstart: Gebruikers aanmelden in een voorbeeld-webapp". In dit artikel leest u hoe u gebruikers kunt aanmelden met behulp van een voorbeeld-Node.js-web-app.
• Visual Studio Code of een andere code-editor.
• Node.js.
• .NET 7.0 of hoger.
• Een externe tenant. Kies een van de volgende methoden om er een te maken:
  • (Aanbevolen) Gebruik de externe id-extensie van Microsoft Entra om rechtstreeks in Visual Studio Code een externe tenant in te stellen.
  • maak een nieuwe externe tenant in het Microsoft Entra-beheercentrum.

Een web-API registreren

In deze stap maakt u de web- en web-API-toepassingsregistraties en geeft u de bereiken van uw web-API op.

Een web-API-toepassing registreren

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 naar uw externe tenant over te schakelen vanuit het menu Mappen en abonnementen.

3. Blader naar Identiteit>Applicaties>App-registraties.

4. Selecteer + Nieuwe registratie.

5. Voer op de pagina Registreer een toepassing die wordt weergegeven 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 ciam-ToDoList-api.

   2. Selecteer onder Ondersteunde accounttypenalleen Accounts in dit organisatieadresboek.

6. Selecteer Registreren om de applicatie aan te maken.

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

API-bereiken configureren

Deze web-API moet machtigingen beschikbaar maken die een client-app verkrijgt om de web-API aan te roepen.

Een API moet minimaal één bereik publiceren, ook wel gedelegeerde machtiginggenoemd, zodat de client-apps een toegangstoken voor een gebruiker kunnen verkrijgen. Voer de volgende stappen uit om een scope te publiceren:

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

2. Onder Beheren, selecteer Een API beschikbaar maken.

3. Selecteer boven aan de pagina, naast URI voor 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 zijn gedefinieerd door deze APIde optie 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:

   Eigenschap	Waarde
   Bereiknaam	ToDoList.Read
   Wie kan toestemming geven	Alleen beheerders
   Beheerderstoestemmingweergavenaam	Lees de ToDo-lijst van gebruikers met behulp van de TodoListApi
   Beschrijving van beheerderstoestemming	Sta de app toe om de takenlijst van de gebruiker te lezen met behulp van de TodoListApi.
   Staat	ingeschakeld

7. Selecteer 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:

   Eigendom	Waarde
   Bereiknaam	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.

App-rollen configureren

Een API moet minimaal één app-rol publiceren voor toepassingen, ook wel toepassingsmachtiginggenoemd, 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 pagina Overzicht te openen.

2. Selecteer onder Beherende optie App-rollen.

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

   Eigenschap	Waarde
   Weergavenaam	ToDoList.Read.All
   Toegestane lidtypen	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 App-rol maken opnieuw en voer vervolgens de volgende waarden in voor de tweede app-rol en selecteer vervolgens Toepassen om uw wijzigingen op te slaan:

   Eigenschap	Waarde
   Weergavenaam	ToDoList.ReadWrite.All
   Toegestane lidtypen	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

Optionele claims configureren

U kunt de idtyp optionele claim toevoegen om de web-API te helpen bepalen of een token een -app is token of een -app + gebruiker token. Hoewel u een combinatie van scp en rollen claims voor hetzelfde doel kunt gebruiken, is het gebruik van de claim idtyp de eenvoudigste manier om een app-token van een app + gebruikerstoken te onderscheiden. De waarde van deze claim is bijvoorbeeld app wanneer het token een alleen-app-token is.

Gebruik de stappen in het artikel Optionele claims configureren om de idtyp- claim toe te voegen aan het toegangstoken:

• Voor het tokentype selecteert u Access-.
• Selecteer idtypin de lijst met optionele claims.

API-machtigingen verlenen aan de web-app

Voer de volgende stappen uit om uw client-app (ciam-client-app) API-machtigingen te verlenen:

1. Selecteer op de pagina App-registraties de toepassing die u hebt gemaakt (zoals ciam-client-app) om de pagina Overzicht te openen.

2. Onder Beheren, selecteer API-machtigingen.

3. Selecteer onder Geconfigureerde machtigingenEen machtiging toevoegen.

4. Selecteer de API's die mijn organisatie gebruikt tabblad.

5. Selecteer in de lijst met API's de API, zoals ciam-ToDoList-api.

6. Selecteer Gedelegeerde machtigingen optie.

7. Selecteer in de lijst met machtigingen ToDoList.Read, ToDoList.ReadWrite (gebruik indien nodig het zoekvak).

8. Selecteer de knop Machtigingen toevoegen. Op dit moment hebt u de machtigingen correct toegewezen. Omdat de tenant echter de tenant van een klant is, kunnen de consumentengebruikers zelf geen toestemming geven voor deze machtigingen. Om dit probleem op te lossen, moet u als beheerder toestemming geven voor deze machtigingen namens alle gebruikers in de tenant:

   1. Selecteer Beheerderstoestemming verlenen voor <uw tenantnaam>en selecteer vervolgens Ja.

   2. Selecteer Vernieuwenen controleer vervolgens dat Verleend bij <uw tenantnaam> verschijnt onder Status voor beide toepassingsgebieden.

9. Selecteer in de lijst Geconfigureerde machtigingen de ToDoList.Read- en ToDoList.ReadWrite machtigingen, één voor één en kopieer de volledige URI van de machtiging voor later gebruik. De volledige machtigings-URI ziet er ongeveer uit als api://{clientId}/{ToDoList.Read} of api://{clientId}/{ToDoList.ReadWrite}.

Voorbeeldwebtoepassing en web-API klonen of downloaden

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

• Als u het voorbeeld wilt klonen, opent u een opdrachtprompt en navigeert u naar de locatie waar u het project wilt maken en voert u de volgende opdracht in:

  git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git
  

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

Projectafhankelijkheden installeren

1. Open een consolevenster en ga naar de map met de Node.js/Express-voorbeeld-app:

   cd 2-Authorization\4-call-api-express\App
   

2. Voer de volgende opdrachten uit om afhankelijkheden van web-apps te installeren:

   npm install && npm update
   

De voorbeeldweb-app en API configureren

Uw app-registratie gebruiken in de voorbeeld-clientwebapplicatie:

1. Open App\authConfig.js bestand in de code-editor.

2. Zoek de plaatsaanduiding:

   • Enter_the_Application_Id_Here en vervang deze door de toepassings-id (client) van de client-app die u eerder hebt geregistreerd. De client-app is een app die u hebt geregistreerd bij de vereisten.
   • Enter_the_Tenant_Subdomain_Here en vervang dit door het subdomein Directory (tenant). Als uw primaire tenantdomein bijvoorbeeld is contoso.onmicrosoft.com, gebruikt u contoso. Als u uw huurdernaam niet hebt, leert u hoe u uw huurdergegevenskunt lezen.
   • Enter_the_Client_Secret_Here en vervang deze door de waarde van het app-geheim die u eerder hebt gekopieerd.
   • Enter_the_Web_Api_Application_Id_Here en vervang deze door de toepassings-id (client) van de web-API die u eerder hebt gekopieerd. De web-API-app is een app die u eerder hebt geregistreerd in Een web-API-toepassing registreren.

Uw app-registratie gebruiken in het web-API-voorbeeld:

1. Open API\ToDoListAPI\appsettings.json bestand in de code-editor.

2. Zoek de plaatsaanduiding:

   • Enter_the_Application_Id_Here en vervang deze door de toepassings-id (client) van de web-API die u hebt gekopieerd. De web-API-app is een app die u eerder hebt geregistreerd in Een web-API-toepassing registreren.
   • Enter_the_Tenant_Id_Here en vervang deze door de Directory ID (tenant) die u eerder hebt gekopieerd.
   • Enter_the_Tenant_Subdomain_Here en vervang dit door het subdomein Directory (tenant). Als uw primaire tenantdomein bijvoorbeeld is contoso.onmicrosoft.com, gebruikt u contoso. Als u uw huurdernaam niet hebt, leert u hoe u uw huurdergegevenskunt lezen.

Voorbeeldweb-app en API uitvoeren en testen

1. Open een consolevenster en voer vervolgens de web-API uit met behulp van de volgende opdrachten:

   cd 2-Authorization\4-call-api-express\API\ToDoListAPI
   dotnet run
   

2. Voer de web-app-client uit met behulp van de volgende opdrachten:

   cd 2-Authorization\4-call-api-express\App
   npm install
   npm start
   

3. Open uw browser en ga naar http://localhost:3000.

4. Selecteer de knop Aanmelden. U wordt gevraagd u aan te melden.

   

5. Typ op de aanmeldingspagina uw e-mailadres, selecteer Volgende, typ uw wachtwoorden selecteer Aanmelden. Als u geen account hebt, selecteert u Geen account? Maak één koppeling, waarmee de registratiestroom wordt gestart.

6. Als u de registratieoptie kiest, voltooit u na het invullen van uw e-mail, eenmalige wachtwoordcode, nieuw wachtwoord en meer accountgegevens de volledige aanmeldingsstroom. U ziet een pagina die vergelijkbaar is met de volgende schermopname. U ziet een vergelijkbare pagina als u de aanmeldingsoptie kiest.

   

API aanroepen

1. Als u de API wilt aanroepen, selecteert u de Bekijk uw takenlijst koppeling. U ziet een pagina die vergelijkbaar is met de volgende schermopname.

   

2. Bewerk de to-do lijst door items te maken en te verwijderen.

Hoe het werkt

U activeert een API-aanroep telkens wanneer u een taak bekijkt, toevoegt of verwijdert. Telkens wanneer u een API-aanroep activeert, verkrijgt de clientweb-app een toegangstoken met de vereiste machtigingen (bereiken) om een API-eindpunt aan te roepen. Bijvoorbeeld, om een taak te lezen, moet de webclient een toegangstoken verkrijgen met ToDoList.Read toestemming/reikwijdte.

Het eindpunt van de web-API moet controleren of de machtigingen of toepassingsgebieden in het toegangstoken, die door de client-app wordt geleverd, geldig zijn. Als het toegangstoken geldig is, reageert het eindpunt op de HTTP-aanvraag, anders reageert het met een 401 Unauthorized HTTP-fout.

Verwante inhoud

• Zelfstudie: Een ASP.NET Core-web-API beveiligen die is geregistreerd in een externe tenant.