Share via

Gebruikers aanmelden en een API aanroepen in voorbeeld-Node.js webtoepassing

  • Artikel

In deze handleiding wordt een voorbeeld van een Node.js-webtoepassing gebruikt om u te laten zien hoe u verificatie en autorisatie toevoegt. De voorbeeldtoepassing meldt gebruikers aan bij een Node.js-web-app, die vervolgens een .NET API aanroept. U schakelt verificatie en autorisatie in met behulp van uw externe tenantgegevens. De voorbeeldwebtoepassing maakt gebruik van Microsoft Authentication Library (MSAL) voor Node om verificatie af te handelen.

In dit artikel voert u de volgende taken uit:

  • Registreer en configureer een web-API in het Microsoft Entra-beheercentrum.

  • Registreer en configureer een clientwebtoepassing in het Microsoft Entra-beheercentrum.

  • Maak een gebruikersstroom voor registreren en aanmelden in het Microsoft Entra-beheercentrum en koppel er vervolgens een clientweb-app aan.

  • Werk een voorbeeld van een Node-webtoepassing en ASP.NET web-API bij om uw externe tenantgegevens te gebruiken.

  • Voer de voorbeeldwebtoepassing en API uit en test deze.

Vereisten

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

  3. Blader naar identiteitstoepassingen>> App-registraties.

  4. Selecteer + Nieuwe registratie.

  5. Voer op de pagina Een toepassing registreren 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. Onder Ondersteunde accounttypen selecteert u Enkel accounts in deze organisatieadreslijst.

  6. Selecteer Registreren om de toepassing te maken.

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

API-bereiken configureren

Deze API moet machtigingen beschikbaar maken, die een client moet verkrijgen voor het aanroepen van de API:

Een API moet minimaal één bereik, ook wel Gedelegeerde machtiging genoemd, publiceren voor de client-apps om een toegangstoken voor een gebruiker te verkrijgen. Voer de volgende stappen uit om een bereik 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. Onder Bereiken die door deze API worden bepaald selecteert u 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:

    Eigenschappen Weergegeven als
    Bereiknaam ToDoList.Read
    Wie kan toestemming verlenen? Alleen beheerders
    Weergavenaam voor beheerderstoestemming 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.
    Provincie 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:

    Eigenschappen Weergegeven als
    Bereiknaam ToDoList.ReadWrite
    Wie kan toestemming verlenen? Alleen beheerders
    Weergavenaam voor beheerderstoestemming ToDo-lijst met gebruikers lezen en schrijven 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
    Provincie Ingeschakeld

  8. Selecteer onder Beheren manifest om de API-manifesteditor te openen.

  9. Stel accessTokenAcceptedVersion de eigenschap in op 2.

  10. Selecteer Opslaan.

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 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. Selecteer onder Beheren app-rollen.

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

    Eigenschappen Weergegeven als
    Display name ToDoList.Read.All
    De toegestane ledentypen Toepassingen
    Weergegeven als ToDoList.Read.All
    Beschrijving Toestaan dat de app de Takenlijst van elke gebruiker kan lezen met behulp van de TodoListApi

  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:

    Eigenschappen Weergegeven als
    Display name ToDoList.ReadWrite.All
    De toegestane ledentypen Toepassingen
    Weergegeven als ToDoList.ReadWrite.All
    Beschrijving Toestaan dat de app de Takenlijst van elke gebruiker kan lezen en schrijven met behulp van de ToDoListApi

Optionele claims configureren

U kunt optionele claim idtyp gebruiken om de web-API te helpen bepalen of een token een app-token is of een app + gebruikerstoken. Hoewel u een combinatie van scp - en rollenclaims voor hetzelfde doel kunt gebruiken, is het gebruik van de idtyp-claim de eenvoudigste manier om een app-token en een app + gebruikerstoken apart te vertellen. De waarde van deze claim is bijvoorbeeld app wanneer het token een token is dat alleen voor apps geldt.

De web-app registreren

Als u wilt dat uw toepassing gebruikers kan aanmelden met Microsoft Entra, moet Microsoft Entra Externe ID op de hoogte worden gesteld van de toepassing die u maakt. De app-registratie brengt een vertrouwensrelatie tot stand tussen de app en Microsoft Entra. Wanneer u een toepassing registreert, genereert externe id een unieke id die bekend staat als een toepassings-id (client), een waarde die wordt gebruikt om uw app te identificeren bij het maken van verificatieaanvragen.

De volgende stappen laten zien hoe u uw app registreert in het Microsoft Entra-beheercentrum:

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

  3. Blader naar identiteitstoepassingen>> App-registraties.

  4. Selecteer + Nieuwe registratie.

  5. Op de pagina Een toepassing registreren die wordt weergegeven;

    1. Voer een betekenisvolle toepassingsnaam in die wordt weergegeven aan gebruikers van de app, bijvoorbeeld ciam-client-app.
    2. Onder Ondersteunde accounttypen selecteert u Enkel accounts in deze organisatieadreslijst.

  6. Selecteer Registreren.

  7. Het deelvenster Overzicht van de toepassing wordt weergegeven bij een geslaagde registratie. Noteer de toepassings-id (client) die moet worden gebruikt in de broncode van uw toepassing.

Voer de volgende stappen uit om uw app-type op te geven voor uw app-registratie:

  1. Selecteer Verificatie onder Beheren.
  2. Selecteer op de pagina Platformconfiguraties de optie Een platform toevoegen en selecteer vervolgens de optie Web.
  3. Voer voor de omleidings-URI's in http://localhost:3000/auth/redirect.
  4. Selecteer Configureren om uw wijzigingen op te slaan.

Een clientgeheim maken

Maak vervolgens een clientgeheim voor de geregistreerde toepassing. De toepassing gebruikt het clientgeheim om de identiteit te bewijzen wanneer er tokens worden aangevraagd.

  1. Selecteer op de pagina App-registraties de toepassing die u hebt gemaakt (zoals ciam-client-app) om de overzichtspagina te openen.
  2. Selecteer onder Beheren de optie Certificaten en geheimen.
  3. Selecteer Nieuw clientgeheim.
  4. Voer in het vak Beschrijving een beschrijving in voor het clientgeheim (bijvoorbeeld ciam-app-clientgeheim).
  5. Selecteer onder Verlopen een duur waarvoor het geheim geldig is (volgens de beveiligingsregels van uw organisatie) en selecteer vervolgens Toevoegen.
  6. Noteer de Waarde van het geheim. U gebruikt deze waarde voor configuratie in een latere stap. De geheime waarde wordt niet opnieuw weergegeven en kan op geen enkele manier worden opgehaald nadat u weg navigeert van de certificaten en geheimen. Zorg ervoor dat u deze opneemt.

API-machtigingen verlenen aan de web-app

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

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

  2. Selecteer onder Beheren de optie API-machtigingen.

  3. Selecteer onder Geconfigureerde machtigingen de optie Een machtiging toevoegen.

  4. Selecteer de API's die door mijn organisatie worden gebruikt .

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

  6. Selecteer de optie Gedelegeerde machtigingen .

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

  8. Selecteer de knop Toestemmingen 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 Vernieuwen en controleer vervolgens of Verleend voor <uw tenantnaam> wordt weergegeven onder Status voor beide bereiken.

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

Een gebruikersstroom maken

Volg deze stappen om een gebruikersstroom te maken die een klant kan gebruiken om zich aan te melden of zich te registreren voor een toepassing.

  1. Meld u aan bij het Microsoft Entra-beheercentrum als ten minste een beheerder van de gebruikersstroom voor externe id's.

  2. Als u toegang hebt tot meerdere tenants, gebruikt u het pictogram Instellingen in het bovenste menu om vanuit het menu Mappen en abonnementen over te schakelen naar uw externe tenant.

  3. Blader naar gebruikersstromen> voor externe identiteiten.>

  4. Selecteer + Nieuwe gebruikersstroom.

  5. Op de pagina Maken :

    1. Voer een naam in voor de gebruikersstroom, zoals SignInSignUpSample.

    2. Selecteer E-mailaccounts in de lijst met id-providers. Met deze id-provider kunnen gebruikers zich aanmelden of registreren met hun e-mailadres.

      Notitie

      Aanvullende id-providers worden hier alleen vermeld nadat u federatie met hen hebt ingesteld. Als u bijvoorbeeld federatie met Google of Facebook instelt, kunt u deze extra id-providers hier selecteren.

    3. Onder E-mailaccounts kunt u een van de twee opties selecteren. Voor deze zelfstudie selecteert u E-mail met wachtwoord.

      • E-mail met wachtwoord: hiermee kunnen nieuwe gebruikers zich registreren en aanmelden met een e-mailadres als de aanmeldingsnaam en een wachtwoord als hun eerste factorreferentie.
      • Eenmalige wachtwoordcode per e-mail verzenden: hiermee kunnen nieuwe gebruikers zich registreren en aanmelden met behulp van een e-mailadres als de aanmeldingsnaam en eenmalige wachtwoordcode per e-mail als hun eerste factorreferentie. Wachtwoordcode voor eenmalige e-mail moet zijn ingeschakeld op tenantniveau (Alle id-providers>voor eenmalige wachtwoordcode) om deze optie beschikbaar te maken op gebruikersstroomniveau.

    4. Kies onder Gebruikerskenmerken de kenmerken die u wilt verzamelen van de gebruiker bij het aanmelden. Als u Meer weergeven selecteert, kunt u kenmerken en claims kiezen voor land/regio, weergavenaam en postcode. Selecteer OK. (Gebruikers worden alleen om kenmerken gevraagd wanneer ze zich voor het eerst registreren.)

  6. Selecteer Maken. De nieuwe gebruikersstroom wordt weergegeven in de lijst gebruikersstromen . Vernieuw de pagina indien nodig.

Als u selfservice voor wachtwoordherstel wilt inschakelen, gebruikt u de stappen in het artikel Selfservice voor wachtwoordherstel inschakelen.

Webtoepassing koppelen aan de gebruikersstroom

Hoewel veel toepassingen aan uw gebruikersstroom kunnen worden gekoppeld, kan één toepassing slechts worden gekoppeld aan één gebruikersstroom. Met een gebruikersstroom kan de gebruikerservaring voor specifieke toepassingen worden geconfigureerd. U kunt bijvoorbeeld een gebruikersstroom configureren waarvoor gebruikers zich moeten aanmelden of zich moeten aanmelden met een e-mailadres.

  1. Selecteer Identiteit in het zijbalkmenu.

  2. Selecteer Externe identiteiten en vervolgens Gebruikersstromen.

  3. Selecteer op de pagina Gebruikersstromen de naam van de gebruikersstroom die u eerder hebt gemaakt, bijvoorbeeld SignInSignUpSample.

  4. Selecteer Toepassingen onder Gebruiken.

  5. Selecteer Toepassing toevoegen.

  6. Selecteer de toepassing in de lijst, zoals ciam-client-app of gebruik het zoekvak om de toepassing te zoeken en selecteer deze.

  7. Kies Selecteren.

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 het voorbeeld van de clientweb-app:

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

  2. Zoek de tijdelijke aanduiding:

    • Enter_the_Application_Id_Here en vervang deze door de toepassings-id (client) van de app die u eerder hebt geregistreerd.
    • Enter_the_Tenant_Subdomain_Here en vervang het door het subdomein Directory (tenant). Als uw primaire tenantdomein bijvoorbeeld is contoso.onmicrosoft.com, gebruikt u contoso. Als u uw tenantnaam niet hebt, leest u de details van uw tenant.
    • Enter_the_Client_Secret_Here en vervang deze door de app-geheime waarde 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.

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

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

  2. Zoek de tijdelijke aanduiding:

    • Enter_the_Application_Id_Here en vervang deze door de toepassings-id (client) van de web-API die u hebt gekopieerd.
    • Enter_the_Tenant_Id_Here en vervang deze door de map-id (tenant) die u eerder hebt gekopieerd.
    • Enter_the_Tenant_Subdomain_Here en vervang het door het subdomein Directory (tenant). Als uw primaire tenantdomein bijvoorbeeld is contoso.onmicrosoft.com, gebruikt u contoso. Als u uw tenantnaam niet hebt, leest u de details van uw tenant.

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 start

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

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

    Schermopname van aanmelden bij een knooppuntweb-app.

  5. Typ uw e-mailadres op de aanmeldingspagina, selecteer Volgende, typ uw wachtwoord en selecteer Vervolgens 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.

    Schermopname van aanmelden bij een knooppuntweb-app en een API aanroepen.

API aanroepen

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

    Schermopname van het bewerken van api voor takenlijst.

  2. Bewerk de takenlijst 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. Als u bijvoorbeeld een taak wilt lezen, moet de clientweb-app een toegangstoken met ToDoList.Read machtiging/bereik verkrijgen.

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

Gerelateerde inhoud