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

  • Cikk

Ez a cikk bemutatja, hogyan hívhat meg védett ASP.NET Core webes API-t ügyfél URL-cím (cURL) használatával. A cURL egy parancssori eszköz, amellyel a fejlesztők adatokat továbbítanak egy kiszolgálóra és onnan. 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 a cURL használatával.

Ez a cikk bemutatja, hogyan hívhat meg védett ASP.NET Core webes API-t ügyfél URL-cím (cURL) használatával. A cURL egy parancssori eszköz, amellyel a fejlesztők adatokat továbbítanak egy kiszolgálóra és onnan. 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ásplatform 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-hoz a cURL használatával.

Előfeltételek

  • Egy Azure-fiók, aktív előfizetéssel. Fiók ingyenes létrehozása.
  • 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 a cURL-t a munkaállomás számítógépén.
  • A .NET 6.0 SDK minimális követelménye.

Alkalmazás regisztrálása a Microsoft Identity Platformon

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

Tipp.

A cikkben szereplő lépések a portáltól függően kissé eltérhetnek.

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ü Gépház ikonjávalvá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 identitásalkalmazásokat>> Alkalmazásregisztrációk.

  4. Új regisztráció kiválasztása.

  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 Súgó kiválasztása lehetőséget.

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

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

  8. 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 .

    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 területen válassza az API-k> 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 Rendszergazda és a felhasználók lehetőség van kiválasztva.
    3. A Rendszergazda hozzájárulás megjelenítendő neve mezőbe írja be a következőtRead forecast data:
    4. A Rendszergazda hozzájárulás leírási mezőjébe írja be a következőtAllows 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őtRead forecast data:
    6. A Felhasználói hozzájárulás leírás mezőjébe írja be a következőtAllows the application to read weather forecast data:
    7. Győződjön meg arról, hogy az állapot engedélyezve van.

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

    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

A webes API használata azonban nem elegendő, mivel egy webalkalmazásra is szükség van a létrehozott 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 identitásalkalmazásokat>> Alkalmazásregisztrációk.
  2. Új regisztráció kiválasztása.
  3. Adja meg az alkalmazás nevét, példáulweb-app-calls-web-api.
  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 Súgó kiválasztása 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 ki a pénztárgépet.
  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ü Gépház ikonjávalvá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 identitásalkalmazásokat>> Alkalmazásregisztrációk.
  4. Új regisztráció kiválasztása.
  5. Adja meg az alkalmazás nevét, például web-app-calls-web-api.
  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 Súgó kiválasztása 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 ki a pénztárgépet.

Ha a regisztráció befejeződött, az alkalmazásregisztráció megjelenik az Áttekintés panelen. 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.

Alkalmazásengedélyek hozzáadása a webes API-hoz való hozzáférés engedélyezéséhez

A webalkalmazás-regisztrációban megadott webes API-hatókörök megadásával a webalkalmazás beszerezheti a Microsoft Identitásplatform által biztosított hatóköröket tartalmazó hozzáférési jogkivonatot. 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.

A webalkalmazás-engedélyek webes API-hoz való konfigurálásához kövesse az alábbi lépéseket:

  1. A webalkalmazás Áttekintés paneljén (web-app-that-calls-web-api) válassza a Kezelés területen az API-engedélyek>hozzáadása engedély>hozzáadása Saját API-k lehetőséget.
  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 ki kell bontania az engedélylistá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

  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. Lépjen a mappába ms-identity-docs-code-dotnet/web-api , és nyissa meg ./appsettings.json a fájlt, cserélje le a {APPLICATION_CLIENT_ID} következőt {DIRECTORY_TENANT_ID} :

    • {APPLICATION_CLIENT_ID}a webes API-alkalmazás (ügyfél) azonosítója az alkalmazás Áttekintés paneljén Alkalmazásregisztrációk.
    • {DIRECTORY_TENANT_ID}az alkalmazás Áttekintés paneljének Alkalmazásregisztrációk webes API-címtár (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

  1. Lépjen az oktatóanyagban létrehozott webes API-ra: 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

  1. 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élyezési kód kérése

Az engedélyezési kód folyamata azzal kezdődik, hogy az ügyfél a végponthoz irányítja a felhasználót /authorize . Ebben a kérésben az ügyfél engedélyt kér a Forecast.Read felhasználótól.

https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize?client_id={web-app-calls-web-api_application_client_id}&response_type=code&redirect_uri=http://localhost&response_mode=query&scope=api://{web_API_application_client_id}/Forecast.Read

  1. Másolja ki az URL-címet, cserélje le a következő paramétereket, és illessze be a böngészőbe:

    • {tenant_id} A webalkalmazás címtárának (bérlői) azonosítója.
    • {web-app-calls-web-api_application_client_id} az alkalmazás (ügyfél) azonosítója a webalkalmazás (web-app-calls-web-api) Áttekintés paneljén.
    • {web_API_application_client_id}A webes API (NewWebAPI1) Áttekintés panelén található alkalmazás (ügyfél) azonosítója.

  2. Jelentkezzen be felhasználóként abban a Microsoft Entra-bérlőben, amelyben az alkalmazások regisztrálva vannak. Szükség esetén hozzájárulás a hozzáférési kérelmekhez.

  3. A böngésző a következőre http://localhost/lesz átirányítva: . Tekintse meg a böngésző navigációs sávját, és másolja ki a {authorization_code} használni kívánt elemet az alábbi lépésekben. Az URL-cím a következő kódrészlet formájában történik:

    http://localhost/?code={authorization_code}

Hozzáférési jogkivonat beszerzése engedélyezési kód és cURL használatával

A cURL mostantól használható hozzáférési jogkivonat lekérésére a Microsoft Identitásplatform.

  1. Másolja a cURL parancsot a következő kódrészletbe. Cserélje le a zárójelben lévő értékeket a terminál következő paramétereire. Mindenképpen távolítsa el a zárójeleket:

    curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token \
-d 'client_id={web-app-calls-web-api_application_client_id}' \
-d 'api://{web_API_application_client_id}/Forecast.Read' \
-d 'code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}' \
-d 'redirect_uri=http://localhost' \
-d 'grant_type=authorization_code' \
-d 'client_secret={client_secret}'
    • {tenant_id} A webalkalmazás címtárának (bérlői) azonosítója.
    • client_id={web-app-calls-web-api_application_client_id}, és session_state={web-app-calls-web-api_application_client_id} az alkalmazás (ügyfél) azonosítója a webalkalmazás (web-app-calls-web-api) Áttekintés paneljén.
    • api://{web_API_application_client_id}/Forecast.ReadA webes API (NewWebAPI1) Áttekintés panelén található alkalmazás (ügyfél) azonosítója.
    • code={authorization_code} az engedélyezési kód kérésében kapott engedélyezési kód. Ez lehetővé teszi, hogy a cURL eszköz hozzáférési jogkivonatot kérjen.
    • client_secret={client_secret}az ügyfél titkos kódjának az Ügyfélkód hozzáadása elemben rögzített értéke.

  2. Futtassa a cURL parancsot, és ha helyesen adta meg, a következő kimenethez hasonló JSON-választ kell kapnia:

    {
   "token_type": "Bearer",
   "scope": "api://{web_API_application_client_id}/Forecast.Read",
   "expires_in": 3600,
   "ext_expires_in": 3600,
   "access_token": "{access_token}"
}

Webes API meghívása hozzáférési jogkivonattal

Az előző cURL-parancs futtatásával a Microsoft Identitásplatform biztosított egy hozzáférési jogkivonatot. A beszerzett jogkivonat mostantól tulajdonosként is használható a webes API meghívására szolgáló HTTP-kérésben.

  1. A webes API meghívásához másolja a következő cURL-parancsot, cserélje le a következő értékeket zárójelben, és illessze be a terminálba:

    curl -X GET https://localhost:{port}/weatherforecast -ki \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}"
    • {access_token} az előző szakaszban szereplő JSON-kimenetből rögzített hozzáférési jogkivonat értéke.
    • {port} a webes API portszáma, amelyet az API terminálban való futtatásakor rögzítettek. Győződjön meg arról, hogy ez a https portszám.

  2. Ha a kérés tartalmaz egy érvényes hozzáférési jogkivonatot, a várt válasz a következő kimenethez hasonló kimenettel jelenik HTTP/2 200 meg:

    HTTP/2 200
content-type: application/json; charset=utf-8
date: Day, DD Month YYYY HH:MM:SS
server: Kestrel
[{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":36,"summary":"Hot","temperatureF":96},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":43,"summary":"Warm","temperatureF":109},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":18,"summary":"Warm","temperatureF":64},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":50,"summary":"Chilly","temperatureF":121},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":3,"summary":"Bracing","temperatureF":37}]

Következő lépések

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