Rychlý start: Ochrana webového rozhraní API ASP.NET Core pomocí platformy Microsoft Identity Platform

Článek
02/14/2024

Vítejte! Pravděpodobně to není stránka, kterou jste očekávali. Zatímco pracujeme na opravě, měl by vás tento odkaz dostat na správný článek:

Rychlý start: Volání webového rozhraní API ASP.NET Core, které je chráněné platformou Microsoft Identity Platform

Omlouváme se za nepříjemnosti a vážíme si vaší trpělivosti, zatímco pracujeme na vyřešení tohoto problému.

Následující rychlý start používá ukázku kódu webového rozhraní API ASP.NET Core, která ukazuje, jak omezit přístup k prostředkům na autorizované účty. Ukázka podporuje autorizaci osobních účtů Microsoft a účtů v jakékoli organizaci Microsoft Entra.

Požadavky

Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
Tenant Microsoft Entra
Minimální požadavek sady .NET 6.0 SDK
Visual Studio 2022 nebo Visual Studio Code

Krok 1: Registrace aplikace

Nejprve zaregistrujte webové rozhraní API v tenantovi Microsoft Entra a přidejte rozsah podle následujících kroků:

Přihlaste se do Centra pro správu Microsoft Entra jako alespoň správce aplikací.
Přejděte k aplikacím> identit>Registrace aplikací.
Vyberte Nová registrace.
Jako Název zadejte název aplikace. Zadejte například AspNetCoreWebApi-Quickstart. Uživatelé aplikace uvidí tento název a můžete ho později změnit.
Vyberte Zaregistrovat.
V části Spravovat vyberte Zveřejnit rozhraní API>Přidat obor. U identifikátoru URI ID aplikace přijměte výchozí nastavení výběrem možnosti Uložit a pokračovat a zadejte následující podrobnosti:

Název oboru: access_as_user
Kdo může souhlasit?: Správci a uživatelé
Zobrazovaný název souhlasu správce: Access AspNetCoreWebApi-Quickstart
Popis souhlasu správce: Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.
Zobrazované jméno souhlasu uživatele: Access AspNetCoreWebApi-Quickstart
Popis souhlasu uživatele: Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
Stav: Povoleno

Chcete-li dokončit přidání oboru, vyberte Přidat obor .

Krok 2: Stažení projektu ASP.NET Core

Stáhněte si řešení ASP.NET Core z GitHubu.

Poznámka:

Ukázka kódu aktuálně cílí na ASP.NET Core 3.1. Ukázku je možné aktualizovat tak, aby používala .NET Core 6.0 a je popsána v následujících krocích: Aktualizujte vzorový kód na ASP.NET Core 6.0. Tento rychlý start bude v blízké budoucnosti zastaralý a bude aktualizován tak, aby používal .NET 6.0.

Krok 3: Konfigurace projektu ASP.NET Core

V tomto kroku se vzorový kód nakonfiguruje tak, aby fungoval s registrací aplikace, která byla vytvořena dříve.

Extrahujte soubor .zip do místní složky, která je blízko kořenového adresáře disku, aby nedocházelo k chybám způsobeným omezením délky cesty ve Windows. Extrahujte například do C:\Azure-Samples.
Otevřete řešení ve složce webapi v editoru kódu.
V appsettings.json nahraďte hodnoty ClientIda TenantId.
```
"ClientId": "Enter_the_Application_Id_here",
"TenantId": "Enter_the_Tenant_Info_Here"
```
- Enter_the_Application_Id_Here je ID aplikace (klienta) registrované aplikace.
- Nahraďte Enter_the_Tenant_Info_Here některou z následujících možností:
  - Pokud aplikace podporuje pouze účty v tomto organizačním adresáři, nahraďte tuto hodnotu ID adresáře (tenanta) ID (identifikátor GUID) nebo názvem tenanta (například contoso.onmicrosoft.com). ID adresáře (tenanta) najdete na stránce Přehled aplikace.
  - Pokud aplikace podporuje účty v libovolném organizačním adresáři, nahraďte tuto hodnotu organizationshodnotou .
  - Pokud aplikace podporuje všechny uživatele účtu Microsoft, ponechte tuto hodnotu jako common.

V tomto rychlém startu neměňte žádné jiné hodnoty v souboru appsettings.json .

Krok 4: Aktualizace ukázkového kódu na ASP.NET Core 6.0

Pokud chcete tuto ukázku kódu aktualizovat tak, aby cílila na ASP.NET Core 6.0, postupujte takto:

Otevřít webapi.csproj
Odeberte následující řádek:

<TargetFramework>netcoreapp3.1</TargetFramework>

Na jeho místo přidejte následující řádek:

<TargetFramework>netcoreapp6.0</TargetFramework>

Tento krok zajistí, že ukázka cílí na architekturu .NET Core 6.0.

Krok 5: Spuštění ukázky

Otevřete terminál a přejděte do složky projektu.
```
cd webapi
```
Spuštěním následujícího příkazu sestavte řešení:

dotnet run

Pokud bylo sestavení úspěšné, zobrazí se následující výstup:

Building...
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: https://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: http://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Application started. Press Ctrl+C to shut down.
...

Jak ukázka funguje

Startup – třída

Middleware Microsoft.AspNetCore.Authentication používá Startup třídu, která se spustí při spuštění procesu hostování. V jeho ConfigureServices metodě se AddMicrosoftIdentityWebApi volá metoda rozšíření poskytovaná microsoft.Identity.Web.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(Configuration, "AzureAd");
    }

Metoda AddAuthentication() nakonfiguruje službu tak, aby přidala ověřování na základě JwtBearer.

Řádek, který obsahuje .AddMicrosoftIdentityWebApi , přidá autorizaci Microsoft Identity Platform do webového rozhraní API. Pak je nakonfigurovaná tak, aby ověřovala přístupové tokeny vydané platformou Microsoft Identity Platform na základě informací v AzureAD části konfiguračního souboru appsettings.json :

klíč appsettings.json	Popis
`ClientId`	ID aplikace (klienta) zaregistrované aplikace.
`Instance`	Koncový bod služby tokenů zabezpečení (STS) pro ověření uživatele Tato hodnota je obvykle `https://login.microsoftonline.com/`označující veřejný cloud Azure.
`TenantId`	Název tenanta nebo JEHO ID tenanta (GUID) nebo `common` přihlášení uživatelů pomocí pracovních nebo školních účtů nebo osobních účtů Microsoft.

Metoda Configure() obsahuje dvě důležité metody a app.UseAuthentication() app.UseAuthorization(), které umožňují jejich pojmenované funkce:

// The runtime calls this method. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // more code
    app.UseAuthentication();
    app.UseAuthorization();
    // more code
}

Ochrana kontroleru, metody kontroleru nebo stránky Razor Page

Metodu kontroleru nebo kontroleru lze chránit pomocí atributu [Authorize] . Tento atribut omezuje přístup k kontroleru nebo metodám tím, že povoluje pouze ověřené uživatele. Pokud uživatel není ověřený, je možné zahájit ověřovací výzvu pro přístup k kontroleru.

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase

Ověření rozsahu v kontroleru

Kód v rozhraní API ověřuje, že požadované obory jsou v tokenu pomocí HttpContext.VerifyUserHasAnyAcceptedScope> (scopeRequiredByApi);:

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        // The web API will only accept tokens 1) for users, and 2) having the "access_as_user" scope for this API
        static readonly string[] scopeRequiredByApi = new string[] { "access_as_user" };

        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi);

            // some code here
        }
    }
}

Nápověda a podpora

Pokud potřebujete pomoc, chcete nahlásit problém nebo se chcete dozvědět o možnostech podpory, přečtěte si nápovědu a podporu pro vývojáře.

Další kroky

Následující úložiště GitHub obsahuje ukázkové pokyny k kódu webového rozhraní API ASP.NET Core a další ukázky, které ukazují, jak dosáhnout následujících kroků:

Přidejte ověřování do nového webového rozhraní API ASP.NET Core.
Volání webového rozhraní API z desktopové aplikace
Volejte podřízená rozhraní API, jako je Microsoft Graph a další rozhraní API Microsoftu.

Kurzy k webovému rozhraní API ASP.NET Core na GitHubu

Sdílet prostřednictvím