Condividi tramite

Autenticazione e autorizzazione in API minime

Nota

Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 9 di questo articolo.

Avviso

Questa versione di ASP.NET Core non è più supportata. Per altre informazioni, vedere i criteri di supporto di .NET e .NET Core. Per la versione corrente, vedere la versione .NET 9 di questo articolo.

Importante

Queste informazioni si riferiscono a un prodotto non definitive che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Per la versione corrente, vedere la versione .NET 9 di questo articolo.

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

Concetti chiave nell'autenticazione e nell'autorizzazione

L'autenticazione è il processo di determinazione dell'identità di un utente. L'autorizzazione è il processo con cui si determina se un utente ha accesso a una risorsa. Gli scenari di autenticazione e autorizzazione condividono una semantica di implementazione simile in ASP.NET Core. L'autenticazione viene gestita dal servizio di autenticazione IAuthenticationService, usato dal middleware di autenticazione. L'autorizzazione viene gestita dal servizio di autorizzazione IAuthorizationService, che viene usato dal middleware di autorizzazione.

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.

Esistono due strategie per determinare l'accesso utente alle risorse nel livello di autorizzazione:

  • 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 sfrutta i gestori di autorizzazione per determinare se un determinato utente soddisfa o meno i requisiti di autorizzazione applicati a una risorsa.

Abilitazione dell'autenticazione in app minime

Per abilitare l'autenticazione, chiamare 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 su bearer JWT. Questo esempio usa le API disponibili nel Microsoft.AspNetCore.Authentication.JwtBearer pacchetto 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();

Per impostazione predefinita, WebApplication registra automaticamente i middleware di autenticazione e autorizzazione se sono abilitati determinati servizi di autenticazione e autorizzazione. Nell'esempio seguente non è necessario richiamare UseAuthentication o UseAuthorization registrare i middleware perché WebApplication esegue questa operazione automaticamente dopo AddAuthentication o AddAuthorization vengono chiamati.

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 ulteriori informazioni sui middleware e su questo comportamento automatico, consultare Middleware nelle applicazioni 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();

Configurazione della strategia di autenticazione

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

Il framework ASP.NET Core prevede di trovare queste opzioni nella sezione Authentication:Schemes:{SchemeName} della configurazione. 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 usata.

{
  "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.cs, vengono registrate due strategie di autenticazione basate su JWT bearer, con:

  • Nome dello schema Bearer.
  • Nome dello schema "LocalAuthIssuer".

"Bearer" è il tipico schema predefinito nelle app abilitate tramite JWT-bearer, ma lo schema predefinito può essere modificato impostando la proprietà DefaultScheme come mostrato nell'esempio precedente.

Il nome dello schema viene usato per identificare in modo univoco una strategia di autenticazione e viene usato 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();

Configurazione dei criteri di autorizzazione in app minime

L'autenticazione viene usata per identificare e convalidare l'identità degli utenti rispetto a un'API. L'autorizzazione viene usata per convalidare e verificare l'accesso alle risorse IAuthorizationService in un'API ed è facilitata dal metodo di estensione registrato AddAuthorization. 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 che richiede:

  1. Configurazione dei requisiti di autorizzazione in una politica a livello globale.
  2. Applicazione di singoli criteri alle risorse.

Nel codice seguente viene richiamato AddAuthorizationBuilder:

  • Aggiunge servizi relativi all'autorizzazione al contenitore DI.
  • Restituisce un oggetto AuthorizationBuilder 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 admin ruolo.
  • Requisito basato sull'attestazione tramite RequireClaim, in cui l'utente deve fornire una dichiarazione greetings_api di ambito.

Il admin_greetings criterio viene fornito come criterio obbligatorio 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();

Uso dotnet user-jwts per i test di sviluppo

In questo articolo viene usata un'app configurata con l'autenticazione basata su JWT bearer. L'autenticazione basata su token bearer richiede che i client presentino un token nell'intestazione della richiesta per convalidare l'identità e le asserzioni. In genere, questi token vengono emessi da un'autorità centrale, ad esempio un server di gestione delle identità.

Durante lo sviluppo sulla macchina locale, lo strumento dotnet user-jwts può essere usato per creare token di accesso.

dotnet user-jwts create

Nota

Quando viene richiamato in un progetto, lo strumento aggiunge automaticamente le opzioni di autenticazione corrispondenti al token generato a appsettings.json.

I token possono essere configurati con un'ampia gamma di personalizzazioni. Ad esempio, per creare un token per il ruolo e admin l'ambito greetings_api previsti dai criteri di autorizzazione nel codice precedente:

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, con curl:

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

Per altre informazioni sullo dotnet user-jwts strumento, vedere la documentazione completa.