Megosztás a következőn keresztül:

ASP.NET Core webes API meghívása az Insomnia használatával

Ez a cikk bemutatja, hogyan hívhat meg védett ASP.NET Core webes API-t az Insomnia használatával. Az Insomnia egy olyan alkalmazás, amely lehetővé teszi HTTP-kérések küldését egy webes API-nak annak engedélyezési és hozzáférés-vezérlési (hitelesítési) szabályzatainak teszteléséhez. Ebben a cikkben egy webalkalmazást és egy webes API-t regisztrál egy bérlőben. A webalkalmazás a Microsoft Identitásplatform által létrehozott hozzáférési jogkivonat lekérésére szolgál. Ezután a jogkivonat használatával jogosult hívást kezdeményezhet a webes API-ra az Insomnia használatával.

Ez a cikk bemutatja, hogyan hívhat meg védett ASP.NET Core webes API-t az Insomnia használatával. Az Insomnia egy olyan alkalmazás, amely lehetővé teszi HTTP-kérések küldését egy webes API-nak annak engedélyezési és hozzáférés-vezérlési (hitelesítési) szabályzatainak teszteléséhez. Az oktatóanyagból következően: Védett végpont implementálása az API-ba, ahol védett API-t hozott létre, regisztrálnia kell egy webalkalmazást a Microsoft identitásplatformján egy hozzáférési jogkivonat létrehozásához. Ezután a jogkivonat használatával jogosult hívást kezdeményezhet az API-ra az Insomnia használatával.

Előfeltételek

  • Egy Azure-fiók, aktív előfizetéssel. Hozzon létre egy fiókot ingyenesen.
  • 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ás-rendszergazda
    • Alkalmazásfejlesztő
    • Felhőalkalmazás-rendszergazda
  • Töltse le és telepítse az Insomnia programot. Az Insomnia használatával hozzáférési jogkivonatot szerezhet be az API-kérésekhez.
  • A .NET 8.0 SDK minimális követelménye.

Egy alkalmazás regisztrálása

A Microsoft Identitásplatform megköveteli, hogy az alkalmazás regisztrálva legyen az identitás- és hozzáférés-kezelési szolgáltatások biztosítása előtt. Az alkalmazásregisztrációval megadhatja az alkalmazás nevét és típusát, valamint a bejelentkezési célközönséget. A bejelentkezési célközönség határozza meg, hogy milyen típusú felhasználói fiókok jelentkezhetnek be egy adott alkalmazásba.

A webes API regisztrálása

A webes API-regisztráció létrehozásához kövesse az alábbi lépéseket:

  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 hozzáfér, a felső menü Beállítások ikonjával válthat arra a bérlőre, amelyben regisztrálni szeretné az alkalmazást a Könyvtárak + előfizetések menüből.

  3. Keresse meg az Entra-azonosítós>alkalmazásregisztrációkat.

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

  5. Adja meg az alkalmazás nevét , például a NewWebAPI1 nevet.

  6. Támogatott fióktípusok esetén csak ebben a szervezeti címtárban válassza a Fiókok lehetőséget. A különböző fióktípusokra vonatkozó információkért válassza a Segítség a választáshoz lehetőséget.

  7. Válassza a Regisztráció lehetőséget.

    Képernyőkép a név megadásáról és a fiók típusának kiválasztásáról.

  8. Amikor a regisztráció befejeződött, megjelenik az alkalmazás Áttekintés panelje. Jegyezze fel a címtár (bérlő) azonosítóját és az alkalmazás (ügyfél) azonosítóját , amelyet a későbbi lépésekben használni szeretne.

    Képernyőkép az áttekintési oldalon található azonosítóértékekről.

Feljegyzés

A támogatott fióktípusok módosíthatók az alkalmazás által támogatott fiókok módosításával.

Az API felfedése

Az API regisztrálása után konfigurálhatja annak engedélyét az API által az ügyfélalkalmazások számára elérhetővé tott hatókörök meghatározásával. Az ügyfélalkalmazások engedélyt kérnek a műveletek végrehajtására azáltal, hogy átadnak egy hozzáférési jogkivonatot a kérésekkel együtt a védett webes API-nak. A webes API ezután csak akkor hajtja végre a kért műveletet, ha a kapott hozzáférési jogkivonat érvényes.

  1. A Kezelés alatt válassza a API kitettsége > Hatókör hozzáadása lehetőséget. Fogadja el a javasolt alkalmazásazonosító URI-ját(api://{clientId}) a Mentés és folytatás lehetőség kiválasztásával. Ez {clientId} az Áttekintés lapról rögzített érték. Ezután adja meg a következő adatokat:

    1. A Hatókör neve mezőbe írja be a következőt Forecast.Read:
    2. A Ki tud hozzájárulni, győződjön meg arról, hogy a Rendszergazdák és a felhasználók lehetőség van kiválasztva.
    3. Rendszergazdai hozzájárulás megjelenítendő neve mezőbe írja be a következőt: .
    4. A Rendszergazdai hozzájárulás leírása mezőbe írja be a következőt Allows the application to read weather forecast data:
    5. A Felhasználói hozzájárulás megjelenítendő név mezőjébe írja be a következőt Read forecast data:
    6. A Felhasználói hozzájárulás leírás mezőjébe írja be a következőt Allows the application to read weather forecast data:
    7. Győződjön meg arról, hogy az állapotengedélyezve van.

  2. Válassza a Hatókör hozzáadása lehetőséget. Ha a hatókör helyesen lett megadva, akkor megjelenik az API-t közzétenő panelen.

    Képernyőkép a mezőértékekről, amikor hozzáadja a hatókört egy API-hoz.

A webalkalmazás regisztrálása

Nem elég webes API-val rendelkeznie, hanem egy webalkalmazásra is szüksége van a webes API eléréséhez szükséges hozzáférési jogkivonat beszerzéséhez.

A webalkalmazás-regisztráció létrehozásához kövesse az alábbi lépéseket:

  1. Válassza a Kezdőlap lehetőséget a kezdőlapra való visszatéréshez. Keresse meg az Entra-azonosítós>alkalmazásregisztrációkat.
  2. Válassza az Új regisztráció lehetőséget.
  3. Adja meg az alkalmazás nevét , például a web-app-calls-web-api nevet.
  4. Támogatott fióktípusok esetén csak ebben a szervezeti címtárban válassza a Fiókok lehetőséget. A különböző fióktípusokkal kapcsolatos információkért válassza a Segítsen választani lehetőséget.
  5. Az Átirányítási URI (nem kötelező) területen válassza a Web lehetőséget, majd írja be http://localhost az URL-cím szövegmezőbe.
  6. Válassza a Regisztráció lehetőséget.
  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 hozzáfér, a felső menü Beállítások ikonjával válthat arra a bérlőre, amelyben regisztrálni szeretné az alkalmazást a Könyvtárak + előfizetések menüből.
  3. Keresse meg az Entra-azonosítós>alkalmazásregisztrációkat.
  4. Válassza az Új regisztráció lehetőséget.
  5. Adja meg az alkalmazás nevét , például a web-app-calls-web-api nevet.
  6. Támogatott fióktípusok esetén csak ebben a szervezeti címtárban válassza a Fiókok lehetőséget. A különböző fióktípusokkal kapcsolatos információkért válassza a Segítsen választani lehetőséget.
  7. Az Átirányítási URI (nem kötelező) területen válassza a Web lehetőséget, majd írja be http://localhost az URL-cím szövegmezőbe.
  8. Válassza a Regisztráció lehetőséget.

Amikor a regisztráció befejeződött, megjelenik az alkalmazás Áttekintés panelje. Jegyezze fel a címtár (bérlő) azonosítóját és az alkalmazás (ügyfél) azonosítóját , amelyet a későbbi lépésekben használni szeretne.

Titkos ügyfélkód hozzáadása

Az ügyfélkód egy sztringérték, amelyet az alkalmazás használhat az identitáshoz, és néha alkalmazásjelszónak is nevezik. A webalkalmazás az ügyfél titkos kódjával igazolja identitását, amikor jogkivonatokat kér.

Az ügyfélkód konfigurálásához kövesse az alábbi lépéseket:

  1. Az Áttekintés panel Kezelés csoportjában válassza a Tanúsítványok & titkos ügyfélkulcsok>új ügyféltitkok> lehetőséget.

  2. Adjon meg egy leírást az ügyfél titkos kódjához, például az Ügyfél titkos kódjához.

  3. Válasszon lejáratot a titkos kódhoz, vagy adjon meg egy egyéni élettartamot.

    • Az ügyfélkód élettartama legfeljebb két évre (24 hónapra) korlátozódik. 24 hónapnál hosszabb egyéni élettartamot nem adhat meg.
    • A Microsoft azt javasolja, hogy 12 hónapnál rövidebb lejárati értéket állítson be.

  4. Válassza a Hozzáadás lehetőséget.

  5. Ügyeljen arra, hogy rögzítse az ügyfél titkos kódjának értékét . Ez a titkos érték soha többé nem jelenik meg a lap elhagyása után.

Az ügyféltitkok biztonságos tárolásával kapcsolatos további információkért tekintse meg a Titkos kulcsok kezelésének ajánlott eljárásait a Key Vaultban.

Engedélyek hozzáadása a webes API eléréséhez

A webes API hatóköreinek megadásával a webalkalmazás beszerezhet egy hozzáférési jogkivonatot, amely tartalmazza a Microsoft Identitásplatform által biztosított hatóköröket. A kódon belül a webes API ezután engedélyalapú hozzáférést biztosíthat az erőforrásaihoz a hozzáférési jogkivonatban található hatókörök alapján.

Az ügyfél webes API-ra vonatkozó engedélyeinek konfigurálásához kövesse az alábbi lépéseket:

  1. Az alkalmazás Áttekintés paneljén, a Kezelés területen válassza az API-engedélyeket>: A> API-k hozzáadása.
  2. Válassza a NewWebAPI1 lehetőséget vagy azt az API-t, amelyhez engedélyeket szeretne hozzáadni.
  3. Az Engedélyek kiválasztása csoportban jelölje be az Forecast.Read melletti jelölőnégyzetet. Előfordulhat, hogy bővítenie kell az Engedélyek listáját. Ez kiválasztja az ügyfélalkalmazásnak a bejelentkezett felhasználó nevében érvényes engedélyeit.
  4. Válassza az Engedélyek hozzáadása lehetőséget a folyamat befejezéséhez.

Miután hozzáadta ezeket az engedélyeket az API-hoz, látnia kell a kiválasztott engedélyeket a Konfigurált engedélyek területen.

A Microsoft Graph API User.Read engedélyét is észreveheti. Ez az engedély automatikusan hozzáadódik egy alkalmazás regisztrálásakor.

A webes API tesztelése

Annak érdekében, hogy az API működőképes legyen, és készen álljon a kérelmek kezelésére, kövesse az alábbi lépéseket:

  1. Klónozza az ms-identity-docs-code-dotnet adattárat .

    git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git

  2. Keresse meg ms-identity-docs-code-dotnet/web-api és nyissa meg appsettings.json, cserélje le a {APPLICATION_CLIENT_ID}{DIRECTORY_TENANT_ID} következő értékeket:

    • {APPLICATION_CLIENT_ID} a webes API-alkalmazás (ügyfél) azonosítója az alkalmazás Áttekintés paneljén.
    • {DIRECTORY_TENANT_ID}az alkalmazás Áttekintés paneljén található webes API Directory (bérlő) azonosítója.

  3. Az alkalmazás elindításához hajtsa végre a következő parancsot:

    dotnet run

  4. A következőhöz hasonló kimenet jelenik meg. Jegyezze fel a portszámot az https://localhost:{port} URL-címben.

    ...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...

A webes API tesztelése

Annak érdekében, hogy az API működőképes legyen, és készen álljon a kérelmek kezelésére, kövesse az alábbi lépéseket:

  1. Keresse meg az oktatóanyagban létrehozott webes API-t: Hozzon létre egy ASP.NET Core-projektet, és konfigurálja az API-t(például NewWebAPILocal), és nyissa meg a mappát.

  2. Nyisson meg egy új terminálablakot, és keresse meg azt a mappát, amelyben a webes API-projekt található.

    1. Az alkalmazás elindításához hajtsa végre a következő parancsot:

      dotnet run

  3. A következőhöz hasonló kimenet jelenik meg. Jegyezze fel a portszámot az https://localhost:{port} URL-címben.

    ...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...

Engedélyezett kérés konfigurálása a webes API-hoz az Insomniaban

Az API-kérésekhez tartozó hozzáférési jogkivonat beszerzéséhez kövesse az alábbi lépéseket:

  1. Indítsa el az Insomnia alkalmazást.

  2. Válassza az Új HTTP-kérés lehetőséget, vagy a Ctrl + N billentyűkombinációval létrehozhat egy új HTTP-kérést.

  3. Az Új kérelem modálisban válassza ki a GET metódust a legördülő listából.

  4. A kérés URL-címéhez adja meg a webes API által közzétett végpont URL-címét. https://localhost:{port}/weatherforecast

  5. Az Auth legördülő menüben válassza az OAuth 2.0 lehetőséget. Ez megjeleníti az OAuth 2.0 űrlapot.

  6. Adja meg a következő értékeket az OAuth 2.0 űrlapon:

    Beállítás Érték
    TÁMOGATÁS TÍPUSA Engedélyezési kód kiválasztása
    ENGEDÉLYEZÉSI URL-cím https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
    Helyettesítse a {tenantId} elemet a címtár (bérlő)azonosítójával
    HOZZÁFÉRÉSI TOKEN URL https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
    Cserélje le a {tenantId}-t a címtár (bérlő) azonosítójával
    ÜGYFÉLAZONOSÍTÓ A webalkalmazás-regisztráció alkalmazás-(ügyfél-) azonosítójának értéke
    TITKOS ÜGYFÉLKÓD A webalkalmazás-regisztráció ügyféltitkának értéke
    ÁTIRÁNYÍTÁS URL Adja meg http://localhostaz átirányítási URL-címet a Microsoft Entra ID azonosítóval regisztrált átirányítási URI-ra.
    Speciális beállítások>HATÓKÖR api://{application_client_id}/Forecast.Read
    Lépjen a webalkalmazás regisztrációjához, a Kezelés területen válassza ki az API-engedélyeket, majd válassza az Előrejelzés.Olvasás lehetőséget.
    Másolja az értéket a szövegmezőbe, amely tartalmazza a Hatókör értéket

Hozzáférési jogkivonat lekérése és kérés küldése a webes API-nak

  1. Miután megadta ezeket az értékeket, válassza a Jogkivonatok lekérése lehetőséget az űrlap végén. Ezzel elindít egy Insomnia böngészőablakot, ahol a felhasználói hitelesítő adatokkal hitelesíthet. Ügyeljen arra, hogy a böngészőben engedélyezze az Insomnia alkalmazás előugró ablakait.
  2. A hitelesítés után válassza a Küldés lehetőséget a kérés védett webes API-végpontra való küldéséhez.

Ha a kérés tartalmaz egy érvényes hozzáférési jogkivonatot, a várt válasz 200 OK, a következőhöz hasonló kimenettel:

[
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": -16,
    "summary": "Scorching",
    "temperatureF": 4
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 1,
    "summary": "Sweltering",
    "temperatureF": 33
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 26,
    "summary": "Freezing",
    "temperatureF": 78
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 54,
    "summary": "Mild",
    "temperatureF": 129
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 11,
    "summary": "Bracing",
    "temperatureF": 51
  }
]

Kapcsolódó tartalom

Az OAuth 2.0 engedélyezési kódfolyamatával és alkalmazástípusával kapcsolatos további információkért lásd:

  • Last updated on