Condividi tramite

Autenticazione e autorizzazione in API minime

  • Articolo

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 di un utente.identity 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 autentica un utente o la disconnessione di 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, ad esempio il controllo dell'ordine del middleware, è necessario registrare in modo esplicito l'autenticazione e l'autorizzazione. Nell'esempio seguente il middleware di autenticazione viene eseguito dopo l'esecuzione del middleware CORS. Per altre informazioni sui 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();

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 nella Authentication:Schemes:{SchemeName} configurazione. Nell'esempio seguente vengono definiti due schemi diversi e Bearer LocalAuthIssuer, 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.csdue strategie di autenticazione basate su bearer JWT vengono registrate con:

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

"Bearer" è lo schema predefinito tipico nelle app abilitate per il bearer JWT, ma lo schema predefinito può essere sottoposto a override impostando la DefaultScheme proprietà come 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'oggetto identity degli utenti rispetto a un'API. L'autorizzazione viene usata per convalidare e verificare l'accesso IAuthorizationService alle risorse in un'API ed è facilitata dal AddAuthorization metodo di estensione registrato. Nello scenario seguente viene aggiunta una /hello risorsa che richiede a un utente di presentare un'attestazione admin di ruolo con un'attestazione 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 un criterio a livello globale.
  2. Applicazione di singoli criteri alle risorse.

Nel codice seguente viene AddAuthorizationBuilder richiamato il seguente:

  • Aggiunge servizi correlati all'autorizzazione al contenitore di inserimento delle dipendenze.
  • 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 il quale l'utente deve fornire un'attestazione 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 connessione JWT. L'autenticazione basata su bearer JWT richiede che i client presentino un token nell'intestazione della richiesta per convalidare identity le attestazioni e . In genere, questi token vengono emessi da un'autorità centrale, ad esempio un identity server.

Durante lo sviluppo nel computer locale, lo dotnet user-jwts strumento può essere usato per creare token di connessione.

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 greetings_api l'ambito admin 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.