Share via

Een API aanroepen in een .NET-voorbeeld-daemon-toepassing

  • Artikel

In deze handleiding wordt een voorbeeldtoepassing voor .NET-daemon gebruikt om te laten zien hoe een daemon-toepassing een token verkrijgt om een beveiligde web-API aan te roepen. Microsoft Entra beveiligt de web-API.

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 en de bijbehorende toepassings-id, referentie (wachtwoord of certificaat) en toepassings-id-URI voor Microsoft Entra Externe ID.

Vereisten

Een daemon-toepassing en een web-API registreren

In deze stap maakt u de daemon en de registraties van de web-API-toepassing 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.

Toepassingsrollen 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 daemon-toepassing 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.

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 daemon-toepassing

  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 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 Toepassingsmachtigingen . We selecteren deze optie als de app zich aanmeldt als zichzelf, niet voor gebruikers.

  7. Selecteer In de lijst met machtigingen todoList.Read.All, ToDoList.ReadWrite.All (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. 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 machtigingen.

Voorbeeld-daemontoepassing 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-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 voorbeeld-daemon-toepassing en -API configureren

Uw app-registratie gebruiken in het voorbeeld van de clientwebtoepassing:

  1. Open in de code-editor ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListClient/appsettings.json-bestand .

  2. Zoek de tijdelijke aanduiding:

    • Enter_the_Application_Id_Here en vervang deze door de toepassings-id (client) van de daemon-toepassing 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 geheime waarde van de daemon-toepassing 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 in de code-editor ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI/appsettings.json-bestand .

  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.

Voorbeeld-daemon-toepassing 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\3-call-own-api-dotnet-core-daemon\ToDoListAPI
dotnet run

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

    cd 2-Authorization\3-call-own-api-dotnet-core-daemon\ToDoListClient
dotnet run

Als uw daemon-toepassing en web-API zijn uitgevoerd, ziet u iets vergelijkbaars met de volgende JSON-matrix in het consolevenster:

Posting a to-do...
Retrieving to-do's from server...
To-do data:
ID: 1
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Bake bread
Posting a second to-do...
Retrieving to-do's from server...
To-do data:
ID: 1
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Bake bread
ID: 2
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Butter bread
Deleting a to-do...
Retrieving to-do's from server...
To-do data:
ID: 2
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Butter bread
Editing a to-do...
Retrieving to-do's from server...
To-do data:
ID: 2
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Eat bread
Deleting remaining to-do...
Retrieving to-do's from server...
There are no to-do's in server

Hoe het werkt

De daemon-toepassing gebruikt OAuth2.0-clientreferenties om een toegangstoken voor zichzelf te verkrijgen 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 in de web-API weergegeven en deze vervolgens aan de daemon-app verleend. De daemon-app in dit artikel maakt gebruik van Microsoft Authentication Library voor .NET om het proces van het verkrijgen van een token te vereenvoudigen.

Aan de API-zijde moet de web-API controleren of het toegangstoken over de vereiste machtigingen (toepassingsmachtigingen) beschikt. De web-API weigert toegangstokens die niet over de vereiste machtigingen beschikken.

Gerelateerde inhoud