Sdílet prostřednictvím

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

  • Článek

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

Krok 1: Registrace aplikace

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

  1. Přihlaste se do Centra pro správu Microsoft Entra jako alespoň správce aplikací.
  2. Přejděte k aplikacím> identit>Registrace aplikací.
  3. Vyberte Nová registrace.
  4. 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.
  5. Vyberte Zaregistrovat.
  6. 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
  1. 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.

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

  2. Otevřete řešení ve složce webapi v editoru kódu.

  3. 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:

  1. Otevřít webapi.csproj
  2. Odeberte následující řádek:
<TargetFramework>netcoreapp3.1</TargetFramework>
  1. 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

  1. Otevřete terminál a přejděte do složky projektu.

    cd webapi

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