Sdílet prostřednictvím

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

  • Článek

Poznámka:

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

Upozorňující

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v tématu .NET a .NET Core Zásady podpory. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Důležité

Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Aktuální verzi najdete ve verzi .NET 8 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é obslužné rutiny 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. Obslužné rutiny ověřování zodpovídají za implementaci strategií ověřování a generování deklarací identity uživatele s ohledem na konkrétní strategii ověřování, jako je OAuth nebo OIDC. Možnosti konfigurace jsou pro strategii jedinečné a poskytují obslužné rutině konfiguraci, která ovlivňuje chování ověřování, jako jsou identifikátory URI přesměrování.

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

Pokud chcete povolit ověřování, zavolejte AddAuthentication na poskytovatele služeb aplikace požadované ověřovací služby.

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í ukázce není nutné vyvolat UseAuthentication nebo UseAuthorization zaregistrovat middlewary, protože WebApplication to dělá automaticky po AddAuthentication volání nebo AddAuthorization jsou volány.

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 middleware ověřování spustí po spuštění middlewaru CORS. Další informace omiddlech 

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é se načítají prostřednictvím 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.csdvou strategiích ověřování založených na nosných JWT se zaregistrují následující:

  • Název schématu "Nosný"
  • 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á k ověření a ověření přístupu k prostředkům v rozhraní API a usnadňuje ho IAuthorizationService zaregistrovaná metodou AddAuthorization rozšíření. V následujícím scénáři se přidá prostředek, který vyžaduje, /hello aby uživatel předložil admin deklaraci identity role s greetings_api deklarací oboru.

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

  1. Globální konfigurace požadavků na autorizaci v zásadách
  2. Použití jednotlivých zásad na prostředky

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

  • Přidá do kontejneru DI služby související s autorizací.
  • Vrátí zásadu AuthorizationBuilder , která se dá 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 uživatelů s admin rolí.
  • Požadavek založený na deklaraci identity prostřednictvím RequireClaim toho, že uživatel musí poskytnout greetings_api deklaraci oboru.

Zásada admin_greetings se do koncového /hello bodu poskytuje jako požadovaná zásada.

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í založené na nosných objektech JWT vyžaduje, aby klienti v hlavičce požadavku předložili token k ověření identity a deklarací identity. 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. Pokud například chcete vytvořit token pro admin roli a greetings_api obor očekávaný autorizačními zásadami 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.