Gyors útmutató – Felhasználók bejelentkeztetése és a webes API meghívása a példa Node.js webalkalmazásban

A következőre vonatkozik: Külső bérlők (további információ)

Ebben a rövid útmutatóban megtudhatja, hogyan jelentkezhet be felhasználóként, és hogyan hívhat meg webes API-t egy Node.js webalkalmazásból a külső bérlőjén. A mintaalkalmazás egy .NET API-t hív meg. A minta webalkalmazás a Csomóponthoz készült Microsoft Authentication Library (MSAL) használatával kezeli a hitelesítést.

Előfeltételek

• Hajtsa végre a Gyorsútmutatóban található lépéseket és előfeltételeket: Jelentkezzen be a felhasználókat a mintapéldány webalkalmazás cikkben. Ez a cikk bemutatja, hogyan jelentkeztethet be felhasználókat egy minta Node.js webalkalmazás használatával.
• Külső bérlő. A létrehozáshoz válasszon az alábbi módszerek közül:
  • (Ajánlott) A Microsoft Entra Külső azonosító bővítmény használatával közvetlenül a Visual Studio Code-ban állíthat be külső bérlőt.
  • Hozzon létre egy új külső bérlőt a Microsoft Entra Felügyeleti központban.
• Regisztráljon egy új alkalmazást a webes API-hoz a Microsoft Entra felügyeleti központban, amely csak ebben a szervezeti címtárban lévő fiókokhoz van konfigurálva. További részletekért tekintse meg az alkalmazás regisztrálását . Jegyezze fel a következő értékeket az alkalmazás áttekintési oldaláról későbbi használatra:
  • Alkalmazás (ügyfél) azonosítója
  • Címtár (ügyfél) azonosítója
• Visual Studio Code vagy más kódszerkesztő.
• Node.js.
• .NET 7.0 vagy újabb.

API-hatókörök és -szerepkörök konfigurálása

A webes API regisztrálásával api-hatóköröket kell konfigurálnia, hogy meghatározza azokat az engedélyeket, amelyeket az ügyfélalkalmazás a webes API eléréséhez kérhet. Emellett be kell állítania az alkalmazásszerepköröket a felhasználók vagy alkalmazások számára elérhető szerepkörök megadásához, és meg kell adnia a webalkalmazás számára a szükséges API-engedélyeket ahhoz, hogy meghívhassa a webes API-t.

API-hatókörök konfigurálása

Az API-nak legalább egy hatókört , más néven delegált engedélyt kell közzétennie ahhoz, hogy az ügyfélalkalmazások sikeresen beszerezhessék a felhasználó hozzáférési jogkivonatát. A hatókör közzétételéhez kövesse az alábbi lépéseket:

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

2. A Kezeléslehetőségei között válassza a API közzétételeelemet.

3. A lap tetején, az alkalmazásazonosító URI-ja mellett válassza a Hozzáadás hivatkozást az alkalmazáshoz egyedi URI létrehozásához.

4. Fogadja el a javasolt alkalmazásazonosító URI-ját, például api://{clientId}, és válassza a Mentés lehetőséget. Amikor a webalkalmazás hozzáférési jogkivonatot kér a webes API-hoz, hozzáadja az URI-t az API-hoz definiált egyes hatókörök előtagjaként.

5. Az API által definiált hatókörök alatt válassza a Hatókör hozzáadása lehetőséget.

6. Adja meg a következő értékeket, amelyek olvasási hozzáférést határoznak meg az API-hoz, majd válassza a Hatókör hozzáadása lehetőséget a módosítások mentéséhez:

   Ingatlan	Érték
   Hatókör neve	ToDoList.Olvassa el
   Kik járulhatnak hozzá	Csak adminisztrátorok
   Rendszergazdai hozzájárulás megjelenítési neve	Felhasználók ToDo-listájának olvasása a "TodoListApi" használatával
   Rendszergazdai hozzájárulás leírása	Engedélyezze az alkalmazás számára a felhasználó ToDo-listájának olvasását a "TodoListApi" használatával.
   Állam	Engedélyezve

7. Válassza a Hatókör hozzáadása lehetőséget újra, és írja be a következő értékeket, amelyek meghatározzák az API olvasási és írási hozzáférési hatókörét. A módosítások mentéséhez válassza a Hatókör hozzáadása lehetőséget:

   Ingatlan	Érték
   Hatókör neve	ToDoList.ReadWrite
   Kik járulhatnak hozzá	Csak adminisztrátorok
   Rendszergazdai hozzájárulás megjelenítési neve	Felhasználók ToDo-listájának olvasása és szerkesztése a "ToDoListApi"
   Rendszergazdai hozzájárulás leírása	Lehetővé teszi az alkalmazás számára a felhasználó ToDo-listájának olvasását és írását a "ToDoListApi" használatával
   Állam	Engedélyezve

További információt a legalacsonyabb jogosultság elvéről, amikor engedélyeket tesz közzé webes API-hoz.

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 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. Az 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ésalatt válassza ki az Alkalmazásszerepköröklehető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:

   Ingatlan	Érték
   Megjelenítendő 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
   Szeretné engedélyezni ezt az alkalmazásszerepkört?	Legyen ez bejelölve

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:

   Ingatlan	Érték
   Megjelenítendő 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
   Szeretné engedélyezni ezt az alkalmazásszerepkört?	Legyen ez bejelölve

Választható jogcímek konfigurálása

Hozzáadhatja az idtyp opcionális jogcímet, hogy segítsen a webes API-nak annak meghatározásában, hogy egy jogkivonat alkalmazásjogkivonat vagy alkalmazás + felhasználói jogkivonat-e. Bár a scp és szerepkörök kombinációját is használhatja ugyanarra a célra igénylések esetén, a idtyp igénylés használata a legegyszerűbb módja annak, hogy megkülönböztessen egy alkalmazásjogkivonatot az alkalmazás + felhasználói jogkivonattól. A jogcím értéke például alkalmazás, ha a token egy csak alkalmazás token.

Az opcionális jogcímek konfigurálása című cikk lépéseit követve adja hozzá az idtyp jogcímet a hozzáférési jogkivonathoz:

• A Token típusnál válassza a Hozzáféréselemet.
• Az opcionális jogcímek listájában válassza az idtyp lehetőséget.

API-engedélyek megadása a webalkalmazáshoz

Az ügyfélalkalmazás (ciam-client-app) API-engedélyeinek megadásához kövesse az alábbi lépéseket:

1. Az 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 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 a Delegált engedélyek lehetőséget.

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

8. Válassza az Engedélyek hozzáadása gombot. Ezen a ponton helyesen rendelte hozzá az engedélyeket. Mivel azonban a bérlő egy ügyfél bérlője, a fogyasztói felhasználók maguk 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(z) Rendszergazdai hozzájárulás megadása a <bérlőnév>számára, majd válassza az Igenlehetőséget.

   2. Válassza a Frissítés lehetőséget, majd ellenőrizze, hogy a < alatt megjelenik-e a(z) az ön bérlőnevéhez >tartozó engedélyezés mindkét hatókör esetében.

9. A Konfigurált engedélyek listájában egyenként válassza ki a ToDoList.Read és a ToDoList.ReadWrite engedélyeket, majd másolja ki az engedély teljes URI-ját későbbi használatra. A teljes URI engedélye valami hasonlót jelent, mint api://{clientId}/{ToDoList.Read} vagy api://{clientId}/{ToDoList.ReadWrite}.

Minta webalkalmazá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, navigáljon arra a helyre, ahol létre szeretné hozni a projektet, majd í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. Helyezze el egy olyan fájl elérési útjára, ahol a név hossza kevesebb, mint 260 karakter.

Projektfüggőségek telepítése

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

   cd 2-Authorization\4-call-api-express\App
   

2. Futtassa a következő parancsokat a webalkalmazás-függőségek telepítéséhez:

   npm install && npm update
   

A minta webalkalmazás és API konfigurálása

Az alkalmazásregisztráció használata az ügyfélweb-alkalmazás mintapéldájában:

1. A kódszerkesztőben nyissa meg App\authConfig.js fájlt.

2. Keresse meg a helykitöltőt:

   • Enter_the_Application_Id_Here és cserélje le a korábban regisztrált ügyfélalkalmazás alkalmazás-(ügyfél-) azonosítójára. Az ügyfélalkalmazás az, amelyet az előfeltételekben regisztráltál.
   • Cserélje le az Enter_the_Tenant_Subdomain_Here-t a Címtár (bérlő) altartományra. Ha például a bérlő elsődleges domainje contoso.onmicrosoft.com, használja a contoso. Ha nem rendelkezik a bérlő nevével, megtudhatja, hogyan olvashatja el a bérlő adatait.
   • Enter_the_Client_Secret_Here és cserélje le a korábban másolt alkalmazás titkos kódértékére.
   • Enter_the_Web_Api_Application_Id_Here és cserélje le a korábban az előfeltételek részeként másolt webes API alkalmazás-(ügyfél-) azonosítójára.

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

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

2. Keresse meg a helykitöltőt:

   • Enter_the_Application_Id_Here és cserélje le a másolt webes API alkalmazás-(ügyfél-) azonosítójára. A web API-alkalmazás az egyik, amelyet korábban regisztráltál az előfeltételek részeként.
   • Enter_the_Tenant_Id_Here és cserélje le a korábban másolt címtár-azonosítóra (bérlői azonosítóra).
   • Cserélje le az Enter_the_Tenant_Subdomain_Here-t a Címtár (bérlő) altartományra. Ha például a bérlő elsődleges domainje contoso.onmicrosoft.com, használja a contoso. Ha nem rendelkezik a bérlő nevével, megtudhatja, hogyan olvashatja el a bérlő adatait.

Minta webalkalmazá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\4-call-api-express\API\ToDoListAPI
   dotnet run
   

2. Futtassa a webapp kliensét az alábbi parancsokkal:

   cd 2-Authorization\4-call-api-express\App
   npm install
   npm start
   

3. Nyisd meg a böngésződ, majd lépj a http://localhost:3000.

4. Válassza a Bejelentkezés gombot. A rendszer kéri, hogy jelentkezzen be.

   

5. A bejelentkezési lapon írja be az e-mail-címét, válassza a Tovább lehetőséget, írja be a jelszavát, majd válassza a Bejelentkezés lehetőséget. Ha nincs fiókja, válassza a Nincs fiók lehetőséget? Hozzon létre egy hivatkozást, amely elindítja a regisztrációs folyamatot.

6. Ha a regisztrációs lehetőséget választja, az e-mail kitöltése, az egyszeri pin-kód, az új jelszó és további fiókadatok kitöltése után befejezi a teljes regisztrációs folyamatot. Az alábbi képernyőképhez hasonló lap jelenik meg. Hasonló lap jelenik meg, ha a bejelentkezési lehetőséget választja.

   

API meghívása

1. Az API meghívásához válassza a Teendőlista megtekintése hivatkozást. Az alábbi képernyőképhez hasonló lap jelenik meg.

   

2. Elemek létrehozásával és eltávolításával módosíthatja a to-do listát.

Hogyan működik?

A tevékenységek megtekintésekor, hozzáadásakor vagy eltávolításakor minden alkalommal elindít egy API-hívást. Minden alkalommal, amikor API-hívást indít, az ügyfél webalkalmazás egy hozzáférési jogkivonatot szerez be az API-végpont meghívásához szükséges engedélyekkel (hatókörökkel). Egy feladat olvasásához például az ügyfél-webalkalmazásnak be kell szereznie egy hozzáférési jogkivonatot ToDoList.Read engedéllyel vagy hatókörrel.

A webes API-végpontnak ellenőriznie kell, hogy az ügyfélalkalmazás által biztosított hozzáférési jogkivonat engedélyei vagy hatókörei érvényesek-e. Ha a hozzáférési jogkivonat érvényes, a végpont a HTTP-kérésre válaszol, ellenkező esetben 401 Unauthorized HTTP-hibával válaszol.

Kapcsolódó tartalom

• Oktatóanyag: Egy külső bérlőben regisztrált ASP.NET Core webes API biztonságossá tétele.