Autenticazione e autorizzazione nelle API minime

Le API minime supportano tutte le opzioni di autenticazione e autorizzazione disponibili in ASP.NET Core e offrono funzionalità aggiuntive per migliorare l'esperienza di gestione dell'autenticazione.

Questo articolo descrive il supporto per l'autenticazione e l'autorizzazione nelle applicazioni API minime e come configurare e testare la funzionalità.

Esaminare i concetti relativi all'autenticazione e all'autorizzazione

L'autenticazione è il processo di determinazione dell'identità di un utente mentre l'autorizzazione è il processo di determinazione dell'accesso a una risorsa da parte di un utente. Gli scenari di autenticazione e autorizzazione condividono una semantica di implementazione simile in ASP.NET Core.

• Il servizio di autenticazione , IAuthenticationService, gestisce tutte le autenticazioni e viene usato dal middleware di autenticazione.
• Il servizio di autorizzazione , IAuthorizationService, gestisce tutte le autorizzazioni e viene usato dal middleware di autorizzazione.

Servizio di autenticazione

Il servizio di autenticazione usa i gestori di autenticazione registrati per completare le azioni correlate all'autenticazione. Ad esempio, un'azione correlata all'autenticazione è autenticare un utente o disconnettere un utente. Gli schemi di autenticazione sono nomi usati per identificare in modo univoco un gestore di autenticazione e le relative opzioni di configurazione. I gestori di autenticazione sono responsabili dell'implementazione delle strategie per l'autenticazione e la generazione di attestazioni di un utente in base a una particolare strategia di autenticazione, ad esempio OAuth o OIDC. Le opzioni di configurazione sono univoche per la strategia e forniscono al gestore la configurazione che influisce sul comportamento di autenticazione, ad esempio gli URI di reindirizzamento.

Servizio di autorizzazione

Nel livello di autorizzazione sono disponibili due strategie per determinare l'accesso utente alle risorse:

• Le strategie basate sui ruoli determinano l'accesso di un utente in base al ruolo assegnato, ad esempio Administrator o User. Per altre informazioni sull'autorizzazione basata sui ruoli, vedere la documentazione sull'autorizzazione basata sui ruoli.

• Le strategie basate sulle attestazioni determinano l'accesso di un utente in base alle attestazioni rilasciate da un'autorità centrale. Per altre informazioni sull'autorizzazione basata su attestazioni, vedere la documentazione sull'autorizzazione basata su attestazioni.

In ASP.NET Core entrambe le strategie vengono acquisite in un requisito di autorizzazione. Il servizio di autorizzazione usa gestori di autorizzazione per determinare se un determinato utente soddisfa o meno i requisiti di autorizzazione per una risorsa.

Abilitare l'autenticazione in app minime

Per abilitare l'autenticazione, chiamare il metodo AddAuthentication per registrare i servizi di autenticazione necessari nel provider di servizi dell'app.

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

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

In genere viene usata una strategia di autenticazione specifica. Nell'esempio seguente l'app viene configurata con il supporto per l'autenticazione basata sul bearer token JSON Web (JWT). Questo esempio utilizza le API disponibili nel pacchetto NuGet Microsoft.AspNetCore.Authentication.JwtBearer.

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

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

Per impostazione predefinita, WebApplication registra automaticamente il middleware di autenticazione e autorizzazione se sono abilitati determinati servizi di autenticazione e autorizzazione. Nell'esempio seguente non è necessario richiamare i metodi UseAuthentication o UseAuthorization per registrare il middleware. WebApplication completa automaticamente la registrazione dopo aver chiamato il AddAuthentication metodo o AddAuthorization .

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

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

In alcuni casi, come nel controllo dell'ordine del middleware, è necessario registrare esplicitamente l'autenticazione e l'autorizzazione. Nell'esempio seguente il middleware di autenticazione viene eseguito dopo l'esecuzione del middleware CORS. Per altre informazioni sul middleware e questo comportamento automatico, vedere Middleware nelle app per le API minime.

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

Configurare la strategia di autenticazione

Le strategie di autenticazione supportano in genere varie configurazioni caricate tramite opzioni. Le app minime supportano le opzioni di caricamento dalla configurazione per le strategie di autenticazione seguenti:

• Autenticazione basata su bearer JWT
• Autenticazione basata su OpenID Connect

Il framework di ASP.NET Core prevede di trovare queste opzioni nella sezione Authentication:Schemes:{SchemeName} del configuration. Nell'esempio seguente vengono definiti due schemi diversi e BearerLocalAuthIssuer, con le rispettive opzioni. L'opzione Authentication:DefaultScheme può essere usata per configurare la strategia di autenticazione predefinita.

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

Nel file Program.cs vengono registrate due strategie di autenticazione basate su bearer JWT con i nomi di schema seguenti:

• Portatore
• "LocalAuthIssuer"

"Bearer" è lo schema predefinito comunemente utilizzato nelle app abilitate per il JWT-bearer. Tuttavia, è possibile eseguire l'override dello schema predefinito impostando la DefaultScheme proprietà come illustrato nell'esempio precedente.

Il nome dello schema viene usato per identificare in modo univoco una strategia di autenticazione. Il nome viene usato anche come chiave di ricerca durante la risoluzione delle opzioni di autenticazione dalla configurazione, come illustrato nell'esempio seguente:

var builder = WebApplication.CreateBuilder(args);

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

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

Configurare i criteri di autorizzazione in app minime

L'autenticazione identifica e convalida l'identità degli utenti rispetto a un'API. L'autorizzazione convalida e verifica l'accesso alle risorse in un'API. Il servizio IAuthorizationService registrato dal metodo di estensione AddAuthorization facilita l'autorizzazione. Nello scenario seguente viene aggiunta una /hello risorsa, che richiede a un utente di fornire una dichiarazione admin di ruolo con una dichiarazione greetings_api di ambito.

La configurazione dei requisiti di autorizzazione per una risorsa è un processo in due passaggi:

1. Definire i requisiti di autorizzazione in un criterio a livello globale.
2. Applicare i singoli criteri alle risorse.

Nel codice seguente viene richiamato il AddAuthorizationBuilder metodo , che:

• Aggiunge servizi relativi all'autorizzazione al contenitore DI.
• Restituisce un AuthorizationBuilder oggetto che può essere utilizzato per registrare direttamente i criteri di autorizzazione.

Il codice crea un nuovo criterio di autorizzazione denominato admin_greetings che incapsula due requisiti di autorizzazione:

• Requisito basato sui ruoli tramite RequireRole per gli utenti con un ruolo di admin.
• Requisito basato sulla dichiarazione tramite il RequireClaim per cui l'utente deve fornire una dichiarazione greetings_api di ambito.

La admin_greetings politica viene fornita come politica richiesta per l'endpoint /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();

Usare 'dotnet user-jwts' per i test di sviluppo

Gli esempi in questo articolo usano un'app configurata con l'autenticazione basata su bearer JWT. L'autenticazione basata su bearer JWT richiede ai client di presentare un token nell'intestazione della richiesta, che viene usato per convalidare l'identità e le attestazioni. In genere, un'autorità centrale come un server di identità rilascia i token.

Per lo sviluppo su un computer locale, lo strumento da riga di comando dotnet user-jwts può essere usato per creare token di autenticazione.

dotnet user-jwts create

I token possono essere configurati con varie personalizzazioni. Ad esempio, per creare un token per il ruolo e admin l'ambito greetings_api previsti dai criteri di autorizzazione nel codice precedente, eseguire lo strumento come indicato di seguito:

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

Il token generato può quindi essere inviato come parte dell'intestazione nello strumento di test scelto. Ad esempio, per inviare il token con curl:

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

Contenuti correlati

• Servizio di autenticazione (IAuthenticationService)
• Servizio di autorizzazione (IAuthorizationService)
• ASP.NET Core Middleware
• Gestire token Web JSON con lo strumento dotnet user-jwts