Share via

API meghívása egy minta Node.js démonalkalmazásban

  • Cikk

Ez az útmutató egy minta Node.js démonalkalmazással mutatja be, hogyan szerez be egy démonalkalmazás egy jogkivonatot egy webes API meghívásához. A Microsoft Entra védi a webes API-t.

A démonalkalmazás saját nevében szerez be jogkivonatot (nem felhasználó nevében). A felhasználók nem használhatnak démonalkalmazásokat, mert saját identitást igényelnek. Az ilyen típusú alkalmazás hozzáférési jogkivonatot kér az alkalmazás identitásának használatával, és megjeleníti annak alkalmazásazonosítóját, hitelesítő adatait (jelszavát vagy tanúsítványát), valamint az alkalmazásazonosító URI-ját a külső azonosítónak.

A démonalkalmazások a szabványos OAuth 2.0 ügyfél-hitelesítő adatokat használják. A jogkivonat beszerzésének egyszerűsítése érdekében a cikkben használt minta a Microsoft Authentication Library for Node (MSAL Node) függvényt használja.

Előfeltételek

Démonalkalmazás és webes API regisztrálása

Ebben a lépésben létrehozza a démont és a webes API-alkalmazásregisztrációkat, és megadja a webes API hatóköreit.

Web API-alkalmazás regisztrálása

  1. Jelentkezzen be a Microsoft Entra felügyeleti központba legalább alkalmazásfejlesztőként.

  2. Ha több bérlőhöz is rendelkezik hozzáféréssel, a felső menü Gépház ikonjával válthat a külső bérlőre a Címtárak + előfizetések menüből.

  3. Keresse meg az identitásalkalmazásokat>> Alkalmazásregisztrációk.

  4. Válassza az + Új regisztráció lehetőséget.

  5. A megjelenő Alkalmazás regisztrálása lapon adja meg az alkalmazás regisztrációs adatait:

    1. A Név szakaszban adjon meg egy értelmes alkalmazásnevet, amely megjelenik az alkalmazás felhasználói számára, például ciam-ToDoList-api.

    2. A Támogatott fióktípusok csoportban válassza a Csak ebben a szervezeti címtárban lévő Fiókok lehetőséget.

  6. Válassza a Regisztráció elemet az alkalmazás létrehozásához.

  7. A regisztráció befejezésekor megjelenik az alkalmazás Áttekintés panelje . Jegyezze fel a címtár (bérlő) azonosítóját és az alkalmazás forráskódjában használandó alkalmazás-(ügyfél-) azonosítót .

Alkalmazásszerepkörök konfigurálása

Az API-nak legalább egy alkalmazásszerepkört kell közzétennie az alkalmazásokhoz, más néven alkalmazásengedélyekhez, hogy az ügyfélalkalmazások saját maguk is beszerezhessék a hozzáférési jogkivonatot. Az alkalmazásengedélyek olyan típusú engedélyek, amelyeket az API-knak közzé kell tenniük, ha engedélyezni szeretnék az ügyfélalkalmazások számára a sikeres hitelesítést, és nem kell bejelentkezniük a felhasználóknak. Alkalmazásengedély közzétételéhez kövesse az alábbi lépéseket:

  1. A Alkalmazásregisztrációk lapon válassza ki a létrehozott alkalmazást (például a ciam-ToDoList-api-t) az Áttekintés lap megnyitásához.

  2. A Kezelés csoportban válassza az Alkalmazásszerepkörök lehetőséget.

  3. Válassza az Alkalmazásszerepkör létrehozása lehetőséget, majd adja meg a következő értékeket, majd kattintson az Alkalmaz gombra a módosítások mentéséhez:

    Tulajdonság Érték
    Megjelenített név ToDoList.Read.All
    Engedélyezett tagtípusok Alkalmazások
    Érték ToDoList.Read.All
    Leírás Minden felhasználó ToDo-listájának olvasásának engedélyezése az alkalmazás számára a "TodoListApi" használatával

  4. Válassza ismét az Alkalmazásszerepkör létrehozása lehetőséget, majd adja meg a következő értékeket a második alkalmazásszerepkörhöz, majd kattintson az Alkalmaz gombra a módosítások mentéséhez:

    Tulajdonság Érték
    Megjelenített név ToDoList.ReadWrite.All
    Engedélyezett tagtípusok Alkalmazások
    Érték ToDoList.ReadWrite.All
    Leírás Az alkalmazás a ToDoListApi használatával elolvashatja és megírhatja minden felhasználó ToDo-listáját

Nem kötelező jogcímek konfigurálása

A Microsoft-identitás által visszaadott jogkivonatok kisebbek maradnak, hogy optimális teljesítményt biztosítsanak a kérést kérő ügyfelek. Ennek eredményeképpen a jogkivonatban alapértelmezés szerint már nem található több jogcím, és kifejezetten alkalmazásonként kell kérni. Ebben az alkalmazásban az idtyp opcionális jogcímet is tartalmaznia kell, amely segít a webes API-nak annak megállapításában, hogy egy jogkivonat alkalmazásjogkivonat vagy alkalmazás+felhasználói jogkivonat-e. Bár az scp- és szerepkör-jogcímek kombinációját is használhatja ugyanahhoz a célra, az idtyp jogcím használata a legegyszerűbb módja annak, hogy egymástól elkülönítsen egy alkalmazásjogkivonatot és egy alkalmazás+felhasználói jogkivonatot. Ennek a jogcímnek az értéke például az alkalmazás , ha a jogkivonat csak alkalmazásjogkivonat.

Az idtyp opcionális jogcímének konfigurálásához kövesse az alábbi lépéseket:

  1. A Alkalmazásregisztrációk lapon, amelyhez opcionális jogcímet (például ciam-client-appot) szeretne konfigurálni az Áttekintés lap megnyitásához.

  2. A Kezelés területen válassza a Jogkivonat-konfiguráció lehetőséget.

  3. Válassza az Opcionális jogcím hozzáadása lehetőséget.

  4. A Jogkivonat típusa csoportban válassza az Access lehetőséget.

  5. Válassza ki a választható jogcímazonosítót.

  6. A módosítások mentéséhez válassza a Hozzáadás lehetőséget.

A démonalkalmazás regisztrálása

Ahhoz, hogy az alkalmazás bejelentkezhessen a Microsoft Entra szolgáltatással, Microsoft Entra Külső ID tisztában kell lennie a létrehozott alkalmazással. Az alkalmazásregisztráció megbízhatósági kapcsolatot létesít az alkalmazás és a Microsoft Entra között. Amikor regisztrál egy alkalmazást, a külső azonosító létrehoz egy egyedi azonosítót, más néven egy alkalmazás (ügyfél) azonosítót, amely az alkalmazás azonosítására szolgál a hitelesítési kérelmek létrehozásakor.

Az alábbi lépések bemutatják, hogyan regisztrálhatja az alkalmazást a Microsoft Entra Felügyeleti központban:

  1. Jelentkezzen be a Microsoft Entra felügyeleti központba legalább alkalmazásfejlesztőként.

  2. Ha több bérlőhöz is rendelkezik hozzáféréssel, a felső menü Gépház ikonjával válthat a külső bérlőre a Címtárak + előfizetések menüből.

  3. Keresse meg az identitásalkalmazásokat>> Alkalmazásregisztrációk.

  4. Válassza az + Új regisztráció lehetőséget.

  5. A Megjelenő alkalmazás regisztrálása lapon;

    1. Adjon meg egy értelmes alkalmazásnevet, amely az alkalmazás felhasználói számára jelenik meg, például ciam-client-app.
    2. A Támogatott fióktípusok csoportban válassza a Csak ebben a szervezeti címtárban lévő Fiókok lehetőséget.

  6. Válassza ki a pénztárgépet.

  7. Az alkalmazás Áttekintés panelje a sikeres regisztrációkor jelenik meg. Jegyezze fel az alkalmazás forráskódjában használandó alkalmazás-(ügyfél-) azonosítót .

Titkos ügyfélkód létrehozása

Hozzon létre egy ügyfélkulcsot a regisztrált alkalmazáshoz. Az alkalmazás az ügyfél titkos kódjával igazolja identitását, amikor jogkivonatokat kér.

  1. A Alkalmazásregisztrációk lapon válassza ki a létrehozott alkalmazást (például a ciam-client-appot) az Áttekintés lap megnyitásához.
  2. A Kezelés területen válassza a Tanúsítványok és titkos kódok lehetőséget.
  3. Válassza az Új titkos ügyfélkód lehetőséget.
  4. A Leírás mezőbe írja be az ügyfél titkos kódjának leírását (például a ciam alkalmazás ügyfélkulcsát).
  5. A Lejáratok csoportban válassza ki azt az időtartamot, amelyre érvényes a titkos kód (a szervezet biztonsági szabályai szerint), majd válassza a Hozzáadás lehetőséget.
  6. Jegyezze fel a titkos kód értékét. Ezt az értéket egy későbbi lépésben fogja használni a konfigurációhoz. A titkos kulcs értéke nem jelenik meg újra, és semmilyen módon nem lesz lekérthető, miután eltávolodik a tanúsítványoktól és titkos kódoktól. Győződjön meg róla, hogy rögzíti.

API-engedélyek megadása a démonalkalmazáshoz

  1. A Alkalmazásregisztrációk lapon válassza ki a létrehozott alkalmazást, például a ciam-client-app alkalmazást.

  2. A Kezelés területen válassza ki az API-engedélyeket.

  3. A Konfigurált engedélyek csoportban válassza az Engedély hozzáadása lehetőséget.

  4. Válassza ki a szervezet által használt API-kat.

  5. Az API-k listájában válassza ki az API-t, például a ciam-ToDoList-api-t.

  6. Válassza az Alkalmazásengedélyek lehetőséget. Ezt a lehetőséget választjuk, mivel az alkalmazás önmagában jelentkezik be, nem a felhasználókba.

  7. Az engedélyek listájában válassza a TodoList.Read.All, a ToDoList.ReadWrite.All elemet (szükség esetén használja a keresőmezőt).

  8. Válassza az Engedélyek hozzáadása gombot.

  9. Ezen a ponton helyesen rendelte hozzá az engedélyeket. Mivel azonban a démonalkalmazás nem teszi lehetővé a felhasználók számára az interakciót, maguk a felhasználók nem járulhatnak hozzá ezekhez az engedélyekhez. A probléma megoldásához Önnek, mint rendszergazdának hozzá kell adnia ezeket az engedélyeket a bérlő összes felhasználója nevében:

    1. Válassza a rendszergazdai hozzájárulás megadása a bérlő nevének> megadását<, majd válassza az Igen lehetőséget.
    2. Válassza a Frissítés lehetőséget, majd ellenőrizze, hogy a bérlő nevének> megadása <mindkét engedély állapotábanmegjelenik-e.

Démonalkalmazás és webes API klónozása vagy letöltése

A mintaalkalmazás beszerzéséhez klónozhatja a GitHubról, vagy letöltheti .zip fájlként.

  • A minta klónozásához nyisson meg egy parancssort, és keresse meg a projektet, és írja be a következő parancsot:

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

  • Töltse le a .zip fájlt. Bontsa ki egy fájl elérési útjára, ahol a név hossza kevesebb, mint 260 karakter.

A projekt függőségeinek telepítése

  1. Nyisson meg egy konzolablakot, és váltson a Node.js mintaalkalmazást tartalmazó könyvtárra:

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

  2. Futtassa a következő parancsokat az alkalmazásfüggőségek telepítéséhez:

    npm install && npm update

A minta démonalkalmazás és API konfigurálása

Az alkalmazásregisztráció használata az ügyfél-webalkalmazás mintájában:

  1. Nyissa meg App\authConfig.js a fájlt a kódszerkesztőben.

  2. Keresse meg a helyőrzőt:

    • Enter_the_Application_Id_Here és cserélje le a korábban regisztrált démonalkalmazás alkalmazás-(ügyfél-) azonosítójára.

    • Enter_the_Tenant_Subdomain_Here és cserélje le a Címtár (bérlő) altartományra. Ha például a bérlő elsődleges tartománya, contoso.onmicrosoft.comhasználja a következőt contoso: Ha nem rendelkezik a bérlő nevével, olvassa el a bérlő adatait.

    • Enter_the_Client_Secret_Here és cserélje le a korábban másolt démonalkalmazás titkos kódértékére.

    • Enter_the_Web_Api_Application_Id_Here és cserélje le a korábban másolt webes API alkalmazás-(ügyfél-) azonosítójára.

Az alkalmazásregisztráció használata a webes API-mintában:

  1. Nyissa meg API\ToDoListAPI\appsettings.json a fájlt a kódszerkesztőben.

  2. Keresse meg a helyőrzőt:

    • Enter_the_Application_Id_Here és cserélje le a másolt webes API alkalmazás-(ügyfél-) azonosítójára.

    • Enter_the_Tenant_Id_Here és cserélje le a korábban másolt címtár-(bérlői) azonosítóra.

    • Enter_the_Tenant_Subdomain_Here és cserélje le a Címtár (bérlő) altartományra. Ha például a bérlő elsődleges tartománya, contoso.onmicrosoft.comhasználja a következőt contoso: Ha nem rendelkezik a bérlő nevével, olvassa el a bérlő adatait.

Minta démonalkalmazás és API futtatása és tesztelése

  1. Nyisson meg egy konzolablakot, majd futtassa a webes API-t az alábbi parancsokkal:

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

  2. Futtassa a webalkalmazás-ügyfelet az alábbi parancsokkal:

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

  • Ha a démonalkalmazás és a webes API sikeresen fut, a következő JSON-tömbhöz hasonlót kell látnia a konzolablakban

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

Hogyan működik?

A Node.js alkalmazás az OAuth 2.0 ügyfél hitelesítő adataival szerez be egy hozzáférési jogkivonatot magának, és nem a felhasználónak. Az alkalmazás által kért hozzáférési jogkivonat tartalmazza a szerepkörként megadott engedélyeket. Az ügyfél hitelesítőadat-folyamata ezt az engedélykészletet használja az alkalmazásjogkivonatok felhasználói hatókörei helyett. Ezeket az alkalmazásengedélyeket korábban a webes API-ban tette közzé, majd megadta őket a démonalkalmazásnak.

Az API oldalán a webes API-nak ellenőriznie kell, hogy a hozzáférési jogkivonat rendelkezik-e a szükséges engedélyekkel (alkalmazásengedélyekkel). A webes API nem tud olyan hozzáférési jogkivonatot elfogadni, amely nem rendelkezik a szükséges engedélyekkel.

Az adatokhoz való hozzáférés

A webes API-végpontnak készen kell állnia arra, hogy fogadja a felhasználóktól és az alkalmazásoktól érkező hívásokat. Ezért meg kell adni a módját annak, hogy ennek megfelelően válaszoljon az egyes kérelmekre. Egy felhasználó által delegált engedélyeken/hatókörökön keresztül érkező hívás például megkapja a felhasználó teendőlistáját. Másfelől egy alkalmazás alkalmazásengedélyeken/szerepkörökön keresztüli hívásai a teljes teendőlistát megkaphatják. Ebben a cikkben azonban csak alkalmazáshívást kezdeményezünk, így nem kellett delegált engedélyeket/hatóköröket konfigurálnunk.

Kapcsolódó tartalom