Share via


Quickstart: Een web-API aanroepen in een voorbeeld-daemon-app

In deze quickstart gebruikt u een voorbeeld-daemon-toepassing om een toegangstoken te verkrijgen en een beveiligde web-API aan te roepen met behulp van de MSAL-(Microsoft Authentication Library).

Voordat u begint, gebruikt u de Kies een tenanttype selector boven aan deze pagina om het tenanttype te selecteren. Microsoft Entra ID biedt twee tenantconfiguraties, werknemers en externe. Een tenantconfiguratie voor werknemers is bedoeld voor uw werknemers, interne apps en andere organisatieresources. Een externe tenant is bedoeld voor uw klantgerichte apps.

De voorbeeld-app die u in deze quickstart gebruikt, verkrijgt een toegangstoken om Microsoft Graph API aan te roepen.

Voorwaarden

  • Een Azure-account met een actief abonnement. Als u er nog geen hebt, maak gratis een account aan.
  • Dit Azure-account moet machtigingen hebben voor het beheren van toepassingen. Een van de volgende Microsoft Entra-rollen omvat de vereiste machtigingen:
    • Toepassingsbeheerder
    • Toepassingsontwikkelaar
    • Cloudtoepassingsbeheerder
  • Een personeelstenant. U kunt uw standaarddirectory gebruiken of een nieuwe tenant aanmaken.
  • Registreer een nieuwe app in het Microsoft Entra-beheercentrum met de volgende configuratie. Zie Een toepassing registrerenvoor meer informatie.
    • naam: identity-client-daemon-app
    • Ondersteunde accounttypen: accounts in deze organisatiemap (alleen één tenant)

Een clientgeheim maken

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

  1. Selecteer vanaf de pagina App-registraties de toepassing die u hebt gemaakt (bijvoorbeeld webapp-clientgeheim) om de pagina Overzicht te openen.
  2. Selecteer onder BeherenCertificaten & geheimen>Clientgeheimen>Nieuw clientgeheim.
  3. Voer in het vak Beschrijving een beschrijving in voor het clientgeheim (bijvoorbeeld clientgeheim van de web-app).
  4. Selecteer onder verloopteen periode waarin het geheim geldig is (volgens de beveiligingsregels van uw organisatie) en selecteer vervolgens Toevoegen.
  5. 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.

Wanneer u toegangsgegevens aanmaakt voor een vertrouwelijke clientoepassing:

  • Microsoft raadt u aan een certificaat te gebruiken in plaats van een clientgeheim voordat u de toepassing naar een productieomgeving verplaatst. Zie voor meer informatie over het gebruik van een certificaat instructies in verificatiecertificaatreferenties voor microsoft-identiteitsplatformtoepassingen.

  • Voor testdoeleinden kunt u een zelfondertekend certificaat maken en uw apps configureren om ermee te verifiëren. in productie-moet u echter een certificaat kopen dat is ondertekend door een bekende certificeringsinstantie en vervolgens Azure Key Vault- gebruiken om de toegang tot certificaten en levensduur te beheren.

API-machtigingen verlenen aan de daemon-app

Voor daemon-app voor toegang tot gegevens in Microsoft Graph API verleent u deze de benodigde machtigingen. De daemon-app heeft machtigingen voor toepassingstypen nodig. Gebruikers kunnen geen interactie hebben met een daemon-toepassing, dus de tenantbeheerder moet toestemming geven voor deze machtigingen. Gebruik de volgende stappen om de machtigingen te verlenen en toestemming te geven:

Voor de .NET-demon-app hoeft u geen toestemming te verlenen of goedkeuring te geven. Deze daemon-app leest zijn eigen app-registratiegegevens, zodat deze dit kan doen zonder dat hiervoor toepassingsmachtigingen zijn verleend.

De voorbeeldtoepassing 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-docs-code-dotnet.git

Het project configureren

Als u uw app-registratiegegevens wilt gebruiken in het voorbeeld van de client-daemon-app, gebruikt u de volgende stappen:

  1. Open een consolevenster en navigeer vervolgens naar de map ms-identity-docs-code-dotnet/console-daemon:

    cd ms-identity-docs-code-dotnet/console-daemon
    
  2. Open Program.cs en vervang de bestandsinhoud door het volgende codefragment;

     // Full directory URL, in the form of https://login.microsoftonline.com/<tenant_id>
     Authority = " https://login.microsoftonline.com/Enter_the_tenant_ID_obtained_from_the_Microsoft_Entra_admin_center",
     // 'Enter the client ID obtained from the Microsoft Entra admin center
     ClientId = "Enter the client ID obtained from the Microsoft Entra admin center",
     // Client secret 'Value' (not its ID) from 'Client secrets' in the Microsoft Entra admin center
     ClientSecret = "Enter the client secret value obtained from the Mifcrosoft Entra admin center",
     // Client 'Object ID' of app registration in Microsoft Entra admin center - this value is a GUID
     ClientObjectId = "Enter the client Object ID obtained from the Microsoft Entra admin center"
    
    • Authority: De instantie is een URL die een map aangeeft waar MSAL tokens kan aanvragen. Vervang Enter_the_tenant_ID_obtained_from_the_Microsoft_Entra_admin_center door de waarde van de Directory-id (tenant) die eerder is vastgelegd.
    • ClientId : de id van de toepassing, ook wel de client genoemd. Vervang de tekst tussen aanhalingstekens door de Application (client) ID waarde die eerder is vastgelegd op de overzichtspagina van de geregistreerde toepassing.
    • ClientSecret: het clientgeheim dat is gemaakt voor de toepassing in het Microsoft Entra-beheercentrum. Voer de waarde in van het clientgeheim.
    • ClientObjectId : de object-id van de clienttoepassing. Vervang de tekst tussen aanhalingstekens door de Object ID waarde die u eerder hebt genoteerd op de overzichtspagina van de geregistreerde toepassing.

De toepassing uitvoeren en testen

U hebt uw voorbeeld-app geconfigureerd. U kunt doorgaan met uitvoeren en testen.

Voer vanuit het consolevenster de volgende opdracht uit om de toepassing te bouwen en uit te voeren:

dotnet run

Zodra de toepassing is uitgevoerd, wordt er een antwoord weergegeven dat vergelijkbaar is met het volgende fragment (ingekort voor kortheid):

{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications/$entity",
"id": "00001111-aaaa-2222-bbbb-3333cccc4444",
"deletedDateTime": null,
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"applicationTemplateId": null,
"disabledByMicrosoftStatus": null,
"createdDateTime": "2021-01-17T15:30:55Z",
"displayName": "identity-dotnet-console-app",
"description": null,
"groupMembershipClaims": null,
...
}

Hoe het werkt

Een daemon-toepassing verkrijgt een token namens zichzelf (niet namens een gebruiker). Gebruikers kunnen geen interactie hebben met een daemon-toepassing, omdat hiervoor een eigen identiteit is vereist. Dit type toepassing vraagt een toegangstoken aan met behulp van de toepassings-id door de toepassings-id, referentie (geheim of certificaat) en een URI voor de toepassings-id weer te geven. De daemon-toepassing maakt gebruik van de standaard-OAuth 2.0-clientreferenties toekenningsstroom om een toegangstoken te verkrijgen.

De app verkrijgt een toegangstoken van het Microsoft Identity Platform. Het toegangstoken is gericht op de Microsoft Graph API. De app gebruikt vervolgens het toegangstoken om zijn eigen toepassingsregistratiegegevens aan te vragen bij Microsoft Graph API. De app kan elke resource aanvragen bij Microsoft Graph API zolang het toegangstoken over de juiste machtigingen beschikt.

In het voorbeeld ziet u hoe een taak zonder toezicht of Windows-service kan worden uitgevoerd met een toepassingsidentiteit in plaats van de identiteit van een gebruiker.

Voorwaarden

  • Een Azure-account met een actief abonnement. Als u er nog geen hebt, maak gratis een account aan.
  • Dit Azure-account moet machtigingen hebben voor het beheren van toepassingen. Een van de volgende Microsoft Entra-rollen omvat de vereiste machtigingen:
    • Toepassingsbeheerder
    • Toepassingsontwikkelaar
    • Cloudtoepassingsbeheerder
  • Een externe tenant. Kies een van de volgende methoden om er een te maken:
  • Registreer een nieuwe app in het Microsoft Entra-beheercentrum met de volgende configuratie. Zie Een toepassing registrerenvoor meer informatie.
    • naam: ciam-daemon-app
    • Ondersteunde accounttypen: accounts in deze organisatiemap (alleen één tenant)
  • Visual Studio Code of een andere code-editor.
  • .NET 7.0 of hoger.
  • Node.js (alleen voor implementatie van knooppunten)

Een clientgeheim maken

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

  1. Selecteer vanaf de pagina App-registraties de toepassing die u hebt gemaakt (bijvoorbeeld webapp-clientgeheim) om de pagina Overzicht te openen.
  2. Selecteer onder BeherenCertificaten & geheimen>Clientgeheimen>Nieuw clientgeheim.
  3. Voer in het vak Beschrijving een beschrijving in voor het clientgeheim (bijvoorbeeld clientgeheim van de web-app).
  4. Selecteer onder verloopteen periode waarin het geheim geldig is (volgens de beveiligingsregels van uw organisatie) en selecteer vervolgens Toevoegen.
  5. 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.

Wanneer u toegangsgegevens aanmaakt voor een vertrouwelijke clientoepassing:

  • Microsoft raadt u aan een certificaat te gebruiken in plaats van een clientgeheim voordat u de toepassing naar een productieomgeving verplaatst. Zie voor meer informatie over het gebruik van een certificaat instructies in verificatiecertificaatreferenties voor microsoft-identiteitsplatformtoepassingen.

  • Voor testdoeleinden kunt u een zelfondertekend certificaat maken en uw apps configureren om ermee te verifiëren. in productie-moet u echter een certificaat kopen dat is ondertekend door een bekende certificeringsinstantie en vervolgens Azure Key Vault- gebruiken om de toegang tot certificaten en levensduur te beheren.

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 BeherenAPI-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 toepassingsmachtigingen optie. We selecteren deze optie als de app zich aanmeldt als zichzelf, maar niet namens een gebruiker.

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

  8. Selecteer de knop Machtigingen 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. 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 of Verleend voor <uw tenantnaam> wordt weergegeven onder Status voor beide machtigingen.

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

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

    Eigendom 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:

    Eigendom 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 instellen

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 idtyp claim de eenvoudigste manier om een app-token en een app + gebruikerstoken te onderscheiden. De waarde van deze claim is bijvoorbeeld app wanneer het token een alleen-app-token is.

Klonen of downloaden van voorbeeld-daemontoepassing en web-API

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
    
  • U kunt ook het voorbeeldbestand .zip downloadenen dit vervolgens uitpakken naar een bestandspad met een naamlengte van minder dan 260 tekens.

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 app-afhankelijkheden te installeren:

    npm install && npm update
    

De voorbeeld-daemon-app en API configureren

Als u uw app-registratiegegevens wilt gebruiken in het voorbeeld van de clientweb-app, gebruikt u de volgende stappen:

  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 daemon-app die u eerder hebt geregistreerd.

    • 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 huurdersnaam niet hebt, leert u hoe u uw huurdergegevens kunt lezen.

    • Enter_the_Client_Secret_Here en vervang deze door de geheime waarde 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 web-API-voorbeeld:

  1. Open API\ToDoListAPI\appsettings.json 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 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 huurdersnaam niet hebt, leert u hoe u uw huurdergegevens kunt lezen.

Voorbeeld-daemon-app en API uitvoeren en testen

U hebt uw voorbeeld-app geconfigureerd. U kunt doorgaan met uitvoeren en testen.

  1. Open een consolevenster en voer vervolgens 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 vergelijkbaars met 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"
}

Hoe het werkt

De Node.js-app gebruikt de OAuth 2.0 client credentials grant flow om een toegangstoken voor eigen gebruik en niet voor de gebruiker te verkrijgen. 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 deze toepassingsmachtigingen eerder in de web-API beschikbaar gemaakt en deze vervolgens verleend aan de daemon-app.

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

Toegang tot gegevens

Een web-API-eindpunt moet worden voorbereid op het accepteren van aanroepen van zowel gebruikers als toepassingen. Daarom moet het een manier hebben om te reageren op elke aanvraag dienovereenkomstig. Een aanroep van een gebruiker via gedelegeerde machtigingen/scopes ontvangt bijvoorbeeld de gebruikersgegevenslijst to-do. Aan de andere kant kan een aanroep van een toepassing via toepassingsmachtigingen/rollen de hele to-do lijst ontvangen. In dit artikel maken we echter alleen een aanroep van een toepassing, dus we hoeven gedelegeerde machtigingen/bereiken niet te configureren.