Autentisering och auktorisering i minimala API:er

Minimala API:er stöder alla autentiserings- och auktoriseringsalternativ som är tillgängliga i ASP.NET Core och ger ytterligare funktioner för att förbättra upplevelsen av autentisering.

Viktiga begrepp inom autentisering och auktorisering

Autentisering är en process för att fastställa en användares identitet. Auktorisering är processen för att avgöra om en användare har åtkomst till en resurs. Både autentiserings- och auktoriseringsscenarier delar liknande implementeringssemantik i ASP.NET Core. Autentisering hanteras av autentiseringstjänsten IAuthenticationService, som används av mellanprogram för autentisering. Auktorisering hanteras av auktoriseringstjänsten IAuthorizationService, som används av mellanprogrammet för auktorisering.

Autentiseringstjänsten använder registrerade autentiseringshanterare för att slutföra autentiseringsrelaterade åtgärder. Till exempel autentiserar en autentiseringsrelaterad åtgärd en användare eller loggar ut en användare. Autentiseringsscheman är namn som används för att unikt identifiera en autentiseringshanterare och dess konfigurationsalternativ. Autentiseringshanterare ansvarar för att implementera strategierna för autentisering och generera en användares anspråk med en viss autentiseringsstrategi, till exempel OAuth eller OIDC. Konfigurationsalternativen är också unika för strategin och ger hanteraren konfiguration som påverkar autentiseringsbeteendet, till exempel omdirigerings-URI:er.

Det finns två strategier för att fastställa användaråtkomst till resurser i auktoriseringsskiktet:

• Rollbaserade strategier avgör en användares åtkomst baserat på vilken roll de tilldelas, till exempel Administrator eller User. Mer information om rollbaserad auktorisering finns i rollbaserad auktoriseringsdokumentation.
• Anspråksbaserade strategier avgör en användares åtkomst baserat på anspråk som utfärdas av en central myndighet. Mer information om anspråksbaserad auktorisering finns i dokumentationen om anspråksbaserad auktorisering.

I ASP.NET Core registreras båda strategierna i ett auktoriseringskrav. Auktoriseringstjänsten använder auktoriseringshanterare för att avgöra om en viss användare uppfyller de auktoriseringskrav som tillämpas på en resurs.

Aktivera autentisering i minimala appar

Om du vill aktivera autentisering anropar du AddAuthentication för att registrera de nödvändiga autentiseringstjänsterna på appens tjänstleverantör.

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

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

Vanligtvis används en specifik autentiseringsstrategi. I följande exempel konfigureras appen med stöd för JWT-ägarbaserad autentisering. I det här exemplet används DE API:er som är tillgängliga i Microsoft.AspNetCore.Authentication.JwtBearer NuGet-paketet.

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

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

Som standard WebApplication registrerar automatiskt mellanprogram för autentisering och auktorisering om vissa autentiserings- och auktoriseringstjänster är aktiverade. I följande exempel är det inte nödvändigt att anropa UseAuthentication eller UseAuthorization registrera mellanprogram eftersom WebApplication gör detta automatiskt efter AddAuthentication eller AddAuthorization anropas.

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

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

I vissa fall, till exempel att kontrollera mellanprogramsordningen, är det nödvändigt att uttryckligen registrera autentisering och auktorisering. I följande exempel körs mellanprogrammet för autentisering när CORS-mellanprogrammet har körts. Mer information om mellanprogram och det här automatiska beteendet finns i Mellanprogram i Minimala API-appar.

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

Konfigurera autentiseringsstrategi

Autentiseringsstrategier stöder vanligtvis en mängd olika konfigurationer som läses in via alternativ. Minimala appar stöder inläsningsalternativ från konfigurationen för följande autentiseringsstrategier:

• JWT-bärarebaserad
• OpenID-anslutningsbaserad

Det ASP.NET Core-ramverket förväntar sig att hitta dessa alternativ under Authentication:Schemes:{SchemeName} avsnittet i konfigurationen. I följande exempel definieras två olika scheman Bearer och LocalAuthIssuer, med respektive alternativ. Alternativet Authentication:DefaultScheme kan användas för att konfigurera standardautentiseringsstrategin som används.

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

I Program.csregistreras två JWT-ägarbaserade autentiseringsstrategier med:

• "Bearer"-schemanamn.
• Schemanamnet "LocalAuthIssuer".

"Bearer" är det typiska standardschemat i JWT-bearer-baserade aktiverade appar, men standardschemat kan åsidosättas genom att ange DefaultScheme egenskapen som i föregående exempel.

Schemanamnet används för att unikt identifiera en autentiseringsstrategi och används som uppslagsnyckel när du löser autentiseringsalternativ från konfigurationen, som du ser i följande exempel:

var builder = WebApplication.CreateBuilder(args);

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

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

Konfigurera auktoriseringsprinciper i minimala appar

Autentisering används för att identifiera och verifiera identiteten för användare mot ett API. Auktorisering används för att validera och verifiera åtkomsten till resurser i ett API och underlättas av IAuthorizationService som registreras av AddAuthorization tilläggsmetoden. I följande scenario läggs en /hello resurs till som kräver att en användare presenterar ett admin rollanspråk med ett greetings_api omfångsanspråk.

Att konfigurera auktoriseringskrav för en resurs är en tvåstegsprocess som kräver:

1. Konfigurera behörighetskraven i en policy globalt.
2. Tillämpa enskilda policyer på resurser.

I följande kod AddAuthorizationBuilder anropas som:

• Lägger till auktoriseringsrelaterade tjänster i DI-containern.
• Returnerar en AuthorizationBuilder som kan användas för att registrera auktoriseringsprinciper direkt.

Koden skapar en ny auktoriseringsprincip med namnet admin_greetings, som kapslar in två auktoriseringskrav:

• Ett rollbaserat krav via RequireRole för användare med en admin roll.
• Ett anspråksbaserat krav via RequireClaim att användaren måste ange ett greetings_api omfångsanspråk.

Policyn admin_greetings tillhandahålls som en obligatorisk policy för /hello endpunkten.

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

Använda dotnet user-jwts för utvecklingstestning

I den här artikeln används en app som konfigurerats med JWT-ägarbaserad autentisering. JWT-ägarbaserad autentisering kräver att klienter presenterar en token i begärandehuvudet för att verifiera sin identitet och sina anspråk. Vanligtvis utfärdas dessa token av en central utfärdare, till exempel en identitetsserver.

När du utvecklar på den lokala datorn kan verktyget dotnet user-jwts användas för att skapa bearertoken.

dotnet user-jwts create

Token kan konfigureras med en mängd olika anpassningar. Till exempel, för att skapa en token för rollen admin och omfånget greetings_api som förväntas av auktoriseringsprincipen i föregående kod:

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

Den genererade token kan sedan skickas som en del av rubriken i valfritt testverktyg. Till exempel med curl:

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

Mer information om verktyget finns dotnet user-jwts i den fullständiga dokumentationen.