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. Dále v kurzu : Implementujte do svého rozhraní API chráněný koncový bod, ve kterém jste vytvořili chráněné rozhraní API, musíte zaregistrovat webovou aplikaci na platformě Microsoft Identity Platform, aby se vygeneroval přístupový token. Dále pomocí tokenu provedete autorizované volání rozhraní API pomocí cURL.

Požadavky

• Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
• Tento účet Azure musí mít oprávnění ke správě aplikací. Mezi následující role Microsoft Entra patří 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 sady .NET 8.0 SDK.

• Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
• Tento účet Azure musí mít oprávnění ke správě aplikací. Mezi následující role Microsoft Entra patří 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

Tip

Postup v tomto článku se může mírně lišit v závislosti na portálu, od který začínáte.

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 k aplikacím> identit>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řejnění 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ý identifikátor URI (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 Read forecast data.
   4. Do pole Popis souhlasu správce zadejte Allows the application to read weather forecast data.
   5. Do pole Zobrazované jméno souhlasu uživatele zadejte Read forecast data.
   6. Do pole Popis souhlasu uživatele zadejte Allows the application to read weather forecast data.
   7. Ujistěte se, že je stav nastavený na Povoleno.

2. Vyberte Přidat rozsah. Pokud byl obor zadán správně, bude 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. Výběrem možnosti Domů se vrátíte na domovskou stránku. Přejděte k aplikacím> identit>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 Nápověda pro výběr .
5. V části Identifikátor URI přesměrování (volitelné) vyberte Web a zadejte http://localhost do textového pole adresy URL.
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 k aplikacím> identit>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 Nápověda pro výběr .
7. V části Identifikátor URI přesměrování (volitelné) vyberte Web a zadejte http://localhost do textového pole adresy URL.
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 tajné klíče>>klienta Nové tajné klíče 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 kódu pak webové rozhraní API může poskytnout přístup na základě oprávnění k prostředkům na základě rozsahů nalezených 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 ho{APPLICATION_CLIENT_ID}:{DIRECTORY_TENANT_ID}

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

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 k webovému rozhraní API vytvořenému 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 požádá Forecast.Read o oprávnění od uživatele.

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 webové aplikace (tenanta).
   • {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č bude přesměrován na http://localhost/. Projděte si navigační panel prohlížeče a zkopírujte ho {authorization_code} , který chcete použít 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 webové aplikace (tenanta).
   • client_id={web-app-calls-web-api_application_client_id}a je ID aplikace (klienta) v podokně Přehled webové aplikace (web-app-calls-web-api). session_state={web-app-calls-web-api_application_client_id}
   • 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 hodnota tajného klíče klienta zaznamenaná v části 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:

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