Volání webového rozhraní API ASP.NET Core pomocí cURL

V tomto článku se dozvíte, jak volat chráněné webové rozhraní API ASP.NET Core pomocí adresy URL klienta (cURL). cURL je nástroj příkazového řádku, který vývojáři používají k přenosu dat do a ze serveru. V tomto článku zaregistrujete webovou aplikaci a webové rozhraní API v tenantovi. Webová aplikace se používá k získání přístupového tokenu vygenerovaného platformou Microsoft Identity Platform. Dále pomocí tokenu provedete autorizované volání webového rozhraní API pomocí cURL.

V tomto článku se dozvíte, jak volat chráněné webové rozhraní API ASP.NET Core pomocí adresy URL klienta (cURL). cURL je nástroj příkazového řádku, který vývojáři používají k přenosu dat do a ze serveru. Následně podle kurzu: Implementujte chráněný koncový bod do svého rozhraní API, kde jste vytvořili chráněné API, musíte zaregistrovat webovou aplikaci na platformě Microsoft Identity pro generování přístupového tokenu. Dále pomocí tokenu provedete autorizované volání rozhraní API pomocí cURL.

Požadavky

• Účet Azure s aktivním předplatným. Vytvořte si bezplatný účet.
• Tento účet Azure musí mít oprávnění ke správě aplikací. Kterákoli z následujících rolí Microsoft Entra zahrnuje požadovaná oprávnění:
  • Správce aplikace
  • Vývojář aplikace
  • Správce cloudové aplikace
• Stáhněte a nainstalujte cURL do počítače pracovní stanice.
• Minimální požadavek pro .NET 8.0 SDK.

• Účet Azure s aktivním předplatným. Vytvořte si bezplatný účet.
• Tento účet Azure musí mít oprávnění ke správě aplikací. Kterákoli z následujících rolí Microsoft Entra zahrnuje požadovaná oprávnění:
  • Správce aplikace
  • Vývojář aplikace
  • Správce cloudové aplikace
• Dokončení série kurzů:
  • Kurz: Registrace webového rozhraní API na platformě Microsoft Identity Platform
  • Kurz: Vytvoření a konfigurace projektu ASP.NET Core pro ověřování
  • Kurz: Implementace chráněného koncového bodu do vašeho rozhraní API
• Stáhněte a nainstalujte cURL do počítače pracovní stanice.

Registrace aplikace na platformě Microsoft Identity Platform

Platforma Microsoft Identity Platform vyžaduje, aby byla vaše aplikace zaregistrovaná před poskytováním služeb pro správu identit a přístupu. Registrace aplikace umožňuje zadat název a typ aplikace a cílovou skupinu přihlašování. Cílová skupina přihlašování určuje, jaké typy uživatelských účtů se můžou přihlásit k dané aplikaci.

Registrace webového rozhraní API

Pokud chcete vytvořit registraci webového rozhraní API, postupujte takto:

1. Přihlaste se do Centra pro správu Microsoft Entra jako alespoň vývojář aplikací.

2. Pokud máte přístup k více tenantům, pomocí ikony Nastavení v horní nabídce přepněte na tenanta, ve kterém chcete aplikaci zaregistrovat z nabídky Adresáře a předplatná.

3. Přejděte na Entra ID>registrace aplikací.

4. Vyberte Nová registrace.

5. Zadejte název aplikace, například NewWebAPI1.

6. U podporovaných typů účtů vyberte Pouze účty v tomto organizačním adresáři. Pokud chcete získat informace o různých typech účtů, vyberte možnost Pomoc s výběrem možnosti.

7. Vyberte Zaregistrovat.

   

8. Po dokončení registrace se zobrazí podokno Přehled aplikace. Poznamenejte si ID adresáře (tenanta) a ID aplikace (klienta), které se má použít ve zdrojovém kódu aplikace.

   

Poznámka:

Podporované typy účtů je možné změnit odkazem na úpravu účtů podporovaných aplikací.

Zveřejnit rozhraní API

Po registraci rozhraní API můžete nakonfigurovat jeho oprávnění definováním oborů, které rozhraní API zveřejňuje klientským aplikacím. Klientské aplikace požadují oprávnění k provádění operací předáním přístupového tokenu spolu s požadavky na chráněné webové rozhraní API. Webové rozhraní API pak provede požadovanou operaci pouze v případě, že přístupový token, který přijímá, je platný.

1. V části Spravovat vyberte Zveřejnit rozhraní API > Přidat obor. Výběrem možnosti Uložit a pokračovat přijměte navrhovaný (api://{clientId}) ID aplikace. Jedná se {clientId} o hodnotu zaznamenanou ze stránky Přehled . Pak zadejte následující informace:

   1. Jako název oboru zadejte Forecast.Read.
   2. U možnosti Kdo může souhlasit, ujistěte se, že je vybraná možnost Správci a uživatelé .
   3. Do pole Zobrazovaný název souhlasu správce zadejte .
   4. Do pole Popis souhlasu zadejte .
   5. Do pole Jméno souhlasu uživatele zadejte Read forecast data.
   6. Do pole Popis souhlasu zadejte .
   7. Ujistěte se, že Stav je nastavený na Povoleno.

2. Vyberte Přidat obor. Pokud byl obor zadán správně, je uvedený v podokně Zveřejnit rozhraní API .

   

Registrace webové aplikace

Webové rozhraní API ale nestačí, protože webová aplikace je také potřebná k získání přístupového tokenu pro přístup k webovému rozhraní API, které jste vytvořili.

Pokud chcete vytvořit registraci webové aplikace, postupujte takto:

1. Vyberte Domů, abyste se vrátili na domovskou stránku. Přejděte na Entra ID>registrace aplikací.
2. Vyberte Nová registrace.
3. Zadejte název aplikace, například web-app-calls-web-api.
4. U podporovaných typů účtů vyberte Pouze účty v tomto organizačním adresáři. Pokud chcete získat informace o různých typech účtů, vyberte možnost Pomoc s výběrem.
5. V části URI přesměrování (volitelné) vyberte možnost Web a poté zadejte do textového pole URL http://localhost.
6. Vyberte Zaregistrovat.

1. Přihlaste se do Centra pro správu Microsoft Entra jako alespoň vývojář aplikací.
2. Pokud máte přístup k více tenantům, pomocí ikony Nastavení v horní nabídce přepněte na tenanta, ve kterém chcete aplikaci zaregistrovat z nabídky Adresáře a předplatná.
3. Přejděte na Entra ID>registrace aplikací.
4. Vyberte Nová registrace.
5. Zadejte název aplikace, například web-app-calls-web-api.
6. U podporovaných typů účtů vyberte Pouze účty v tomto organizačním adresáři. Pokud chcete získat informace o různých typech účtů, vyberte možnost Pomoc s výběrem.
7. V části URI přesměrování (volitelné) vyberte možnost Web a poté zadejte do textového pole URL http://localhost.
8. Vyberte Zaregistrovat.

Po dokončení registrace se registrace aplikace zobrazí v podokně Přehled . Poznamenejte si ID adresáře (tenanta) a ID aplikace (klienta), které se použije v dalších krocích.

Přidání tajného klíče klienta

Tajný klíč klienta je řetězcová hodnota, kterou může aplikace použít k identitě samotné, a někdy se označuje jako heslo aplikace. Webová aplikace používá tajný klíč klienta k prokázání své identity při žádosti o tokeny.

Ke konfiguraci tajného klíče klienta postupujte takto:

1. V podokně Přehled v části Spravovat vyberte Certifikáty a tajemství> tajemství klienta>Nové tajemství klienta.

2. Přidejte popis tajného klíče klienta, například tajný klíč klienta.

3. Vyberte vypršení platnosti tajného kódu nebo zadejte vlastní životnost.

   • Životnost tajného klíče klienta je omezená na dva roky (24 měsíců) nebo méně. Nemůžete zadat vlastní životnost delší než 24 měsíců.
   • Microsoft doporučuje nastavit hodnotu vypršení platnosti kratší než 12 měsíců.

4. Vyberte Přidat.

5. Nezapomeňte zaznamenat hodnotu tajného klíče klienta. Tato hodnota tajného kódu se po opuštění této stránky už nikdy nezobrazí .

Přidání oprávnění aplikace pro povolení přístupu k webovému rozhraní API

Zadáním oborů webového rozhraní API v registraci webové aplikace může webová aplikace získat přístupový token obsahující obory poskytované platformou Microsoft Identity Platform. V rámci kódu pak webové API může poskytnout přístup ke svým prostředkům na základě oprávnění určených rozsahy nalezenými v přístupovém tokenu.

Pomocí následujícího postupu nakonfigurujte oprávnění webové aplikace k webovému rozhraní API:

1. V podokně Přehled vaší webové aplikace (web-app-that-calls-web-api) vyberte v části Správa oprávněníPřidat>rozhraní> API, kterápoužívá moje organizace.
2. Vyberte NewWebAPI1 nebo rozhraní API, ke kterému chcete přidat oprávnění.
3. V části Vybrat oprávnění zaškrtněte políčko vedle položky Forecast.Read. Možná budete muset rozbalit seznam oprávnění . Tím se vyberou oprávnění, která by klientská aplikace měla mít jménem přihlášeného uživatele.
4. Výběrem možnosti Přidat oprávnění dokončete proces.

Po přidání těchto oprávnění do rozhraní API by se měla zobrazit vybraná oprávnění v části Nakonfigurovaná oprávnění.

Můžete si také všimnout oprávnění User.Read pro rozhraní Microsoft Graph API. Toto oprávnění se přidá automaticky při registraci aplikace.

Testování webového rozhraní API

1. Naklonujte úložiště ms-identity-docs-code-dotnet .

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

2. Přejděte do ms-identity-docs-code-dotnet/web-api složky a otevřete ./appsettings.json soubor, nahraďte {APPLICATION_CLIENT_ID} a {DIRECTORY_TENANT_ID} tímto:

   • {APPLICATION_CLIENT_ID} je webové rozhraní API aplikace ID (klienta) v podokně Přehled registrací aplikací.
   • {DIRECTORY_TENANT_ID}je ID adresáře webového rozhraní API (tenanta) v registracích aplikací v podokně Přehled aplikace.

3. Spuštěním následujícího příkazu spusťte aplikaci:

   .NET 6.0

   dotnet run
   

   .NET 7.0

   dotnet run --launch-profile https
   

4. Zobrazí se výstup podobný následujícímu. Poznamenejte si číslo portu v https://localhost:{port} adrese URL.

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

Testování webového rozhraní API

1. Přejděte na webové rozhraní API vytvořené v kurzu: Vytvořte projekt ASP.NET Core a nakonfigurujte rozhraní API, například NewWebAPILocal, a otevřete složku.

2. Otevřete nové okno terminálu a přejděte do složky, ve které se nachází projekt webového rozhraní API.

.NET 6.0

1. Spuštěním následujícího příkazu spusťte aplikaci:

   dotnet run
   

.NET 7.0

1. Spuštěním následujícího příkazu spusťte aplikaci v https profilu:

   dotnet run --launch-profile https
   

1. Zobrazí se výstup podobný následujícímu. Poznamenejte si číslo portu v https://localhost:{port} adrese URL.

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

Žádost o autorizační kód

Tok autorizačního kódu začíná klientem, který uživatele nasměruje na /authorize koncový bod. V této žádosti klient žádá uživatele o oprávnění Forecast.Read.

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. Zkopírujte adresu URL, nahraďte následující parametry a vložte ji do prohlížeče:

   • {tenant_id} je ID adresáře (tenanta) webové aplikace.
   • {web-app-calls-web-api_application_client_id}je ID aplikace (klienta) v podokně Přehled webové aplikace (web-app-calls-web-api).
   • {web_API_application_client_id}je ID aplikace (klienta) v podokně Přehled webového rozhraní API (NewWebAPI1).

2. Přihlaste se jako uživatel v tenantovi Microsoft Entra, ve kterém jsou aplikace zaregistrované. V případě potřeby odsouhlaste všechny žádosti o přístup.

3. Váš prohlížeč je přesměrován na http://localhost/. Podívejte se na navigační lištu svého prohlížeče a zkopírujte {authorization_code}, které použijete v následujících krocích. Adresa URL má formu následujícího fragmentu kódu:

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

Získání přístupového tokenu pomocí autorizačního kódu a cURL

CURL se teď dá použít k vyžádání přístupového tokenu z platformy Microsoft Identity Platform.

1. Zkopírujte příkaz cURL v následujícím fragmentu kódu. Nahraďte hodnoty v závorkách následujícími parametry do terminálu. Nezapomeňte odebrat závorky:

   Udeřit

   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}'
   

   Příkazový řádek windows

   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} je ID adresáře (tenanta) webové aplikace.
   • client_id={web-app-calls-web-api_application_client_id}, session_state={web-app-calls-web-api_application_client_id} je ID aplikace (klienta) v podokně Přehled webové aplikace (web-app-calls-web-api).
   • api://{web_API_application_client_id}/Forecast.Readje ID aplikace (klienta) v podokně Přehled webového rozhraní API (NewWebAPI1).
   • code={authorization_code} je autorizační kód přijatý v žádosti o autorizační kód. Díky tomu může nástroj cURL požádat o přístupový token.
   • client_secret={client_secret} je tajný klíč klienta, jehož hodnota je uvedena v Přidat tajný klíč klienta.

2. Spusťte příkaz cURL a pokud jste zadali správně, měli byste obdržet odpověď JSON podobnou následujícímu výstupu:

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

Volání webového rozhraní API s přístupovým tokenem

Spuštěním předchozího příkazu cURL platforma Microsoft Identity Platform poskytla přístupový token. Získaný token se teď dá použít jako nosný v požadavku HTTP k volání webového rozhraní API.

1. Pokud chcete volat webové rozhraní API, zkopírujte následující příkaz cURL, nahraďte následující hodnoty v závorkách a vložte ho do terminálu:

   curl -X GET https://localhost:{port}/weatherforecast -ki \
   -H 'Content-Type: application/json' \
   -H "Authorization: Bearer {access_token}"
   

   • {access_token} hodnota přístupového tokenu zaznamenaná z výstupu JSON v předchozí části.
   • {port} číslo portu z webového rozhraní API zaznamenané při spuštění rozhraní API v terminálu. Ujistěte se, že se jedná o https číslo portu.

2. S platným přístupovým tokenem zahrnutým v požadavku je HTTP/2 200 očekávaná odpověď s výstupem podobným následujícímu výstupu:

   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}]
   

Další kroky

Další informace o toku autorizačního kódu OAuth 2.0 a typech aplikací najdete tady:

• Platforma Microsoft identity a tok autorizačního kódu OAuth 2.0
• Typy aplikací pro platformu Microsoft Identity Platform