Volání webového rozhraní API ASP.NET Core s režimu spánku

Článek
01/29/2025

V tomto článku se dozvíte, jak volat chráněné webové rozhraní API ASP.NET Core pomocí režimu spánku. Spánku je aplikace, která umožňuje odesílat požadavky HTTP webovému rozhraní API k otestování zásad autorizace a řízení přístupu (ověřování). 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í režimu spánku.

V tomto článku se dozvíte, jak volat chráněné webové rozhraní API ASP.NET Core pomocí režimu spánku. Spánku je aplikace, která umožňuje odesílat požadavky HTTP webovému rozhraní API k otestování zásad autorizace a řízení přístupu (ověřování). 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í režimu spánku.

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 spánku. Pomocí režimu spánku získáte přístupový token pro požadavky rozhraní API.
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ů:
Stáhněte a nainstalujte spánku.

Registrace aplikace

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:

Přihlaste se do Centra pro správu Microsoft Entra jako alespoň vývojář aplikací.
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á.
Přejděte k aplikacím>Registrace aplikací.
Vyberte Nová registrace.
Zadejte název aplikace, například NewWebAPI1.
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.
Vyberte Zaregistrovat.
Po dokončení registrace se zobrazí podokno Přehled aplikace. Poznamenejte si ID adresáře (tenanta) a ID aplikace (klienta), které se použije v dalších krocích.

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

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 Read forecast data
4. Do pole Popis souhlasu 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 Allows the application to read weather forecast data
7. Ujistěte se, že je stav nastavený na Povoleno.
Vyberte Přidat rozsah. Pokud byl obor zadán správně, zobrazí se v podokně Zveřejnit rozhraní API .

Registrace webové aplikace

Nestačí mít webové rozhraní API, k získání přístupového tokenu k webovému rozhraní API potřebujete také webovou aplikaci.

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

Výběrem možnosti Domů se vrátíte na domovskou stránku. Přejděte k aplikacím>Registrace aplikací.
Vyberte Nová registrace.
Zadejte název aplikace, například web-app-calls-web-api.
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 .
V části Identifikátor URI přesměrování (volitelné) vyberte Web a zadejte http://localhost do textového pole adresy URL.
Vyberte Zaregistrovat.

Přihlaste se do Centra pro správu Microsoft Entra jako alespoň vývojář aplikací.
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á.
Přejděte k aplikacím>Registrace aplikací.
Vyberte Nová registrace.
Zadejte název aplikace, například web-app-calls-web-api.
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 .
V části Identifikátor URI přesměrování (volitelné) vyberte Web a zadejte http://localhost do textového pole adresy URL.
Vyberte Zaregistrovat.

Po dokončení registrace se zobrazí podokno Přehled aplikace. 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:

V podokně Přehled v části Spravovat vyberte > klienta.
Přidejte popis tajného klíče klienta, například tajný klíč klienta.
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ů.
Vyberte Přidat.
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í.

Další informace o bezpečném ukládání tajného klíče klienta najdete v tématu Osvědčené postupy pro správu tajných kódů ve službě Key Vault.

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

Zadáním oborů webového rozhraní API 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í klienta k webovému rozhraní API:

V podokně Přehled vaší aplikace v části Spravovat vyberte oprávnění>>rozhraní API, která používá moje organizace.
Vyberte NewWebAPI1 nebo rozhraní API, ke kterému chcete přidat oprávnění.
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.
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

Pokud chcete zajistit, aby vaše rozhraní API bylo funkční a připravené ke zpracování požadavků, postupujte takto:

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

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

Přejděte na ms-identity-docs-code-dotnet/web-api a otevřete appsettings.json, nahraďte a {APPLICATION_CLIENT_ID} nahraďte {DIRECTORY_TENANT_ID} následujícími hodnotami:
- {APPLICATION_CLIENT_ID}je ID aplikace webového rozhraní API (klienta) v podokně Přehled aplikace.
- {DIRECTORY_TENANT_ID}je ID adresáře webového rozhraní API (tenanta) v podokně Přehled aplikace.
Spuštěním následujícího příkazu spusťte aplikaci:
```
dotnet run
```
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

Pokud chcete zajistit, aby vaše rozhraní API bylo funkční a připravené ke zpracování požadavků, postupujte takto:

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.
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
- .NET 7.0
1. Spuštěním následujícího příkazu spusťte aplikaci:
```
dotnet run
```
1. Otevřete nový terminál a spuštěním následujícího příkazu spusťte aplikaci v https profilu:
```
dotnet run -launch-profile https`
```
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}
...
```

Konfigurace autorizovaného požadavku na webové rozhraní API v režimu spánku

Pokud chcete získat přístupový token pro požadavky rozhraní API, postupujte takto:

Spusťte aplikaci Režimu spánku.
Vyberte Nový požadavek HTTP nebo můžete vytvořit nový požadavek HTTP pomocí ctrl + N .
V modálu New Request vyberte z rozevíracího seznamu metodu GET.
Jako adresu URL požadavku zadejte adresu URL koncového bodu vystaveného webovým rozhraním API. https://localhost:{port}/weatherforecast
V rozevírací nabídce Ověřování vyberte OAuth 2.0. Zobrazí se formulář OAuth 2.0.

Do formuláře OAuth 2.0 zadejte následující hodnoty:

Nastavení	Hodnota
TYP GRANTU	Výběr autorizačního kódu
ADRESA URL AUTORIZACE	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize` Nahradit `{tenantId}` ID adresáře (tenanta)
ADRESA URL PŘÍSTUPOVÉHO TOKENU	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token` Nahradit `{tenantId}` ID adresáře (tenanta)
ID KLIENTA	Hodnota ID aplikace (klienta) registrace webové aplikace
TAJNÝ KLÍČ KLIENTA	Hodnota tajného klíče klienta registrace webové aplikace
ADRESA URL PRO PŘESMĚROVÁNÍ	Zadejte `http://localhost`, který nastaví adresu URL REDIRECT na identifikátor URI přesměrování zaregistrovaný v Microsoft Entra ID.
Rozsah rozšířených možností>	`api://{application_client_id}/Forecast.Read` Přejděte do registrace webové aplikace v části Spravovat, vyberte oprávnění rozhraní API a pak vyberte Forecast.Read. Zkopírujte hodnotu do textového pole, která obsahuje hodnotu Oboru .

Získání přístupového tokenu a odeslání požadavku do webového rozhraní API

Po zadání těchto hodnot vyberte na konci formuláře tokeny Fetch. Tím se spustí okno prohlížeče režimu spánku, ve kterém se ověřujete pomocí přihlašovacích údajů uživatele. Nezapomeňte povolit automaticky otevíraná okna z aplikace Režimu spánku v prohlížeči.
Po ověření vyberte Odeslat a odešlete požadavek do koncového bodu chráněného webového rozhraní API.

S platným přístupovým tokenem zahrnutým v požadavku je očekávaná odpověď 200 OK s výstupem podobným:

[
  {
    "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
  }
]

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

Sdílet prostřednictvím

Volání webového rozhraní API ASP.NET Core s režimu spánku

Požadavky