Sdílet prostřednictvím

Kurz: Sestavení a zabezpečení webového rozhraní API ASP.NET Core pomocí platformy Microsoft Identity Platform

  • Článek

platí pro: Zelený kruh se symbolem bílé zaškrtnutí. nájemníci pracovních sil Zelený kruh se symbolem bílé zaškrtnutí. externí nájemníci (další informace)

Tato série kurzů ukazuje, jak chránit webové rozhraní API ASP.NET Core pomocí platformy Microsoft Identity Platform, aby byl omezen přístup jenom autorizovaným uživatelům a klientským aplikacím. Webové rozhraní API, které vytvoříte, používá delegovaná oprávnění (obory) i oprávnění aplikace (role aplikací).

V tomto kurzu:

  • Vytvoření webového rozhraní API ASP.NET Core
  • Nakonfigurujte webové rozhraní API tak, aby používalo podrobnosti registrace aplikace Microsoft Entra.
  • Ochrana koncových bodů webového rozhraní API
  • Spuštěním webového rozhraní API se ujistěte, že naslouchá požadavkům HTTP.

Požadavky

Vytvoření nového projektu webového rozhraní API ASP.NET Core

Pokud chcete vytvořit minimální projekt webového rozhraní API ASP.NET Core, postupujte takto:

  1. Otevřete terminál v editoru Visual Studio Code nebo jiném editoru kódu a přejděte do adresáře, kam chcete projekt vytvořit.

  2. Na .NET CLI nebo jiném nástroji příkazového řádku spusťte následující příkazy.

    dotnet new webapi -n MyProtectedApi
cd MyProtectedApi

  3. Vyberte Ano, když se zobrazí dialogové okno s dotazem, jestli chcete autorům důvěřovat.

  4. Vyberte Ano Když se zobrazí dialogové okno s dotazem, jestli chcete do projektu přidat požadované prostředky.

Instalace požadovaných balíčků

K ochraně webového rozhraní API ASP.NET Core potřebujete balíček Microsoft.Identity.Web – sada knihoven ASP.NET Core, které zjednodušují přidávání podpory ověřování a autorizace do webových aplikací a webových rozhraní API, které se integrují s platformou Microsoft Identity Platform.

K instalaci balíčku použijte:

dotnet add package Microsoft.Identity.Web

Konfigurace podrobností registrace aplikace

Otevřete soubor appsettings.json ve složce aplikace a přidejte podrobnosti o registraci aplikace, které jste si poznamenali po registraci webového rozhraní API.

{
    "AzureAd": {
        "Instance": "Enter_the_Authority_URL_Here",
        "TenantId": "Enter_the_Tenant_Id_Here",
        "ClientId": "Enter_the_Application_Id_Here",
    },
    "Logging": {...},
  "AllowedHosts": "*"
}

Nahraďte následující zástupné symboly, jak je znázorněno:

  • Nahraďte Enter_the_Application_Id_Here ID vaší aplikace (klienta).
  • Nahraďte Enter_the_Tenant_Id_Here ID adresáře (tenanta).
  • Nahraďte Enter_the_Authority_URL_Here adresou URL autority, jak je to vysvětleno v další části.

Adresa URL autority pro vaši aplikaci

Adresa URL autority určuje adresář, ze kterého může microsoft Authentication Library (MSAL) požadovat tokeny. Je postaven odlišně jak v pracovní síle, tak u externích nájemníků, jak je znázorněno.

//Instance for workforce tenant
Instance: "https://login.microsoftonline.com/"

Použití vlastní domény URL (volitelné)

V tenantech pro pracovníky nejsou podporovány vlastní domény URL.

Přidání role a oboru aplikace

Všechna rozhraní API musí publikovat minimálně jeden obor, označovaný také jako delegovaná oprávnění, aby klientské aplikace získaly přístupový token pro uživatele. Rozhraní API by také měla publikovat minimálně jednu roli aplikace, označovanou také jako oprávnění aplikace, aby klientské aplikace získaly přístupový token jako samy o sobě, tzn. když se nepřihlašují uživateli.

Tato oprávnění zadáme do souboru appsettings.json. V tomto kurzu zaregistrujete delegovaná oprávnění i oprávnění aplikace s obory Forecast.Read. To znamená, že k přístupu k chráněnému koncovému bodu mají oprávnění pouze uživatelé nebo klientské aplikace, které volají rozhraní API s přístupovým tokenem obsahujícím obor Forecast.Read.

{
  "AzureAd": {
    "Instance": "Enter_the_Authority_URL_Here",
    "TenantId": "Enter_the_Tenant_Id_Here",
    "ClientId": "Enter_the_Application_Id_Here",
    "Scopes": {
      "Read": "Forecast.Read",
    },
    "AppPermissions": {
      "Read": ["Forecast.Read"],
    }
  },
  "Logging": {...},
  "AllowedHosts": "*"
}

Implementace ověřování a autorizace v rozhraní API

Pokud chcete nakonfigurovat ověřování a autorizaci, otevřete soubor program.cs a nahraďte jeho obsah následujícími fragmenty kódu:

Přidání schématu ověřování

V tomto rozhraní API používáme schéma nosných tokenů JSON (JWT) jako výchozí mechanismus ověřování. Pomocí metody AddAuthentication zaregistrujte schéma nosiče JWT.

// Import the required packages

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Configure authentication
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(options =>
    {
        builder.Configuration.Bind("AzureAd", options);
        options.TokenValidationParameters.NameClaimType = "name";
    }, options => { builder.Configuration.Bind("AzureAd", options); });

Nakonfigurujte autorizaci

Autorizace určuje, co může ověřený uživatel dělat. Definujeme zásadu s názvem AuthZPolicy, která vyžaduje, aby klient volající rozhraní API měl Forecast.Read roli pro klientské aplikace nebo obor Forecast.Read pro přihlášeného uživatele.

builder.Services.AddAuthorization(config =>
{
config.AddPolicy("AuthZPolicy", policy =>
    policy.RequireRole("Forecast.Read"));
});

Metoda AddPolicy vytvoří pojmenovanou zásadu (AuthZPolicy), která kontroluje existenci role Forecast.Read v deklaraci identity tokenu uživatele. Pokud token nemá deklaraci identity roles, přístup ke koncovým bodům vyžadujícím tuto zásadu je odepřen.

Sestavte potrubí požadavku HTTP

V tomto kurzu používáme minimální rozhraní API bez kontrolerů, protože se zaměřujeme spíše na ochranu rozhraní API. Kanál middlewaru rozhraní API nakonfigurujeme přidáním následujících:

  • Přesměrování na HTTPS: Prosazujte zabezpečenou komunikaci přesměrováním požadavků HTTP na HTTPS.
  • Ověřovací middleware: Před zpracováním požadavků ověřuje příchozí tokeny.
  • Autorizační middleware: Implementuje zásady po ověření a zajistí přístup k chráněným koncovým bodům pouze autorizovaným klientům.
var app = builder.Build();

// Configure the HTTP request pipeline

app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();

Definování koncového bodu předpovědi počasí

Koncový bod /weatherforecast vygeneruje náhodnou pětidenní prognózu chráněnou zásadami autorizace. RequireAuthorization("AuthZPolicy") zajišťuje, že k němu budou mít přístup jenom klienti s rolí Forecast.Read.

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast =  Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
    
        summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("weatherForecast")
.RequireAuthorization("AuthZPolicy"); // Protect this endpoint with the AuthZPolicy

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Tok ověřování a autorizace v ukázkovém webovém rozhraní API, které jsme vytvořili, funguje takto:

  • Klient odešle požadavek GET na /weatherforecast s JWT v hlavičce Authorization.
  • UseAuthentication ověří token vůči identifikátoru Microsoft Entra.
  • UseAuthorization kontroluje roli Forecast.Read v nárocích tokenu.
  • V případě úspěchu koncový bod vrátí prognózu; jinak odpoví 401 Unauthorized (neplatný nebo bez tokenu) nebo 403 Forbidden (chybějící role).

Spuštění rozhraní API

Spusťte příkaz dotnet runk ověření, že vaše rozhraní API běží bez chyb. Pokud máte v úmyslu používat protokol HTTPS i během testování, musíte důvěřovat vývojovému certifikátu .NET.

  1. Spusťte aplikaci zadáním následujícího příkazu v terminálu:

    dotnet run

  2. V terminálu by se měl zobrazit podobný výstup jako ten následující, který potvrzuje, že aplikace běží na http://localhost:{port} a naslouchá na žádosti.

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

Webová stránka http://localhost:{host} zobrazí výstup podobný následujícímu obrázku. Důvodem je to, že se rozhraní API volá bez ověřování. Pokud chcete provést autorizované volání, přečtěte si pokyny Další kroky k přístupu k chráněnému webovému rozhraní API.

snímek obrazovky s chybou 401 při spuštění webové stránky

Úplný příklad tohoto kódu rozhraní API najdete v ukázkovém souboru.

Další kroky

část 2: Otestování chráněného webového rozhraní API ASP.NET Core