Rychlý start: Ochrana webového rozhraní API ASP.NET Core

V tomto rychlém startu chráníte webové rozhraní API ASP.NET Core pomocí Microsoft Entra ID a Microsoft.Identity.Web. Přidáte ověřovací middleware, který ověřuje nosné tokeny a omezuje přístup autorizovaným volajícím.

Pokud nemáte předplatné Azure, vytvořte si bezplatný účet před zahájením.

Předpoklady

Možnost 1: Vytvoření ze šablony (nejrychlejší)

K vygenerování projektu chráněného rozhraní API použijte šablonu ASP.NET Core s integrovaným ověřováním Microsoft Entra.

1. Vytvoření projektu

Spuštěním následujících příkazů vytvořte nový projekt webového rozhraní API s ověřováním jedné organizace a přejděte do adresáře projektu:

dotnet new webapi --auth SingleOrg --name MyWebApi
cd MyWebApi

2. Konfigurace registrace aplikace

Zástupné hodnoty v appsettings.json nahraďte podrobnostmi o registraci aplikace Microsoft Entra:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-api-client-id"
  }
}

3. Spuštění rozhraní API

Spusťte aplikaci:

dotnet run

Vaše rozhraní API je teď chráněné na adrese https://localhost:5001.

Hotovo! Požadavky teď vyžadují platný přístupový token.

Možnost 2: Přidání do existujícího webového rozhraní API

Pokud už máte webové rozhraní API ASP.NET Core, přidejte Microsoft Entra ověřování pomocí následujícího postupu.

1. Instalace balíčku NuGet

Přidejte Microsoft. Balíček NuGet Identity.Web do projektu:

dotnet add package Microsoft.Identity.Web

2. Konfigurace ověřování v Program.cs

Zaregistrujte ověřovací a autorizační služby ve spouštěcím kanálu vaší aplikace. Následující kód konfiguruje ověřování nositele JWT s validací Microsoft Entra:

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

var builder = WebApplication.CreateBuilder(args);

// Add authentication
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(builder.Configuration, "AzureAd");

// Add authorization
builder.Services.AddAuthorization();

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthentication(); //  Add authentication middleware
app.UseAuthorization();

app.MapControllers();

app.Run();

3. Přidejte konfiguraci do appsettings.json

Přidejte část konfigurace Microsoft Entra s podrobnostmi o tenantovi a aplikaci. Nastavte úroveň protokolování pro Microsoft.Identity.Web na Information, abyste mohli řešit potíže s ověřováním tokenů:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-api-client-id"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Identity.Web": "Information"
    }
  }
}

4. Ochrana koncových bodů rozhraní API

[Authorize] Použijte atribut na kontrolery nebo akce, které vyžadují platný přístupový token.

Vyžadovat autentizaci pro všechny koncové body:

Následující kontroler vyžaduje platný přístupový token pro všechny akce a ukazuje, jak získat přístup k deklaracím identity uživatelů:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[Authorize] //  Require valid access token
[ApiController]
[Route("api/[controller]")]
public class WeatherForecastController : ControllerBase
{
    [HttpGet]
    public IEnumerable<WeatherForecast> Get()
    {
        // Access user information
        var userId = User.FindFirst("oid")?.Value;
        var userName = User.Identity?.Name;

        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = "Protected data"
        });
    }
}

Vyžadovat konkrétní obory:

Pomocí atributu [RequiredScope] vynucujte jemně odstupňovaná oprávnění pro jednotlivé akce:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Identity.Web;

[Authorize]
[ApiController]
[Route("api/[controller]")]
public class TodoController : ControllerBase
{
    [HttpGet]
    [RequiredScope("access_as_user")] //  Require specific scope
    public IActionResult GetAll()
    {
        return Ok(new[] { "Todo 1", "Todo 2" });
    }

    [HttpPost]
    [RequiredScope("write")] //  Different scope for write operations
    public IActionResult Create([FromBody] string item)
    {
        return Created("", item);
    }
}

5. Spuštění a testování

Spusťte aplikaci a ověřte, že jsou neověřené požadavky odmítnuty:

dotnet run

Otestujte nástroj, jako je Postman nebo curl. Neověřený požadavek vrátí 401 Unauthorized:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://localhost:5001/api/weatherforecast

Úspěch! Vaše rozhraní API teď ověřuje nosné tokeny.

Nastavení registrace aplikace

Než vaše rozhraní API dokáže ověřit tokeny, potřebujete registraci Microsoft Entra aplikace. Na portálu Azure postupujte takto.

1. Registrace rozhraní API

  1. Přihlaste se k portálu Azure
  2. Přejděte na Microsoft Entra ID>Registrace aplikací>Nová registrace
  3. Zadejte název (např. Moje webové rozhraní API).
  4. Výběr jednoho tenanta (nejběžnější pro rozhraní API)
  5. Pro API není potřeba žádné URI přesměrování.
  6. Klikněte na Zaregistrovat.

2. Zveřejnění oboru rozhraní API

Definujte oprávnění (obory), které můžou klientské aplikace požadovat při volání rozhraní API.

  1. V registraci aplikace API přejděte na Zveřejnit rozhraní API.
  2. Klikněte na Přidat obor.
  3. Přijměte výchozí identifikátor URI ID aplikace nebo ho přizpůsobte (např. api://your-api-client-id)
  4. Přidejte obor:
    • Název oboru:access_as_user
    • Kdo může souhlasit: Správci a uživatelé
    • Zobrazovaný název souhlasu správce: Přístup k webovému API
    • Popis souhlasu správce: "Umožňuje aplikaci přístup k webovému rozhraní API jménem přihlášeného uživatele"
  5. Klikněte na Přidat obor.

3. Poznamenejte si ID aplikace.

Zkopírujte ID aplikace (klienta) ze stránky s přehledem registrace aplikace. Tato hodnota je vaše ClientId v appsettings.json.

Vytvoření registrace klientské aplikace (pro testování)

Pokud chcete otestovat chráněné rozhraní API, zaregistrujte samostatnou klientskou aplikaci, která získává tokeny a volá rozhraní API.

1. Registrace klientské aplikace

  1. V Microsoft Entra ID>Registrace aplikací vytvořte další registraci.
  2. Pojmenujte ho (např. "My API Client")
  3. Výběr typů účtů
  4. Přidejte identifikátor URI přesměrování: https://localhost:7000/signin-oidc (pokud se jedná o webovou aplikaci)
  5. Klikněte na Zaregistrovat.

2. Udělení oprávnění rozhraní API

Udělte klientské aplikaci oprávnění k volání rozhraní API s definovanými obory.

  1. V registraci klientské aplikace přejděte na oprávnění rozhraní API.
  2. Klikněte na Přidat oprávnění>Moje rozhraní API.
  3. Výběr registrace rozhraní API
  4. Zkontrolujte rozsah access_as_user
  5. Klikněte na Přidat oprávnění.
  6. Klikněte na Udělit souhlas správce (v případě potřeby).

3. Vytvoření tajného klíče klienta (pro důvěrné klienty)

Pokud klientská aplikace běží na serveru (ne v prohlížeči nebo mobilním zařízení), vytvořte tajný klíč klienta pro ověření.

  1. Přejděte na Certifikáty a tajné kódy
  2. Klikněte na Nový tajný klíč klienta.
  3. Přidání popisu a vypršení platnosti
  4. Klikněte na Přidat.
  5. Okamžitě zkopírujte hodnotu tajného kódu – už ji neuvidíte.

Testování chráněného rozhraní API

Ověřte, že vaše rozhraní API správně ověřuje tokeny odesláním ověřených požadavků.

Použití nástroje Postman

Nastavte ověřování OAuth 2.0 v Postmanu, abyste získali token a volali vaše rozhraní API.

  1. Vytvoření nového požadavku v Nástroji Postman
  2. Nastavení ověřování OAuth 2.0:
    • Typ udělení: Autorizační kód (pro kontext uživatele) nebo přihlašovací údaje klienta (pro kontext aplikace)
    • Adresa URL ověřování:https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
    • Adresa URL přístupového tokenu:https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
    • ID klienta: ID klienta klientské aplikace
    • Tajný klíč klienta: Tajný kód klientské aplikace
    • Rozsah:api://your-api-client-id/access_as_user
  3. Klikněte na Získat nový přístupový token.
  4. Použití tokenu k volání rozhraní API

Použití kódu (příklad jazyka C#)

Následující příklad používá MSAL.NET k získání tokenu s tokem přihlašovacích údajů klienta a volání chráněného rozhraní API:

// In a console app or client application
using Microsoft.Identity.Client;

var app = ConfidentialClientApplicationBuilder
    .Create("client-app-id")
    .WithClientSecret("client-secret")
    .WithAuthority("https://login.microsoftonline.com/{tenant-id}")
    .Build();

var result = await app.AcquireTokenForClient(
    new[] { "api://your-api-client-id/.default" }
).ExecuteAsync();

var accessToken = result.AccessToken;

// Use the token to call your API
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", accessToken);

var response = await client.GetAsync("https://localhost:5001/api/weatherforecast");

Běžné možnosti konfigurace

Microsoft. Identity.Web podporuje několik vzorů konfigurace pro různé scénáře.

Vyžadování konkrétních oborů v konfiguraci

Místo použití atributu [RequiredScope] můžete nakonfigurovat požadované obory globálně v appsettings.json:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-api-client-id",
    "Scopes": "access_as_user"
  }
}

Přijmout tokeny z více tenantů

Pokud chcete přijímat tokeny z libovolného tenanta Microsoft Entra, nastavte TenantId na common:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "common",
    "ClientId": "your-api-client-id"
  }
}

Konfigurace ověřování tokenů

Pokud vaše rozhraní API volá podřízená rozhraní API (například Microsoft Graph), povolte získání tokenu a nakonfigurujte mezipaměť tokenů:

builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi() // If your API calls other APIs
    .AddInMemoryTokenCaches();

Další kroky

Teď, když máte chráněné rozhraní API, prozkoumejte tato témata:

Troubleshooting

401 Neautorizováno

Problém: Rozhraní API vrátí hodnotu 401 i s tokenem.

Možné příčiny:

  • Cílová skupina tokenů (aud deklarace identity) neodpovídá vašemu rozhraní API ClientId
  • Platnost tokenu vypršela.
  • Token je určen pro nesprávného nájemce.
  • Chybí požadovaný obor.

Řešení: Dekódujte token na jwt.ms a ověřte nároky. Podrobné řešení potíží najdete v tématu Protokolování a diagnostika .

AADSTS50013: Neplatný podpis

Problém: Ověření podpisu tokenu se nezdaří.

Řešení: Ujistěte se, že jsou vaše TenantId a ClientId správné. Token musí vydat očekávaná autorita. Pokud chcete zobrazit chyby ověření, povolte podrobné protokolování.

Rozsahy nebyly v tokenu nalezeny.

Problém:[RequiredScope] atribut selže.

Solution:

  1. Ověřte, že klientská aplikace má oprávnění k rozsahu.
  2. Ujistěte se, že byl udělen souhlas správce (v případě potřeby).
  3. Kompletní vzory ověřování rozsahu najdete v Průvodci autorizací .
  4. Zkontrolujte, zda je obor požadován při získávání tokenu (např. api://your-api/.default nebo konkrétní obory).

Další informace:Průvodce odstraňováním potíží s webovým rozhraním API

Související obsah

  • Last updated on