Anropa ett API i ett exempel på Node.js daemon-program

  • Artikel

Den här artikeln använder ett exempel på Node.js daemon-program för att visa hur en daemonapp hämtar en token för att anropa ett webb-API. Microsoft Entra-ID för kunder skyddar webb-API:et.

Ett daemonprogram hämtar en token för sig själv (inte för en användares räkning). Användare kan inte interagera med ett daemonprogram eftersom det kräver en egen identitet. Den här typen av program begär en åtkomsttoken med hjälp av dess programidentitet och presenterar dess program-ID, autentiseringsuppgifter (lösenord eller certifikat) och program-ID-URI till externt ID.

En daemonapp använder OAuth 2.0-klientens standardautentiseringsuppgifter. För att förenkla processen med att hämta token använder exemplet som vi använder i den här artikeln Microsoft Authentication Library for Node (MSAL Node).

Förutsättningar

Registrera ett daemonprogram och ett webb-API

I det här steget skapar du daemon- och webb-API-programregistreringarna och anger omfången för webb-API:et.

Registrera ett webb-API-program

  1. Logga in på Microsoft Entra administrationscenter som minst en programutvecklare.

  2. Om du har åtkomst till flera klienter använder du filtret Kataloger + prenumerationer på den översta menyn för att växla till din kundklientorganisation.

  3. Bläddra till Identitetsprogram>>Appregistreringar.

  4. Välj + Ny registrering.

  5. På sidan Registrera ett program som visas anger du ditt programs registreringsinformation:

    1. I avsnittet Namn anger du ett beskrivande programnamn som ska visas för appens användare, till exempel ciam-ToDoList-api.

    2. Under Kontotyper som stöds väljer du Endast konton i den här organisationskatalogen.

  6. Välj Registrera för att skapa programmet.

  7. Programmets översiktsfönster visas när registreringen är klar. Registrera katalog-ID:t (klient)-ID :t och program-ID:t (klient) som ska användas i programmets källkod.

Konfigurera approller

Ett API måste publicera minst en approll för program, även kallat Programbehörighet, för att klientapparna ska få en åtkomsttoken som sig själva. Programbehörigheter är den typ av behörigheter som API:er bör publicera när de vill göra det möjligt för klientprogram att autentisera sig själva och inte behöver logga in användare. Följ dessa steg för att publicera en programbehörighet:

  1. På sidan Appregistreringar väljer du det program som du skapade (till exempel ciam-ToDoList-api) för att öppna sidan Översikt.

  2. Under Hantera väljer du Approller.

  3. Välj Skapa approll och ange sedan följande värden och välj sedan Använd för att spara ändringarna:

    Egenskap Värde
    Visningsnamn ToDoList.Read.All
    Tillåtna medlemstyper Program
    Värde ToDoList.Read.All
    Description Tillåt att appen läser alla användares ToDo-lista med hjälp av TodoListApi

  4. Välj Skapa approll igen och ange sedan följande värden för den andra approllen och välj sedan Använd för att spara ändringarna:

    Egenskap Värde
    Visningsnamn ToDoList.ReadWrite.All
    Tillåtna medlemstyper Program
    Värde ToDoList.ReadWrite.All
    Description Tillåt att appen läser och skriver varje användares ToDo-lista med hjälp av ToDoListApi

Konfigurera valfria anspråk

Token som returneras av Microsoft-identiteten hålls mindre för att säkerställa optimal prestanda för klienter som begär dem. Därför finns flera anspråk inte längre i token som standard och måste efterfrågas specifikt per program. För den här appen inkluderar du valfritt idtyp-anspråk för att hjälpa webb-API:et att avgöra om en token är en apptoken eller en app+användartoken. Även om en kombination av scp - och rollanspråk kan användas för samma ändamål är användningen av idtyp-anspråket det enklaste sättet att skilja en apptoken och en app+användartoken åt. Värdet för det här anspråket är till exempel app när token är en appspecifik token.

Använd följande steg för att konfigurera valfritt idtyp-anspråk :

  1. Under Hantera väljer du Tokenkonfiguration.

  2. Välj Lägg till valfritt anspråk.

  3. Under Tokentyp väljer du Åtkomst.

  4. Välj den valfria anspråks-idtyp.

  5. Välj Lägg till för att spara dina ändringar.

Registrera daemonappen

För att programmet ska kunna logga in användare med Microsoft Entra måste Microsoft Entra-ID för kunder göras medvetet om det program som du skapar. Appregistreringen upprättar en förtroenderelation mellan appen och Microsoft Entra. När du registrerar ett program genererar externt ID en unik identifierare som kallas ett program-ID (klient)-ID, ett värde som används för att identifiera din app när du skapar autentiseringsbegäranden.

Följande steg visar hur du registrerar din app i Microsoft Entra administrationscenter:

  1. Logga in på Microsoft Entra administrationscenter som minst en programutvecklare.

  2. Om du har åtkomst till flera klienter använder du filtret Kataloger + prenumerationer på den översta menyn för att växla till din kundklientorganisation.

  3. Bläddra till Identitetsprogram>>Appregistreringar.

  4. Välj + Ny registrering.

  5. På sidan Registrera ett program som visas;

    1. Ange ett beskrivande programnamn som visas för appens användare, till exempel ciam-client-app.
    2. Under Kontotyper som stöds väljer du Endast konton i den här organisationskatalogen.

  6. Välj Register (Registrera).

  7. Programmets översiktsfönster visas vid lyckad registrering. Registrera det program-ID (klient)-ID som ska användas i programmets källkod.

Skapa en klienthemlighet

Skapa en klienthemlighet för det registrerade programmet. Programmet använder klienthemligheten för att bevisa sin identitet när den begär token.

  1. På sidan Appregistreringar väljer du det program som du skapade (till exempel ciam-client-app) för att öppna sidan Översikt.
  2. Under Hantera väljer du Certifikathemligheter&.
  3. Välj Ny klienthemlighet.
  4. I rutan Beskrivning anger du en beskrivning av klienthemligheten (till exempel ciam-appklienthemlighet).
  5. Under Upphör att gälla väljer du en varaktighet för vilken hemligheten är giltig (enligt organisationens säkerhetsregler) och väljer sedan Lägg till.
  6. Registrera hemlighetens värde. Du använder det här värdet för konfiguration i ett senare steg.

Anteckning

Det hemliga värdet visas inte igen och kan inte hämtas på något sätt när du har navigerat bort från sidan Certifikat och hemligheter , så se till att du registrerar det.
För förbättrad säkerhet bör du överväga att använda certifikat i stället för klienthemligheter.

Bevilja API-behörigheter till daemonappen

  1. På sidan Appregistreringar väljer du det program som du skapade, till exempel ciam-client-app.

  2. Under Hantera väljer du API-behörigheter.

  3. Under Konfigurerade behörigheter väljer du Lägg till en behörighet.

  4. Välj fliken Mina API:er .

  5. I listan över API:er väljer du API:et, till exempel ciam-ToDoList-api.

  6. Välj alternativet Programbehörigheter . Vi väljer det här alternativet eftersom appen loggar in som sig själv, inte användare.

  7. I behörighetslistan väljer du TodoList.Read.All, ToDoList.ReadWrite.All (använd sökrutan om det behövs).

  8. Välj knappen Lägg till behörigheter .

  9. Nu har du tilldelat behörigheterna korrekt. Men eftersom daemonappen inte tillåter användare att interagera med den kan användarna själva inte godkänna dessa behörigheter. För att lösa det här problemet måste du som administratör samtycka till dessa behörigheter för alla användare i klientorganisationen:

    1. Välj Bevilja administratörsmedgivande för <ditt klientnamn> och välj sedan Ja.
    2. Välj Uppdatera och kontrollera sedan att Beviljat för <ditt klientnamn> visas under Status för båda behörigheterna.

Klona eller ladda ned exempel på daemonprogram och webb-API

Om du vill hämta webbappens exempelkod kan du utföra någon av följande uppgifter:

  • Ladda ned .zip-filen eller klona exempelwebbappen från GitHub genom att köra följande kommando:

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

Om du väljer att ladda ned .zip-filen extraherar du exempelappfilen till en mapp där sökvägens totala längd är 260 eller färre tecken.

Installera projektberoenden

  1. Öppna ett konsolfönster och ändra till den katalog som innehåller Node.js exempelapp:

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

  2. Kör följande kommandon för att installera appberoenden:

        npm install && npm update

Konfigurera exempeldaemonappen och API:et

Så här använder du appregistreringen i klientwebbappexemplet:

  1. Öppna App\authConfig.js filen i kodredigeraren.

  2. Hitta platshållaren:

    • Enter_the_Application_Id_Here och ersätt det med program-ID:t (klient) för daemonappen som du registrerade tidigare.

    • Enter_the_Tenant_Subdomain_Here och ersätt den med underdomänen Katalog (klientorganisation). Om din primära klientdomän till exempel är contoso.onmicrosoft.comanvänder du contoso. Om du inte har ditt klientnamn kan du läsa information om klientorganisationen.

    • Enter_the_Client_Secret_Here och ersätt det med det hemliga daemon-appvärdet som du kopierade tidigare.

    • Enter_the_Web_Api_Application_Id_Here och ersätt det med program-ID :t (klient) för webb-API:et som du kopierade tidigare.

Så här använder du appregistreringen i webb-API-exemplet:

  1. Öppna API\ToDoListAPI\appsettings.json filen i kodredigeraren.

  2. Hitta platshållaren:

    • Enter_the_Application_Id_Here och ersätt det med program-ID:t (klient) för det webb-API som du kopierade.

    • Enter_the_Tenant_Id_Here och ersätt det med katalog-ID:t (klientorganisation) som du kopierade tidigare.

    • Enter_the_Tenant_Subdomain_Here och ersätt den med underdomänen Katalog (klientorganisation). Om din primära klientdomän till exempel är contoso.onmicrosoft.comanvänder du contoso. Om du inte har ditt klientnamn kan du läsa information om klientorganisationen.

Köra och testa daemon-exempelappen och API:et

  1. Öppna ett konsolfönster och kör sedan webb-API:et med hjälp av följande kommandon:

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

  2. Kör webbappklienten med hjälp av följande kommandon:

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

Om daemonappen och webb-API:et körs korrekt bör du se något som liknar följande JSON-matris i konsolfönstret

{
    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'
}

Så här fungerar det

Den Node.js appen använder OAuth 2.0-klientautentiseringsuppgifter för att hämta en åtkomsttoken för sig själv och inte för användaren. Den åtkomsttoken som appbegäranden kräver innehåller de behörigheter som representeras som roller. Flödet för klientautentiseringsuppgifter använder den här uppsättningen behörigheter i stället för användaromfattningar för programtoken. Du exponerade dessa programbehörigheter i webb-API:et tidigare och beviljade dem sedan till daemonappen.

På API-sidan måste webb-API:et verifiera att åtkomsttoken har de behörigheter som krävs (programbehörigheter). Webb-API:et kan inte acceptera en åtkomsttoken som inte har de behörigheter som krävs.

Åtkomst till data

En webb-API-slutpunkt bör vara beredd att acceptera anrop från både användare och program. Därför bör den ha ett sätt att svara på varje begäran i enlighet med detta. Ett anrop från en användare via delegerade behörigheter/omfång tar till exempel emot användarens uppgiftslista. Å andra sidan kan ett anrop från ett program via programbehörigheter/roller få hela att göra-listan. Men i den här artikeln gör vi bara ett programanrop, så vi behövde inte konfigurera delegerade behörigheter/omfång.

Nästa steg