Rövid útmutató: Webes API meghívása egy minta démonalkalmazásban

A következőkre vonatkozik: Zöld kör fehér pipa szimbólummal, amely a következő tartalmat jelzi a munkaerő-bérlőkre. A munkaerő-bérlők zöld körrel, fehér pipa jellel, amely a következő tartalmat jelzi a külső bérlőkre. Külső bérlők (további információ)

Ebben a rövid útmutatóban egy minta démonalkalmazással szerezhet be hozzáférési jogkivonatot, és meghívhat egy védett webes API-t a Microsoft Authentication Library (MSAL)használatával.

Mielőtt hozzákezdene, használja a Bérlőtípus kiválasztása a lap tetején található választógombot a bérlőtípus kiválasztásához. A Microsoft Entra ID két bérlői konfigurációs lehetőséget biztosít: szervezeti és külső. A munkaerőnek szánt bérlői konfiguráció az ön alkalmazottai, a belső alkalmazások és más szervezeti erőforrások számára készült. A külső bérlő az ügyfelek által használt alkalmazások számára készült.

A rövid útmutatóban használt mintaalkalmazás hozzáférési jogkivonatot szerez be a Microsoft Graph API meghívásához.

Előfeltételek

  • Aktív előfizetéssel rendelkező Azure-fiók. Ha még nem rendelkezik ilyen fiókkal, hozzon létre egy fiókot ingyenes.
  • Ennek az Azure-fióknak rendelkeznie kell az alkalmazások kezeléséhez szükséges engedélyekkel. Az alábbi Microsoft Entra-szerepkörök bármelyike tartalmazza a szükséges engedélyeket:
    • Alkalmazásadminisztrátor
    • Alkalmazásfejlesztő
    • Felhőalkalmazás-rendszergazda
  • Munkaerőt igénybe vevő. Használhatja az alapértelmezett címtárat, vagy beállíthat egy új bérlőt.
  • Regisztráljon egy új alkalmazást 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
  • Adjon hozzá egy titkos ügyfélkulcsot az alkalmazásregisztrációhoz. Ne használja ügyféltitkokat az éles alkalmazásokban. Használjon inkább tanúsítványokat vagy összevont hitelesítő adatokat. További információ: Hitelesítő adatok hozzáadása az alkalmazáshoz.

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

Ahhoz, hogy a démonalkalmazás hozzáférjen az adatokhoz a Microsoft Graph API-ban, meg kell adnia neki a szükséges engedélyeket. A démonalkalmazásnak alkalmazástípus-engedélyekre van szüksége. A felhasználók nem használhatnak démonalkalmazásokat, ezért a bérlői rendszergazdának hozzá kell adnia ezeket az engedélyeket. Az engedélyek megadásához és jóváhagyásához kövesse az alábbi lépéseket:

A .NET démonalkalmazáshoz nincs szükség engedély megadására és jóváhagyására. Ez a démonalkalmazás beolvassa a saját alkalmazásregisztrációs adatait, így ezt anélkül teheti meg, hogy bármilyen alkalmazásengedélyt kap.

A mintaalkalmazás 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 nyissa meg a parancssort, navigáljon arra a helyre, ahol létre kívánja hozni a projektet, és írja be a következő parancsot:
git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git

A projekt konfigurálása

Az alkalmazásregisztrációs adatok ügyféldémonalkalmazás-mintában való használatához kövesse az alábbi lépéseket:

  1. Nyisson meg egy konzolablakot, majd lépjen az ms-identity-docs-code-dotnet/console-daemon könyvtárra:

    cd ms-identity-docs-code-dotnet/console-daemon

  2. Nyissa meg Program.cs, és cserélje le a fájl tartalmát a következő kódrészletre;

     // 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 Microsoft 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 – A hitelesítési hatóság egy URL-cím, amely olyan könyvtárat jelöl, amelytől az MSAL jogkivonatokat kérhet. Cserélje le a Enter_the_tenant_ID_obtained_from_the_Microsoft_Entra_admin_center értéket a korábban rögzített könyvtár- (bérlő-) azonosítóra.
    • ClientId – Az alkalmazás azonosítója, más néven az ügyfél. Cserélje le az idézőjelek szövegét a regisztrált alkalmazás áttekintési oldaláról korábban rögzített Application (client) ID értékre.
    • ClientSecret – Az alkalmazáshoz a Microsoft Entra felügyeleti központban létrehozott ügyfélkód. Adja meg az ügyféltitok értékét.
    • ClientObjectId – Az ügyfélalkalmazás objektumazonosítója. Cserélje le az idézőjelek szövegét a regisztrált alkalmazás áttekintési oldaláról korábban rögzített Object ID értékre.

Az alkalmazás futtatása és tesztelése

Konfigurálta a mintaalkalmazást. Továbbléphet és futtathatja, majd tesztelheti.

A konzolablakban futtassa a következő parancsot az alkalmazás létrehozásához és futtatásához:

dotnet run

Miután az alkalmazás sikeresen lefutott, a következő kódrészlethez hasonló választ jelenít meg (rövidítve a rövidítéshez):

{
"@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,
...
}

Hogyan működik?

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 az alkalmazásazonosító, a hitelesítő adatok (titkos kulcs vagy tanúsítvány) és az alkalmazásazonosító URI bemutatásával. A démon-alkalmazás a standard OAuth 2.0 ügyfél-hitelesítési folyamathoz használja a hozzáférési jogkivonat megszerzéséhez.

Az alkalmazás hozzáférési jogkivonatot szerez be a Microsoft identitásplatformjáról. A hozzáférési jogkivonat hatóköre a Microsoft Graph API-hoz tartozik. Az alkalmazás ezután a hozzáférési jogkivonat használatával saját alkalmazásregisztrációs adatokat kér a Microsoft Graph API-tól. Az alkalmazás bármilyen erőforrást kérhet a Microsoft Graph API-tól, amennyiben a hozzáférési jogkivonat rendelkezik a megfelelő engedélyekkel.

A minta bemutatja, hogy egy felügyelet nélküli feladat vagy Windows-szolgáltatás hogyan futtatható alkalmazásidentitással a felhasználó identitása helyett.

Kapcsolódó tartalom

Előfeltételek

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 kulcsával igazolja identitását, amikor tokeneket kér.

  1. Az Alkalmazásregisztrációk lapon válassza ki a létrehozott alkalmazást (például webalkalmazás ügyfélkódját) a Áttekintés lap megnyitásához.
  2. A kezelése területen válassza a Tanúsítványok & titkos kulcsok>Az ügyfél titkos kulcsainak>Új titkos ügyfélkódlehetőséget.
  3. A Leírás mezőben adja meg az ügyfél titkos kulcsának leírását (például webalkalmazás ügyfél titkos kulcsa).
  4. A Lejáratiterületen válassza ki a titkos kód érvényességének időtartamát (a szervezet biztonsági szabályai szerint), majd válassza a hozzáadása lehetőséget.
  5. A titkos kód értékénekrögzítése. Ezt az értéket egy későbbi lépésben konfigurálhatja. A titkos érték nem jelenik meg újra, és semmilyen módon nem visszakereshető, miután elnavigált a tanúsítványok és titkos kódok. Győződjön meg róla, hogy rögzíti.

Amikor hitelesítő adatokat hoz létre egy bizalmas ügyfélalkalmazáshoz:

  • A Microsoft azt javasolja, hogy az alkalmazás éles környezetbe való áthelyezése előtt használjon tanúsítványt az ügyfélkód helyett. További információ egy tanúsítvány használatáról: lásd az utasításokat Microsoft identitásplatform-alkalmazás hitelesítési tanúsítványának hitelesítő adatai.

  • Tesztelési célokra létrehozhat egy önaláírt tanúsítványt, és konfigurálhatja az alkalmazásokat a hitelesítésre. Azonban a termelésben Önnek egy jól ismert hitelesítésszolgáltató által aláírt tanúsítványt kell vásárolnia, majd az Azure Key Vault használatával kezelheti a tanúsítványhozzáférést és az élettartamot.

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

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

  2. A Kezelésalatt válassza az API-engedélyeket.

  3. A Konfigurált engedélyekterületen válassza a Engedély hozzáadásalehetőséget.

  4. Válassza ki azokat a API-kat, amelyeket a szervezetem használ a lapon.

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

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

  7. Az engedélyek listájában válassza TodoList.Read.All, ToDoList.ReadWrite.All (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 bérlőneve <rendszergazdai hozzájárulás megadását>, majd válassza az Igenlehetőséget.
    2. Válassza a Frissítéslehetőséget, majd ellenőrizze, hogy Megadott <a bérlő neve> jelenik-e meg Állapot alatt mindkét engedély esetében.

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 ciam-ToDoList-api) a Áttekintés oldal megnyitásához.

  2. A Kezelésterületen válassza alkalmazásszerepköröket.

  3. Válassza az Alkalmazásszerepkör létrehozásagombot, adja meg a következő értékeket, majd válassza az Alkalmaz lehetőséget 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 Engedélyezze, hogy az alkalmazás minden felhasználónak a ToDo-listáját beolvassa a 'TodoListApi' használatával
    Szeretné engedélyezni ezt az alkalmazásszerepkört? Maradjon bejelölve

  4. Válassza újra a Alkalmazásszerepkör létrehozása lehetőséget, majd adja meg a második alkalmazásszerepkörhöz a következő értékeket, és végül válassza az Alkalmazás lehetőséget 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 Engedélyezze az alkalmazás számára az összes felhasználó teendőlistájának olvasását és írását a "ToDoListApi" használatával
    Szeretné engedélyezni ezt az alkalmazásszerepkört? Maradjon 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 ugyanarra a célra használhatja a scp és szerepkörök jogcímek kombinációját is, az idtyp jogcím használata a legegyszerűbb módja annak megkülönböztetésére, hogy egy alkalmazásjogkivonatról vagy egy alkalmazás + felhasználói jogkivonatról van-e szó. A követelés értéke például app, amikor a jogkivonat csak alkalmazásokhoz használható token.

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 nyissa meg a parancssort, navigáljon arra a helyre, ahol létre kívánja hozni a projektet, és írja be a következő parancsot:

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

  • Másik lehetőségként töltse le a fájl .zip mintákat, majd bontsa ki egy olyan fájlútvonalra, ahol a név hossza 260 karakternél rövidebb.

Projektfüggőségek 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ós adatok ügyfél-webalkalmazás-mintában való használatához kövesse az alábbi lépéseket:

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

  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ő) aldoménra. Ha például a bérlő elsődleges domain neve contoso.onmicrosoft.com, használja a contoso. Ha nem rendelkezik a bérlő nevével, megtudhatja, hogyan olvasni a bérlő adatait.

    • Enter_the_Client_Secret_Here, és cserélje le a korábban másolt daemon alkalmazás titkos é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. A kódszerkesztőben nyissa meg API\ToDoListAPI\appsettings.json fájlt.

  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.

    • Cserélje le a Enter_the_Tenant_Id_Here-t 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ő) aldoménra. Ha például a bérlő elsődleges domain neve contoso.onmicrosoft.com, használja a contoso. Ha nem rendelkezik a bérlő nevével, megtudhatja, hogyan olvasni a bérlő adatait.

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

Konfigurálta a mintaalkalmazást. Továbbléphet és futtathatja, majd tesztelheti.

  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-klienst 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ő adatok folyamának segítségével szerez be hozzáférési jogkivonatot saját magának, nem pedig a felhasználó számára. 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 közzé a webes API-ban, majd adta meg őket a démonalkalmazásnak.

Az API oldalán egy minta .NET 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.

Hozzáférés az adatokhoz

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élyekkel/hatókörökön keresztül érkező hívás például megkapja a felhasználó adatlistáját to-do. Másfelől, egy alkalmazás által, alkalmazásengedélyeken/szerepkörökön keresztül indított hívás a teljes to-do listát megkaphatja. 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

  • Last updated on