Een API aanroepen in een voorbeeld-Node.js daemontoepassing

  • Artikel

In dit artikel wordt een voorbeeld Node.js daemontoepassing gebruikt om te laten zien hoe een daemon-app een token verkrijgt om een web-API aan te roepen. Microsoft Entra-id voor klanten beveiligt de web-API.

Een daemontoepassing verkrijgt een token namens zichzelf (niet namens een gebruiker). Gebruikers kunnen geen interactie hebben met een daemontoepassing omdat deze een eigen identiteit vereist. Dit type toepassing vraagt een toegangstoken aan met behulp van de toepassings-id en het presenteren van de toepassings-id, referenties (wachtwoord of certificaat) en toepassings-id-URI aan externe id.

Een daemon-app maakt gebruik van de standaardtoekenning van OAuth 2.0-clientreferenties. Het voorbeeld dat we in dit artikel gebruiken, maakt gebruik van Microsoft Authentication Library for Node (MSAL Node) om het proces voor het verkrijgen van het token te vereenvoudigen.

Vereisten

Een daemontoepassing en een web-API registreren

In deze stap maakt u de daemon- 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 toepassingsontwikkelaar.

  2. Als u toegang hebt tot meerdere tenants, gebruikt u het filter Mappen en abonnementen in het bovenste menu om over te schakelen naar de tenant van uw klant.

  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 voor 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 moeten worden gebruikt in de broncode van uw toepassing.

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 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 bijbehorende overzichtspagina te openen.

  2. Selecteer onder Beherende optie App-rollen.

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

    Eigenschap Waarde
    Weergavenaam ToDoList.Read.All
    De toegestane ledentypen Toepassingen
    Waarde ToDoList.Read.All
    Description Toestaan dat de app de takenlijst van elke gebruiker kan lezen met behulp van de 'TodoListApi'

  4. Selecteer nogmaals App-rol maken , voer 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
    De toegestane ledentypen Toepassingen
    Waarde ToDoList.ReadWrite.All
    Description Toestaan dat de app de Takenlijst van elke gebruiker kan lezen en schrijven met behulp van de 'ToDoListApi'

Optionele claims configureren

Tokens die door Microsoft Identity worden geretourneerd, worden kleiner gehouden om optimale prestaties te garanderen door clients die ze aanvragen. Als gevolg hiervan zijn verschillende claims niet meer standaard aanwezig in het token en moeten er specifiek per toepassing om worden gevraagd. Voor deze app neemt u optionele idtyp-claim op om de web-API te helpen bepalen of een token een app-token of een app+gebruiker-token is. Hoewel een combinatie van scp - en rollenclaims voor hetzelfde doel kan worden gebruikt, is het gebruik van de idtyp-claim de eenvoudigste manier om een app-token en een app+user-token van elkaar te onderscheiden. De waarde van deze claim is bijvoorbeeld app wanneer het token een token is dat alleen een app-token is.

Gebruik de volgende stappen om de optionele idtyp-claim te configureren:

  1. Selecteer onder Beheren de optie Tokenconfiguratie.

  2. Selecteer Optionele claim toevoegen.

  3. Kies onder Tokentypede optie Toegang.

  4. Selecteer het optionele claim-idtyp.

  5. Selecteer Toevoegen om uw wijzigingen op te slaan.

De daemon-app registreren

Als u wilt dat uw toepassing gebruikers kan aanmelden met Microsoft Entra, moet Microsoft Entra-id voor klanten 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 een toepassings-id (client-id) wordt genoemd, een waarde die wordt gebruikt om uw app te identificeren bij het maken van verificatieaanvragen.

In de volgende stappen ziet u hoe u uw app registreert in het Microsoft Entra-beheercentrum:

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

  2. Als u toegang hebt tot meerdere tenants, gebruikt u het filter Mappen en abonnementen in het bovenste menu om over te schakelen naar de tenant van uw klant.

  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 wanneer de registratie is geslaagd. Noteer de toepassings-id (client) die moet worden gebruikt in de broncode van uw toepassing.

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 pagina Overzicht 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 clientgeheim van ciam-app).
  5. Selecteer onder Verloopt 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.

Notitie

De geheime waarde wordt niet meer weergegeven en kan op geen enkele manier worden opgehaald nadat u de pagina Certificaten en geheimen hebt verwijderd. Zorg er dus voor dat u de waarde opneemt.
Voor een betere beveiliging kunt u overwegen certificaten te gebruiken in plaats van clientgeheimen.

API-machtigingen verlenen aan de daemon-app

  1. Selecteer op de pagina App-registraties de toepassing die u hebt gemaakt, zoals ciam-client-app.

  2. Selecteer onder Beheren de optie API-machtigingen.

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

  4. Selecteer het tabblad Mijn API's.

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

  6. Selecteer de optie Toepassingsmachtigingen . We selecteren deze optie als de app zich aanmeldt als zichzelf, niet als gebruikers.

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

  8. Selecteer de knop Toestemmingen toevoegen.

  9. Op dit moment hebt u de machtigingen correct toegewezen. Omdat de daemon-app echter niet toestaat dat gebruikers ermee werken, kunnen de gebruikers zelf geen toestemming geven voor deze machtigingen. Als u dit probleem wilt oplossen, 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 machtigingen.

Voorbeeld daemontoepassing en web-API klonen of downloaden

Als u de voorbeeldcode van de web-app wilt ophalen, kunt u een van de volgende taken uitvoeren:

  • Download het .zip-bestand of kloon de voorbeeldwebtoepassing vanuit GitHub door de volgende opdracht uit te voeren:

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

Als u ervoor kiest om het .zip-bestand te downloaden, extraheert u het voorbeeld-app-bestand naar een map waarin de totale lengte van het pad 260 tekens of minder is.

Projectafhankelijkheden installeren

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

        cd 2-Authorization\3-call-api-node-daemon\App

  2. Voer de volgende opdrachten uit om de vereiste app-afhankelijkheden te installeren:

        npm install && npm update

De voorbeeld-daemon-app en API configureren

Ga als volgende te werk om uw app-registratie te 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 daemon-app die u eerder hebt geregistreerd.

    • Enter_the_Tenant_Subdomain_Here en vervang dit door het subdomein Map (tenant). Als het primaire domein van uw tenant bijvoorbeeld is contoso.onmicrosoft.com, gebruikt u contoso. Als u de naam van uw tenant niet hebt, leest u hoe u uw tenantgegevens kunt lezen.

    • Enter_the_Client_Secret_Here en vervang deze door de waarde voor het geheim van de daemon-app 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 voorbeeld van de web-API:

  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 dit door het subdomein Map (tenant). Als het primaire domein van uw tenant bijvoorbeeld is contoso.onmicrosoft.com, gebruikt u contoso. Als u de naam van uw tenant niet hebt, leest u hoe u uw tenantgegevens kunt lezen.

Voorbeeld daemon-app en API uitvoeren en testen

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

    cd 2-Authorization\3-call-api-node-daemon\API\ToDoListAPI
dotnet run

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

        2-Authorization\3-call-api-node-daemon\App
     node . --op getToDos

Als uw daemon-app en web-API zijn uitgevoerd, ziet u iets dat lijkt op de volgende JSON-matrix in het consolevenster

{
    id: 1,
    owner: '3e8....-db63-43a2-a767-5d7db...',
    description: 'Pick up grocery'
},
{
    id: 2,
    owner: 'c3cc....-c4ec-4531-a197-cb919ed.....',
    description: 'Finish invoice report'
},
{
    id: 3,
    owner: 'a35e....-3b8a-4632-8c4f-ffb840d.....',
    description: 'Water plants'
}

Uitleg

De Node.js-app gebruikt OAuth 2.0-clientreferenties voor het verkrijgen van een toegangstoken voor zichzelf en niet voor de gebruiker. Het toegangstoken dat door de app wordt aangevraagd, bevat de machtigingen die worden weergegeven als rollen. De clientreferentiestroom gebruikt deze set machtigingen in plaats van gebruikersbereiken voor toepassingstokens. U hebt deze toepassingsmachtigingen eerder beschikbaar gemaakt in de web-API en ze vervolgens verleend aan de daemon-app.

Aan de API-zijde moet de web-API controleren of het toegangstoken de vereiste machtigingen (toepassingsmachtigingen) heeft. De web-API kan geen toegangstoken accepteren dat niet over de vereiste machtigingen beschikt.

Toegang tot gegevens

Een web-API-eindpunt moet worden voorbereid om aanroepen van zowel gebruikers als toepassingen te accepteren. Daarom moet het een manier hebben om op elke aanvraag dienovereenkomstig te reageren. Een aanroep van een gebruiker via gedelegeerde machtigingen/bereiken ontvangt bijvoorbeeld de takenlijst van de gebruiker. Aan de andere kant kan een aanroep vanuit een toepassing via toepassingsmachtigingen/rollen de volledige takenlijst ontvangen. In dit artikel doen we echter alleen een toepassingsaanroep, zodat we geen gedelegeerde machtigingen/bereiken hoeven te configureren.

Volgende stappen