Uwierzytelnianie i autoryzacja w minimalnych interfejsach API

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z aktualną wersją, zobacz artykuł w wersji .NET 10.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz zasady pomocy technicznej platformy .NET i platformy .NET Core. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu w .NET 9.

Minimalne interfejsy API obsługują wszystkie opcje uwierzytelniania i autoryzacji dostępne w usłudze ASP.NET Core i zapewniają dodatkowe funkcje w celu ulepszenia środowiska pracy z uwierzytelnianiem.

Kluczowe pojęcia dotyczące uwierzytelniania i autoryzacji

Uwierzytelnianie to proces określania tożsamości użytkownika. Autoryzacja to proces ustalania, czy użytkownik ma dostęp do zasobu. Scenariusze uwierzytelniania i autoryzacji współdzielą podobne semantyki implementacji w programie ASP.NET Core. Uwierzytelnianie jest obsługiwane przez usługę IAuthenticationService, z której korzysta middleware uwierzytelniający. Autoryzacja jest obsługiwana przez usługę IAuthorizationService, którą wykorzystuje oprogramowanie pośredniczące.

Usługa uwierzytelniania używa zarejestrowanych procedur obsługi uwierzytelniania, aby wykonywać akcje związane z uwierzytelnianiem. Na przykład akcja związana z uwierzytelnianiem to uwierzytelnienie użytkownika lub wylogowanie użytkownika. Schematy uwierzytelniania to nazwy używane do unikatowego identyfikowania programu obsługi uwierzytelniania i jego opcji konfiguracji. Procedury obsługi uwierzytelniania są odpowiedzialne za implementowanie strategii uwierzytelniania i generowanie oświadczeń użytkownika przy użyciu określonej strategii uwierzytelniania, takiej jak OAuth lub OIDC. Opcje konfiguracji są również unikatowe dla strategii i dostarczają modułowi obsługi konfigurację, która wpływa na zachowanie uwierzytelniania, takie jak URI przekierowania.

Istnieją dwie strategie określania dostępu użytkowników do zasobów w warstwie autoryzacji:

• Strategie oparte na rolach określają dostęp użytkownika na podstawie przypisanej roli, takiej jak Administrator lub User. Aby uzyskać więcej informacji na temat autoryzacji opartej na rolach, zobacz dokumentację autoryzacji opartej na rolach.
• Strategie oparte na oświadczeniach określają dostęp użytkownika na podstawie oświadczeń wystawionych przez urząd centralny. Aby uzyskać więcej informacji na temat autoryzacji opartej na oświadczeniach, zobacz dokumentację autoryzacji opartej na oświadczeniach.

W ASP.NET Core obie strategie są przechwytywane jako wymaganie autoryzacyjne. Usługa autoryzacji korzysta z procedur obsługi autoryzacji, aby określić, czy określony użytkownik spełnia wymagania autoryzacji zastosowane do zasobu.

Włączanie uwierzytelniania w minimalnych aplikacjach

Aby włączyć uwierzytelnianie, wywołaj AddAuthentication w celu zarejestrowania wymaganych usług uwierzytelniania u usługodawcy aplikacji.

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

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

Zazwyczaj jest używana określona strategia uwierzytelniania. W poniższym przykładzie aplikacja jest skonfigurowana z obsługą uwierzytelniania opartego na elementach nośnych JWT. W tym przykładzie użyto interfejsów API dostępnych w pakiecie Microsoft.AspNetCore.Authentication.JwtBearer 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();

Domyślnie program WebApplication automatycznie rejestruje oprogramowanie pośredniczące uwierzytelniania i autoryzacji, jeśli niektóre usługi uwierzytelniania i autoryzacji są włączone. W poniższym przykładzie nie jest konieczne wywoływanie UseAuthentication ani UseAuthorization w celu zarejestrowania oprogramowania pośredniczącego, ponieważ WebApplication robi to automatycznie po wywołaniu AddAuthentication lub AddAuthorization.

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

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

W niektórych przypadkach, takich jak kontrolowanie kolejności oprogramowania pośredniczącego, konieczne jest jawne zarejestrowanie uwierzytelniania i autoryzacji. W poniższym przykładzie oprogramowanie pośredniczące uwierzytelniania jest uruchamiane po uruchomieniu oprogramowania pośredniczącego CORS. Aby uzyskać więcej informacji na temat oprogramowania pośredniczącego i automatyzacji z nim związanej, zobacz Oprogramowanie pośredniczące w aplikacjach 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();

Konfigurowanie strategii uwierzytelniania

Strategie uwierzytelniania zwykle obsługują różne konfiguracje ładowane za pośrednictwem opcji. Proste aplikacje obsługują ładowanie opcji z konfiguracji dla następujących strategii uwierzytelniania:

• Oparty na mechanizmie uwierzytelniania JWT
• Oparte na połączeniu OpenID

Platforma ASP.NET Core oczekuje znalezienia tych opcji w Authentication:Schemes:{SchemeName} sekcji w konfiguracji. W poniższym przykładzie są definiowane dwa różne schematy Bearer i LocalAuthIssuer, z odpowiednimi opcjami. Za Authentication:DefaultScheme pomocą opcji można skonfigurować domyślną strategię uwierzytelniania, która jest używana.

{
  "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"
      }
    }
  }
}

W Program.cs rejestrowane są dwie strategie uwierzytelniania oparte na tokenach JWT z:

• Nazwa schematu "Bearer".
• Nazwa schematu "LocalAuthIssuer".

"Bearer" jest typowym schematem domyślnym w aplikacjach z obsługą JWT, ale schemat domyślny można zastąpić, ustawiając właściwość DefaultScheme tak jak w poprzednim przykładzie.

Nazwa schematu służy do unikatowego identyfikowania strategii uwierzytelniania i jest używana jako klucz odnośnika podczas rozpoznawania opcji uwierzytelniania z konfiguracji, jak pokazano w poniższym przykładzie:

var builder = WebApplication.CreateBuilder(args);

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

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

Konfigurowanie zasad autoryzacji w minimalnych aplikacjach

Uwierzytelnianie służy do identyfikowania i weryfikowania tożsamości użytkowników względem interfejsu API. Autoryzacja służy do sprawdzania i weryfikacji dostępu do zasobów w interfejsie API i jest wspomagana przez zarejestrowaną IAuthorizationService przez metodę rozszerzenia AddAuthorization. W poniższym scenariuszu dodawany jest zasób /hello, który wymaga, żeby użytkownik przedstawił oświadczenie roli admin oraz oświadczenie zakresu greetings_api.

Konfigurowanie wymagań dotyczących autoryzacji dla zasobu jest procesem dwuetapowym, który wymaga:

1. Globalne konfigurowanie wymagań autoryzacji w ramach polityki.
2. Stosowanie poszczególnych polityk do zasobów.

W poniższym kodzie wywoływany jest następujący kod AddAuthorizationBuilder :

• Dodaje usługi związane z autoryzacją do kontenera DI.
• Zwraca element AuthorizationBuilder , który może służyć do bezpośredniego rejestrowania zasad autoryzacji.

Kod tworzy nowe zasady autoryzacji o nazwie admin_greetings, które hermetyzują dwa wymagania dotyczące autoryzacji:

• Wymaganie w oparciu o rolę za pomocą RequireRole dla użytkowników z rolą admin.
• Wymaganie oparte na oświadczeniach za pośrednictwem RequireClaim, że użytkownik musi podać greetings_api żądanie dotyczące zakresu.

Zasady admin_greetings są udostępniane jako obowiązkowe zasady dla punktu końcowego /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();

Używanie dotnet user-jwts do testowania programistycznego

W tym artykule jest używana aplikacja skonfigurowana z uwierzytelnianiem opartym na elementach nośnych JWT. Uwierzytelnianie oparte na nośniku JWT wymaga, żeby klienci przedstawiali token w nagłówku żądania w celu zweryfikowania tożsamości i roszczeń. Zazwyczaj te tokeny są wystawiane przez urząd centralny, taki jak serwer tożsamości.

Podczas tworzenia na lokalnym komputerze narzędzie dotnet user-jwts może służyć do tworzenia tokenów typu bearer.

dotnet user-jwts create

Uwaga

Po wywołaniu w projekcie, narzędzie automatycznie dodaje do appsettings.json elementu opcje uwierzytelniania pasujące do wygenerowanego tokenu.

Tokeny można skonfigurować przy użyciu różnych dostosowań. Aby utworzyć na przykład token dla roli admin i zakresu greetings_api, którego oczekuje polityka autoryzacji w poprzednim kodzie:

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

Wygenerowany token można następnie wysłać jako część nagłówka w wybranym narzędziu do testowania. Na przykład za pomocą narzędzia curl:

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

Aby uzyskać więcej informacji na dotnet user-jwts temat narzędzia, przeczytaj pełną dokumentację.