Sdílet prostřednictvím

Ověřování a autorizace v minimálních rozhraních API

Poznámka:

Toto není nejnovější verze tohoto článku. Aktuální verzi najdete ve verzi .NET 10 tohoto článku.

Varování

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v zásadách podpory .NET a .NET Core. Aktuální vydání najdete v verzi .NET 9 tohoto článku.

Minimální rozhraní API podporují všechny možnosti ověřování a autorizace dostupné v ASP.NET Core a poskytují některé další funkce, které zlepšují práci s ověřováním.

Klíčové koncepty ověřování a autorizace

Ověřování je proces určení identity uživatele. Autorizace je proces určení, jestli uživatel má přístup k prostředku. Scénáře ověřování i autorizace sdílejí podobné sémantiky implementace v ASP.NET Core. Ověřování zpracovává ověřovací služba IAuthenticationService, která se používá ověřovacím middlewarem. Autorizaci zpracovává autorizační služba IAuthorizationService, která se používá autorizačním middlewarem.

Ověřovací služba používá k dokončení akcí souvisejících s ověřováním registrované ovladače ověřování. Například akce související s ověřováním ověřuje uživatele nebo odhlasuje uživatele. Schémata ověřování jsou názvy, které slouží k jednoznačné identifikaci obslužné rutiny ověřování a možností konfigurace. Zpracovatelé ověřování jsou zodpovědní za implementaci strategií ověřování a generování uživatelských nároků na základě konkrétní strategie ověřování, jako je OAuth nebo OIDC. Možnosti konfigurace jsou jedinečné pro strategii a poskytují zpracovateli nastavení, které ovlivňuje chování ověřování, jako jsou přesměrovací URI.

Existují dvě strategie pro určení přístupu uživatelů k prostředkům ve vrstvě autorizace:

  • Strategie založené na rolích určují přístup uživatele na základě přiřazené role, například Administrator .User Další informace o autorizaci na základě role najdete v dokumentaci k autorizaci na základě role.
  • Strategie založené na deklarací identity určují přístup uživatele na základě deklarací identity, které vydává centrální autorita. Další informace o autorizaci na základě deklarace identity najdete v dokumentaci k autorizaci na základě deklarace identity.

V ASP.NET Core jsou obě strategie zachyceny do požadavku na autorizaci. Autorizační služba využívá obslužné rutiny autorizace k určení, jestli konkrétní uživatel splňuje požadavky na autorizaci použité u prostředku.

Povolení ověřování v minimálních aplikacích

Chcete-li povolit ověřování, zavolejte AddAuthentication k zaregistrování požadovaných ověřovacích služeb u poskytovatele služeb aplikace.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Obvykle se používá konkrétní strategie ověřování. V následující ukázce je aplikace nakonfigurovaná s podporou ověřování založeného na nosných modelech JWT. Tento příklad využívá rozhraní API dostupná v Microsoft.AspNetCore.Authentication.JwtBearer balíčku NuGet.

var builder = WebApplication.CreateBuilder(args);
// Requires Microsoft.AspNetCore.Authentication.JwtBearer
builder.Services.AddAuthentication().AddJwtBearer();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Ve výchozím nastavení WebApplication automaticky zaregistruje ověřovací a autorizační middleware, pokud jsou povolené určité ověřovací a autorizační služby. V následujícím příkladu není nutné vyvolat UseAuthentication nebo UseAuthorization k registraci middleware, protože WebApplication to provádí automaticky po spuštění AddAuthentication nebo AddAuthorization.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

V některých případech, například řízení pořadí middlewaru, je nutné explicitně zaregistrovat ověřování a autorizaci. V následující ukázce se autentizační middleware spustí po spuštění CORS middleware. Další informace o middlewarech a tomto automatickém chování najdete v tématu Middleware v aplikacích Minimal API.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCors();
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/", () => "Hello World!");
app.Run();

Konfigurace strategie ověřování

Strategie ověřování obvykle podporují řadu konfigurací, které jsou načítány pomocí možností. Minimální aplikace podporují možnosti načítání z konfigurace pro následující strategie ověřování:

Architektura ASP.NET Core očekává, že tyto možnosti najdete v Authentication:Schemes:{SchemeName} části konfigurace. V následující ukázce jsou definována dvě různá schémata Bearer a LocalAuthIssuer, s příslušnými možnostmi. Tuto Authentication:DefaultScheme možnost můžete použít ke konfiguraci výchozí použité strategie ověřování.

{
  "Authentication": {
    "DefaultScheme":  "LocalAuthIssuer",
    "Schemes": {
      "Bearer": {
        "ValidAudiences": [
          "https://localhost:7259",
          "http://localhost:5259"
        ],
        "ValidIssuer": "dotnet-user-jwts"
      },
      "LocalAuthIssuer": {
        "ValidAudiences": [
          "https://localhost:7259",
          "http://localhost:5259"
        ],
        "ValidIssuer": "local-auth"
      }
    }
  }
}

Ve Program.cs se zaregistrují dvě strategie ověřování založené na nosných JWT:

  • Název schématu "Nosič"
  • Název schématu „LocalAuthIssuer“

"Bearer" je typické výchozí schéma v aplikacích s podporou JWT-bearer, ale výchozí schéma lze přepsat nastavením DefaultScheme vlastnosti jako v předchozím příkladu.

Název schématu slouží k jednoznačné identifikaci strategie ověřování a používá se jako vyhledávací klíč při překladu možností ověřování z konfigurace, jak je znázorněno v následujícím příkladu:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication()
  .AddJwtBearer()
  .AddJwtBearer("LocalAuthIssuer");
  
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Konfigurace zásad autorizace v minimálních aplikacích

Ověřování se používá k identifikaci a ověření identity uživatelů v rozhraní API. Autorizace se používá pro validaci a ověření přístupu k prostředkům v rozhraní API a je usnadněna IAuthorizationService zaregistrovanou metodou rozšíření AddAuthorization. V následujícím scénáři se přidá /hello prostředek, který vyžaduje, aby uživatel předložil deklaraci role admin s oborovou deklarací greetings_api.

Konfigurace požadavků na autorizaci prostředku je dvoustupňový proces, který vyžaduje:

  1. Konfigurace požadavků na autorizaci v rámci zásady na globální úrovni.
  2. Použití jednotlivých zásad na zdroje

V následujícím kódu se vyvolá AddAuthorizationBuilder, který:

  • Přidá do kontejneru DI služby související s autorizací.
  • Vrátí objekt AuthorizationBuilder, který lze použít k přímé registraci zásad autorizace.

Kód vytvoří novou zásadu autorizace s názvem admin_greetings, která zapouzdřuje dva požadavky na autorizaci:

  • Požadavek na základě role prostřednictvím RequireRole pro uživatele s admin rolí.
  • Požadavek založený na deklaraci identity prostřednictvím RequireClaim, že uživatel musí poskytnout greetings_api požadavek na rozsah.

Zásada admin_greetings je k dispozici jako požadovaná zásada pro koncový bod /hello.

using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthorizationBuilder()
  .AddPolicy("admin_greetings", policy =>
        policy
            .RequireRole("admin")
            .RequireClaim("scope", "greetings_api"));

var app = builder.Build();

app.MapGet("/hello", () => "Hello world!")
  .RequireAuthorization("admin_greetings");

app.Run();

Použití dotnet user-jwts pro vývojové testování

V tomto článku se používá aplikace nakonfigurovaná s ověřováním na základě nosných objektů JWT. Ověřování na základě nosiče JWT vyžaduje, aby klienti v hlavičce požadavku předložili token k ověření jejich identity a nároků. Tyto tokeny obvykle vydává centrální autorita, například server identit.

Při vývoji na místním počítači dotnet user-jwts lze nástroj použít k vytvoření nosných tokenů.

dotnet user-jwts create

Poznámka:

Při vyvolání projektu nástroj automaticky přidá možnosti ověřování odpovídající vygenerovanému tokenu .appsettings.json

Tokeny je možné nakonfigurovat s různými přizpůsobeními. Například chcete-li vytvořit token pro roli admin a obor greetings_api, které očekává autorizační politika v předchozím kódu:

dotnet user-jwts create --scope "greetings_api" --role "admin"

Vygenerovaný token se pak dá odeslat jako součást hlavičky ve zvoleném testovacím nástroji. Například s curl:

curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/hello

Další informace o nástroji dotnet user-jwts najdete v úplné dokumentaci.

  • Last updated on