Verificatie en autorisatie in minimale API's

Minimale API's ondersteunen alle verificatie- en autorisatieopties die beschikbaar zijn in ASP.NET Core en bieden extra functionaliteit om de ervaring met verificatie te verbeteren.

Belangrijkste concepten in verificatie en autorisatie

Verificatie is het proces van het bepalen van de identiteit van een gebruiker. Autorisatie is het proces om te bepalen of een gebruiker toegang heeft tot een resource. Zowel verificatie- als autorisatiescenario's delen vergelijkbare implementatiesemantiek in ASP.NET Core. Authenticatie wordt behandeld door de authenticatieservice, IAuthenticationService, die wordt gebruikt door authenticatie middleware. Autorisatie wordt verwerkt door de autorisatieservice, IAuthorizationService, die wordt gebruikt door de autorisatie-middleware.

De verificatieservice maakt gebruik van geregistreerde verificatiehandlers om verificatiegerelateerde acties te voltooien. Een verificatiegerelateerde actie is bijvoorbeeld het verifiëren van een gebruiker of het afmelden van een gebruiker. Verificatieschema's zijn namen die worden gebruikt om een verificatiehandler en de configuratieopties uniek te identificeren. Verificatiehandlers zijn verantwoordelijk voor het implementeren van de strategieën voor verificatie en het genereren van claims van een gebruiker op basis van een bepaalde verificatiestrategie, zoals OAuth of OIDC. De configuratieopties zijn ook uniek voor de strategie en bieden de handler een configuratie die van invloed is op het verificatiegedrag, zoals omleidings-URI's.

Er zijn twee strategieën voor het bepalen van gebruikerstoegang tot resources in de autorisatielaag:

• Strategieën op basis van rollen bepalen de toegang van een gebruiker op basis van de rol waaraan ze zijn toegewezen, zoals Administrator of User. Zie autorisatiedocumentatie op basis van rollenvoor meer informatie over autorisatie op basis van rollen.
• Strategieën op basis van claims bepalen de toegang van een gebruiker op basis van claims die worden uitgegeven door een centrale autoriteit. Zie op claim gebaseerde autorisatiedocumentatievoor meer informatie over autorisatie op basis van claims.

In ASP.NET Core worden beide strategieën vastgelegd in een autorisatievereiste. De autorisatieservice maakt gebruik van autorisatiehandlers om te bepalen of een bepaalde gebruiker voldoet aan de autorisatievereisten die zijn toegepast op een resource.

Verificatie inschakelen in minimale apps

Als u verificatie wilt inschakelen, roept u AddAuthentication aan om de vereiste verificatieservices te registreren bij de serviceprovider van de app.

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

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

Normaal gesproken wordt een specifieke verificatiestrategie gebruikt. In het volgende voorbeeld wordt de app geconfigureerd met ondersteuning voor verificatie op basis van JWT-bearer. In dit voorbeeld wordt gebruikgemaakt van de API's die beschikbaar zijn in het Microsoft.AspNetCore.Authentication.JwtBearer NuGet-pakket.

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

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

Standaard registreert de WebApplication automatisch de verificatie- en autorisatie-middlewares als bepaalde verificatie- en autorisatieservices zijn ingeschakeld. In het volgende voorbeeld is het niet nodig om UseAuthentication of UseAuthorization aan te roepen om de middlewares te registreren, omdat WebApplication dit automatisch doet nadat AddAuthentication of AddAuthorization zijn aangeroepen.

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

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

In sommige gevallen, zoals het beheren van de middlewarevolgorde, is het nodig om expliciet verificatie en autorisatie te registreren. In het volgende voorbeeld wordt de authenticatie-middleware uitgevoerd nadat de CORS-middleware heeft uitgevoerd. Zie Middleware in Minimale API-appsvoor meer informatie over middlewares en dit automatische gedrag.

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

Verificatiestrategie configureren

Verificatiestrategieën ondersteunen doorgaans verschillende configuraties die via opties worden geladen. Minimalistische apps ondersteunen laadopties vanuit de configuratie voor de volgende verificatiestrategieën:

• op JWT bearer gebaseerde
• OpenID Connection-gebaseerd

Het ASP.NET Core-framework verwacht deze opties te vinden in de sectie Authentication:Schemes:{SchemeName} in configuratie-. In het volgende voorbeeld worden twee verschillende schema's, Bearer en LocalAuthIssuer, gedefinieerd met hun respectieve opties. De optie Authentication:DefaultScheme kan worden gebruikt om de standaardverificatiestrategie te configureren die wordt gebruikt.

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

In Program.csworden twee op JWT bearer gebaseerde verificatiestrategieën geregistreerd, met de volgende:

• Naam van het Bearer-schema.
• Naam van het schema LocalAuthIssuer.

Bearer is het standaardschema in op JWT-bearer gebaseerde apps, maar het standaardschema kan worden overschreven door de eigenschap DefaultScheme in te stellen zoals in het voorgaande voorbeeld.

De schemanaam wordt gebruikt om een verificatiestrategie uniek te identificeren en wordt gebruikt als de zoeksleutel bij het omzetten van verificatieopties uit de configuratie, zoals wordt weergegeven in het volgende voorbeeld:

var builder = WebApplication.CreateBuilder(args);

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

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

Autorisatiebeleid configureren in minimale apps

Verificatie wordt gebruikt om de identiteit van gebruikers te identificeren en te valideren op basis van een API. Autorisatie wordt gebruikt om de toegang tot resources in een API te valideren en te verifiëren en wordt mogelijk gemaakt door de IAuthorizationService geregistreerd door de AddAuthorization-extensiemethode. In het volgende scenario wordt een /hello resource toegevoegd waarvoor een gebruiker een admin rolclaim moet presenteren met een greetings_api bereikclaim.

Het configureren van autorisatievereisten voor een resource is een proces in twee stappen dat vereist is:

1. De autorisatievereisten in een beleid globaal configureren.
2. Afzonderlijke beleidsregels toepassen op middelen.

In de volgende code wordt AddAuthorizationBuilder aangeroepen, dat:

• Voegt autorisatiegerelateerde services toe aan de DI-container.
• Retourneert een AuthorizationBuilder die kan worden gebruikt om autorisatiebeleid rechtstreeks te registreren.

De code maakt een nieuw autorisatiebeleid met de naam admin_greetings, dat twee autorisatievereisten bevat:

• Een op rollen gebaseerde vereiste via RequireRole voor gebruikers met een admin rol.
• Een claimvereiste via RequireClaim dat de gebruiker een greetings_api bereikclaim moet opgeven.

Het admin_greetings-beleid wordt geleverd als een vereist beleid voor het /hello-eindpunt.

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

dotnet user-jwts gebruiken voor ontwikkelingstests

In dit artikel wordt een app gebruikt die is geconfigureerd met verificatie op basis van JWT-bearer. Verificatie op basis van JWT bearer vereist dat clients een token in de aanvraagheader presenteren om hun identiteit en claims te valideren. Deze tokens worden doorgaans uitgegeven door een centrale instantie, zoals een identiteitsserver.

Bij het ontwikkelen op de lokale computer kan het hulpprogramma dotnet user-jwts worden gebruikt om bearer-tokens te maken.

dotnet user-jwts create

Tokens kunnen worden geconfigureerd met verschillende aanpassingen. Als u bijvoorbeeld een token wilt maken voor de admin-rol en het greetings_api-bereik, zoals verwacht door het autorisatiebeleid in de vorige code:

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

Het gegenereerde token kan vervolgens worden meegestuurd als onderdeel van de header in het testhulpprogramma naar keuze. Bijvoorbeeld met curl:

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

Voor meer informatie over het hulpprogramma dotnet user-jwts, lees de volledige documentatie.