Uwierzytelnianie i autoryzacja w minimalnych interfejsach API

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz .NET i .NET Core Support Policy (Zasady obsługi platformy .NET Core). Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

Ważne

Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .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 identityuż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ę uwierzytelniania IAuthenticationService, która jest używana przez oprogramowanie pośredniczące uwierzytelniania. Autoryzacja jest obsługiwana przez usługę autoryzacji IAuthorizationService, która jest używana przez oprogramowanie pośredniczące autoryzacji.

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 uwierzytelnia użytkownika lub wylogowywanie 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 zapewniają procedurę obsługi z konfiguracją, która wpływa na zachowanie uwierzytelniania, takie jak identyfikatory 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 w wymaganie autoryzacji. 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 metodę AddAuthentication rejestrowania wymaganych usług uwierzytelniania u dostawcy usług 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łanie ani UseAuthorization zarejestrowanie oprogramowania pośredniczącego, ponieważ WebApplication powoduje to automatyczne AddAuthentication wywołanie UseAuthentication lub AddAuthorization wywołanie.

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 tego automatycznego zachowania, zobacz Oprogramowanie pośredniczące w minimalnych aplikacjach interfejsu 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. Minimalne aplikacje obsługują opcje ładowania z konfiguracji dla następujących strategii uwierzytelniania:

• Oparty na elementu nośnym 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.cssystemie są rejestrowane dwie strategie uwierzytelniania oparte na elementach nośnych JWT z:

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

"Bearer" jest typowym schematem domyślnym w aplikacjach z obsługą elementu nośnego JWT, ale schemat domyślny można zastąpić, ustawiając DefaultScheme właściwość 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 identity użytkowników względem interfejsu API. Autoryzacja służy do weryfikowania i weryfikowania dostępu do zasobów w interfejsie API i jest ułatwiana przez zarejestrowaną IAuthorizationService przez metodę AddAuthorization rozszerzenia. W poniższym scenariuszu dodawany jest zasób, /hello który wymaga od użytkownika przedstawienia admin oświadczenia roli z oświadczeniem greetings_api zakresu.

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

1. Globalne konfigurowanie wymagań dotyczących autoryzacji w zasadach.
2. Stosowanie poszczególnych zasad 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 oparte na rolach dla RequireRole użytkowników z rolą admin .
• Wymaganie oparte na oświadczeniach za pośrednictwem RequireClaim tego, że użytkownik musi podać greetings_api oświadczenie zakresu.

Zasady admin_greetings są udostępniane jako wymagane zasady do 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 elementach nośnych JWT wymaga, aby klienci prezentowali token w nagłówku żądania w celu zweryfikowania ich identity i oświadczeń. Zazwyczaj te tokeny są wystawiane przez urząd centralny, taki jak identity serwer.

Podczas tworzenia aplikacji na komputerze dotnet user-jwts lokalnym narzędzie może służyć do tworzenia tokenów elementu nośnego.

dotnet user-jwts create

Uwaga

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

Tokeny można skonfigurować przy użyciu różnych dostosowań. Aby na przykład utworzyć token dla admin roli i greetings_api zakresu oczekiwanego przez zasady 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ę.