Hitelesítés és engedélyezés minimális API-kban

Jegyzet

Ez nem a cikk legújabb verziója. Az aktuális kiadásról a cikk .NET 10-es verziójában olvashat.

Figyelmeztetés

A ASP.NET Core ezen verziója már nem támogatott. További információ: .NET és .NET Core támogatási szabályzat. Az aktuális kiadást lásd ennek a cikknek a .NET 9-es verziójában.

A minimális API-k támogatják a ASP.NET Core-ban elérhető összes hitelesítési és engedélyezési lehetőséget, és további funkciókat biztosítanak a hitelesítéssel kapcsolatos élmény javítása érdekében.

A hitelesítés és az engedélyezés főbb fogalmai

A hitelesítés a felhasználó identitásának meghatározására szolgáló folyamat. Az engedélyezés annak meghatározására szolgáló folyamat, hogy a felhasználó rendelkezik-e hozzáféréssel egy erőforráshoz. A hitelesítési és engedélyezési forgatókönyvek is hasonló implementációs szemantikát használnak a ASP.NET Core-ban. A hitelesítést a hitelesítési szolgáltatás, IAuthenticationServicekezeli, amelyet a hitelesítés köztes szoftverhasznál. Az engedélyezést az engedélyezési szolgáltatás, IAuthorizationServicekezeli, amelyet az engedélyezési köztes szoftver használ.

A hitelesítési szolgáltatás regisztrált hitelesítéskezelőket használ a hitelesítéssel kapcsolatos műveletek végrehajtásához. Egy hitelesítéssel kapcsolatos művelet például egy felhasználó hitelesítése vagy egy felhasználó kijelentkeztetése. A hitelesítési sémák olyan nevek, amelyek egyedileg azonosítják a hitelesítési kezelőt és annak konfigurációs beállításait. A hitelesítési kezelők feladata a hitelesítési stratégiák implementálása és a felhasználó jogcímeinek generálása adott hitelesítési stratégiával, például OAuth vagy OIDC alapján. A konfigurációs beállítások a stratégiában is egyediek, és olyan konfigurációt biztosítanak a kezelőnek, amely befolyásolja a hitelesítési viselkedést, például az átirányítási URI-kat.

Az engedélyezési rétegben két stratégia határozza meg a felhasználók hozzáférését az erőforrásokhoz:

• A szerepköralapú stratégiák a hozzárendelt szerepkör alapján határozzák meg a felhasználó hozzáférését, például Administrator vagy User. A szerepköralapú engedélyezésről további információkért lásd a szerepköralapú engedélyezési dokumentációt.
• A jogcímalapú stratégiák a felhasználó hozzáférését egy központi hatóság által kibocsátott jogcímek alapján határozzák meg. További információ a jogcímalapú engedélyezésről: jogcímalapú engedélyezési dokumentáció.

A ASP.NET Core-ban mindkét stratégia engedélyezési követelményként van rögzítve. Az engedélyezési szolgáltatás az engedélyezési kezelők segítségével állapítja meg, hogy egy adott felhasználó megfelel-e az erőforrásra alkalmazott engedélyezési követelményeknek.

Hitelesítés engedélyezése minimális alkalmazásokban

A hitelesítés engedélyezéséhez hívja meg AddAuthentication, hogy regisztrálja a szükséges hitelesítési szolgáltatásokat az alkalmazás szolgáltatóján.

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

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

A rendszer általában egy adott hitelesítési stratégiát használ. Az alábbi példában az alkalmazás JWT-alapú hitelesítés támogatásával van konfigurálva. Ez a példa a Microsoft.AspNetCore.Authentication.JwtBearer NuGet-csomagban elérhető API-kat használja.

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

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

Alapértelmezés szerint a WebApplication automatikusan regisztrálja a hitelesítési és engedélyezési köztes szoftvereket, ha bizonyos hitelesítési és engedélyezési szolgáltatások engedélyezve vannak. Az alábbi példában nem szükséges meghívni UseAuthentication vagy UseAuthorization a köztes szoftverek regisztrálásához, mert WebApplication ezt automatikusan elvégzi AddAuthentication vagy AddAuthorization meghívása után.

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

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

Bizonyos esetekben, például a köztes szoftver rendelésének szabályozásához explicit módon regisztrálni kell a hitelesítést és az engedélyezést. Az alábbi példában a hitelesítési köztes szoftver fut a CORS köztes szoftver után. A köztes szoftverekkel és az automatikus működésekkel kapcsolatos további információkért lásd: Köztes szoftver a Minimal API-alkalmazásokban.

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();

Hitelesítési stratégia konfigurálása

A hitelesítési stratégiák általában számos konfigurációt támogatnak, amelyek a beállításokon keresztül töltődnek be. A minimális alkalmazások támogatják a konfigurációból való betöltési beállításokat a következő hitelesítési stratégiákhoz:

• JWT-jogosultságon-alapuló
• OpenID kapcsolatalapú

A ASP.NET Core-keretrendszer ezeket a beállításokat a Authentication:Schemes:{SchemeName} szakaszában találja meg. A következő mintában két különböző sémát határozunk meg, Bearer és LocalAuthIssuer, a megfelelő beállításokkal. A Authentication:DefaultScheme beállítással konfigurálhatja a használt alapértelmezett hitelesítési stratégiát.

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

A Program.cs-ban két JWT-alapú hitelesítési stratégia van regisztrálva, a következőkkel:

• "Tulajdonos" séma neve.
• A "LocalAuthIssuer" rendszer neve.

A "Bearer" a JWT-bearer-alapú engedélyezett alkalmazások tipikus alapértelmezett sémája, de az alapértelmezett sémát felül lehet bírálni a DefaultScheme tulajdonság beállításával, ahogyan az előző példában bemutatva.

A sémanév egy hitelesítési stratégia egyedi azonosítására szolgál, és keresési kulcsként használatos a hitelesítési beállítások konfigurációból való feloldásakor, ahogyan az alábbi példában látható:

var builder = WebApplication.CreateBuilder(args);

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

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

Engedélyezési szabályzatok konfigurálása minimális alkalmazásokban

A hitelesítéssel azonosíthatja és ellenőrizheti a felhasználók identitását egy API-val. Az engedélyezés egy API-ban lévő erőforrásokhoz való hozzáférés ellenőrzésére és hitelesítésére szolgál, és IAuthorizationService az AddAuthorization bővítménymetódus által történő regisztrálása által segített. A következő forgatókönyvben egy /hello erőforrást adunk hozzá, amely megköveteli, hogy a felhasználó egy admin szerepkör-jogcímet mutasson be egy greetings_api hatókörre vonatkozó jogcímmel.

Az erőforrás engedélyezési követelményeinek konfigurálása kétlépéses folyamat, amelyhez az alábbiak szükségesek:

1. Az engedélyezési követelmények globális konfigurálása egy szabályzatban.
2. Egyéni szabályzatok alkalmazása erőforrásokra.

A következő kódban a AddAuthorizationBuilder van meghívva, amely:

• Engedélyezéssel kapcsolatos szolgáltatásokat ad hozzá a DI-tárolóhoz.
• Egy olyan AuthorizationBuilder ad vissza, amely az engedélyezési szabályzatok közvetlen regisztrálásához használható.

A kód létrehoz egy új, admin_greetingsnevű engedélyezési szabályzatot, amely két engedélyezési követelményt foglal magában:

• Szerepköralapú RequireRole követelmény az admin szerepkörrel rendelkező felhasználók számára.
• A RequireClaim keresztüli jogcímalapú követelmény, amely szerint a felhasználónak greetings_api hatókörre vonatkozó jogcímet kell megadnia.

A admin_greetings szabályzat kötelező házirendként van megadva a /hello végponthoz.

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();

A dotnet user-jwts használata fejlesztési teszteléshez

Ebben a cikkben egy JWT-bearer alapú hitelesítéssel konfigurált alkalmazást használunk. A JWT-alapú hitelesítéshez az ügyfeleknek egy tokent kell bemutatniuk a kérés fejlécében a személyazonosságuk és igényeik igazolására. Ezeket a jogkivonatokat általában egy központi hatóság, például egy identitáskiszolgáló bocsátja ki.

A helyi gépen történő fejlesztéskor a dotnet user-jwts eszköz használható hordozó tokenek létrehozásához.

dotnet user-jwts create

Jegyzet

Amikor egy projekten használják, az eszköz automatikusan hozzáadja a generált tokenhez tartozó hitelesítési beállításokat appsettings.json-hoz.

A tokenek számos módon testreszabhatók. Az előző kód engedélyezési szabályzata által megkövetelt admin szerepkörhöz és greetings_api hatókörhöz például hozzon létre egy jogkivonatot.

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

A létrehozott jogkivonat ezután elküldhető a fejléc részeként a választott tesztelési eszközben. Például a curl használatával:

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

Az dotnet user-jwts eszközzel kapcsolatos további információkért olvassa el a teljes dokumentációt.