Come usare Identity per proteggere un back-end dell'API Web per le applicazioni a pagina singola

ASP.NET Core Identity fornisce API che gestiscono l'autenticazione, l'autorizzazione e identity la gestione. Le API consentono di proteggere gli endpoint di un back-end dell'API Web con cookiel'autenticazione basata su . Un'opzione basata su token è disponibile per i client che non possono usare i cookie, ma in questo modo si è responsabili della sicurezza dei token. È consigliabile usare i cookie per le applicazioni basate su browser, perché, per impostazione predefinita, il browser li gestisce automaticamente senza esporli a JavaScript.

Questo articolo illustra come usare Identity per proteggere un back-end dell'API Web per le app spA, ad esempio Angular, React e Vue. Le stesse API back-end possono essere usate per proteggere Blazor WebAssembly le app.

Prerequisiti

I passaggi illustrati in questo articolo aggiungono l'autenticazione e l'autorizzazione a un'app api Web core di ASP.NET che:

• Non è già configurato per l'autenticazione.
• Destinazioni net8.0 o versioni successive.
• Può essere un'API minima o un'API basata su controller.

Alcune delle istruzioni di test in questo articolo usano l'interfaccia utente di Swagger inclusa nel modello di progetto. L'interfaccia utente di Swagger non è necessaria per l'uso Identity con un back-end dell'API Web.

Installare i pacchetti NuGet

Installare i pacchetti NuGet seguenti:

• Microsoft.AspNetCore.Identity.EntityFrameworkCore - Consente di Identity usare Entity Framework Core (EF Core).
• Uno che consente di EF Core usare un database, ad esempio uno dei pacchetti seguenti:
  • Microsoft.EntityFrameworkCore.SqlServer oppure
  • Microsoft.EntityFrameworkCore.Sqlite oppure
  • Microsoft.EntityFrameworkCore.InMemory.

Per iniziare più rapidamente, usare il database in memoria.

Modificare il database in un secondo momento in SQLite o SQL Server per salvare i dati utente tra sessioni durante i test o per l'uso in produzione. Ciò introduce una certa complessità rispetto alla memoria, perché richiede che il database venga creato tramite migrazioni, come illustrato nell'esercitazione EF Coreintroduttiva.

Installare questi pacchetti usando gestione pacchetti NuGet in Visual Studio o il comando dotnet add package CLI.

Creare una chiave IdentityDbContext

Aggiungere una classe denominata ApplicationDbContext che eredita da IdentityDbContext<TUser>:

using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;

public class ApplicationDbContext : IdentityDbContext<IdentityUser>
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) :
        base(options)
    { }
}

Il codice illustrato fornisce un costruttore speciale che consente di configurare il database per ambienti diversi.

Aggiungere una o più delle direttive seguenti using in base alle esigenze quando si aggiunge il codice illustrato in questi passaggi.

using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;

Configurare il EF Core contesto

Come indicato in precedenza, il modo più semplice per iniziare consiste nell'usare il database in memoria. Ogni esecuzione in memoria inizia con un nuovo database e non è necessario usare le migrazioni. Dopo la chiamata a WebApplication.CreateBuilder(args), aggiungere il codice seguente per configurare Identity per l'uso di un database in memoria:

builder.Services.AddDbContext<ApplicationDbContext>(
    options => options.UseInMemoryDatabase("AppDb"));

Per salvare i dati utente tra sessioni durante i test o per l'uso in produzione, modificare il database in un secondo momento in SQLite o SQL Server.

Aggiungere Identity servizi al contenitore

Dopo la chiamata a WebApplication.CreateBuilder(args), chiamare AddAuthorization per aggiungere servizi al contenitore di inserimento delle dipendenze:

builder.Services.AddAuthorization();

Attivare Identity le API

Dopo la chiamata a WebApplication.CreateBuilder(args), chiamare AddIdentityApiEndpoints<TUser>(IServiceCollection) e AddEntityFrameworkStores<TContext>(IdentityBuilder).

builder.Services.AddIdentityApiEndpoints<IdentityUser>()
    .AddEntityFrameworkStores<ApplicationDbContext>();

Per impostazione predefinita, vengono attivati sia i cookie che i token proprietari. I cookie e i token vengono emessi all'account di accesso se il parametro della useCookies stringa di query nell'endpoint di accesso è true.

Mappa Identity itinerari

Dopo la chiamata a builder.Build(), chiamare MapIdentityApi<TUser>(IEndpointRouteBuilder) per eseguire il mapping degli Identity endpoint:

app.MapIdentityApi<IdentityUser>();

Proteggere gli endpoint selezionati

Per proteggere un endpoint, usare il RequireAuthorization metodo di estensione nella Map{Method} chiamata che definisce la route. Ad esempio:

app.MapGet("/weatherforecast", (HttpContext httpContext) =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = summaries[Random.Shared.Next(summaries.Length)]
        })
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi()
.RequireAuthorization();

Il RequireAuthorization metodo può essere usato anche per:

• Proteggere gli endpoint dell'interfaccia utente di Swagger, come illustrato nell'esempio seguente:

  app.MapSwagger().RequireAuthorization();
  

• Proteggere con un'attestazione o un'autorizzazione specifica, come illustrato nell'esempio seguente:

  .RequireAuthorization("Admin");
  

In un progetto api Web basato su controller, gli endpoint sicuri applicando l'attributo [Authorize] a un controller o a un'azione.

Testare l'API

Un modo rapido per testare l'autenticazione consiste nell'usare il database in memoria e l'interfaccia utente di Swagger inclusa nel modello di progetto. I passaggi seguenti illustrano come testare l'API con l'interfaccia utente di Swagger. Assicurarsi che gli endpoint dell'interfaccia utente di Swagger non siano protetti.

Tentare di accedere a un endpoint protetto

• Eseguire l'app e passare all'interfaccia utente di Swagger.
• Espandere un endpoint protetto, ad esempio /weatherforecast in un progetto creato dal modello api Web.
• Selezionare Prova.
• Seleziona Execute. La risposta è 401 - not authorized.

Testare la registrazione

• Espandere /register e selezionare Prova.

• Nella sezione Parametri dell'interfaccia utente viene visualizzato un corpo della richiesta di esempio:

  {
    "email": "string",
    "password": "string"
  }
  

• Sostituire "string" con un indirizzo di posta elettronica e una password validi e quindi selezionare Esegui.

  Per rispettare le regole di convalida della password predefinite, la password deve avere una lunghezza di almeno sei caratteri e contenere almeno uno dei caratteri seguenti:

  • Lettera maiuscola
  • Lettera minuscola
  • Cifra numerica
  • Carattere non alfanumerico

  Se si immette un indirizzo di posta elettronica non valido o una password non valida, il risultato include gli errori di convalida. Ecco un esempio di corpo della risposta con errori di convalida:

  {
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
      "PasswordTooShort": [
        "Passwords must be at least 6 characters."
      ],
      "PasswordRequiresNonAlphanumeric": [
        "Passwords must have at least one non alphanumeric character."
      ],
      "PasswordRequiresDigit": [
        "Passwords must have at least one digit ('0'-'9')."
      ],
      "PasswordRequiresLower": [
        "Passwords must have at least one lowercase ('a'-'z')."
      ]
    }
  }
  

  Gli errori vengono restituiti nel formato ProblemDetails in modo che il client possa analizzarli e visualizzare gli errori di convalida in base alle esigenze.

  Una registrazione riuscita restituisce una 200 - OK risposta.

Testare l'account di accesso

• Espandere /login e selezionare Prova. Il corpo della richiesta di esempio mostra due parametri aggiuntivi:

  {
    "email": "string",
    "password": "string",
    "twoFactorCode": "string",
    "twoFactorRecoveryCode": "string"
  }
  

  Le proprietà JSON aggiuntive non sono necessarie per questo esempio e possono essere eliminate. Impostare useCookies su true.

• Sostituire "string" con l'indirizzo di posta elettronica e la password usati per la registrazione e quindi selezionare Esegui.

  Un account di accesso riuscito restituisce una 200 - OK risposta con un cookie nell'intestazione della risposta.

Eseguire il nuovo test dell'endpoint protetto

Dopo aver completato l'accesso, eseguire di nuovo l'endpoint protetto. L'autenticazione cookie viene inviata automaticamente con la richiesta e l'endpoint è autorizzato. CookieL'autenticazione basata su è integrata in modo sicuro nel browser e "funziona".

Test con client nonbrowser

Alcuni client Web potrebbero non includere cookie nell'intestazione per impostazione predefinita:

• Se si usa uno strumento per testare le API, potrebbe essere necessario abilitare i cookie nelle impostazioni.

• L'API JavaScript fetch non include cookie per impostazione predefinita. Abilitarli impostando credentials sul valore include nelle opzioni.

• Un HttpClient oggetto in esecuzione in un'app Blazor WebAssembly deve HttpRequestMessage includere le credenziali, come nell'esempio seguente:

  request.SetBrowserRequestCredential(BrowserRequestCredentials.Include);
  

usare l'autenticazione basata su token

È consigliabile usare i cookie nelle applicazioni basate su browser, perché, per impostazione predefinita, il browser li gestisce automaticamente senza esporli a JavaScript.

Viene generato un token personalizzato (proprietario della piattaforma ASP.NET Core identity ) che può essere usato per autenticare le richieste successive. Il token viene passato nell'intestazione Authorization come token di connessione. Viene fornito anche un token di aggiornamento. Questo token consente all'applicazione di richiedere un nuovo token alla scadenza di quella precedente senza forzare l'accesso dell'utente.

I token non sono token Web JSON standard (JWT). L'uso di token personalizzati è intenzionale, perché l'API predefinita Identity è destinata principalmente a scenari semplici. L'opzione token non è progettata per essere un provider di servizi o un server di token completo identity , ma un'alternativa all'opzione cookie per i client che non possono usare i cookie.

Per usare l'autenticazione basata su token, impostare il parametro della useCookies stringa di query su false quando si chiama l'endpoint /login . I token usano lo schema di autenticazione di connessione . Usando il token restituito dalla chiamata a /login, le chiamate successive agli endpoint protetti devono aggiungere l'intestazione Authorization: Bearer <token> dove <token> è il token di accesso. Per altre informazioni, vedere Usare l'endpoint POST /login più avanti in questo articolo.

Effettuare la disconnessione

Per consentire all'utente di disconnettersi, definire un /logout endpoint come nell'esempio seguente:

app.MapPost("/logout", async (SignInManager<IdentityUser> signInManager,
    [FromBody] object empty) =>
{
    if (empty != null)
    {
        await signInManager.SignOutAsync();
        return Results.Ok();
    }
    return Results.Unauthorized();
})
.WithOpenApi()
.RequireAuthorization();

Specificare un oggetto JSON vuoto ({}) nel corpo della richiesta quando si chiama questo endpoint. Il codice seguente è un esempio di chiamata all'endpoint di disconnessione:

public signOut() {
  return this.http.post('/logout', {}, {
    withCredentials: true,
    observe: 'response',
    responseType: 'text'

Endpoint MapIdentityApi<TUser>

La chiamata a MapIdentityApi<TUser> aggiunge gli endpoint seguenti all'app:

• POST /register
• POST /login
• POST /refresh
• GET /confirmEmail
• POST /resendConfirmationEmail
• POST /forgotPassword
• POST /resetPassword
• POST /manage/2fa
• GET /manage/info
• POST /manage/info

Usare l'endpoint POST /register

Il corpo della richiesta deve avere Email proprietà e Password :

{
  "email": "string",
  "password": "string",
}

Per altre informazioni, vedi:

• Testare la registrazione in precedenza in questo articolo.
• RegisterRequest.

Usare l'endpoint POST /login

Nel corpo Email della richiesta e Password sono necessari. Se l'autenticazione a due fattori (2FA) è abilitata, TwoFactorCode o TwoFactorRecoveryCode è necessaria. Se 2FA non è abilitato, omettere sia twoFactorCode che twoFactorRecoveryCode. Per altre informazioni, vedere Usare l'endpoint POST /manage/2fa più avanti in questo articolo.

Ecco un esempio di corpo della richiesta con 2FA non abilitato:

{
  "email": "string",
  "password": "string"
}

Ecco alcuni esempi di corpo della richiesta con 2FA abilitato:

• {
    "email": "string",
    "password": "string",
    "twoFactorCode": "string",
  }
  

• {
    "email": "string",
    "password": "string",
    "twoFactorRecoveryCode": "string"
  }
  

L'endpoint prevede un parametro della stringa di query:

• useCookies - Impostare su true per cookiel'autenticazione basata su . Impostare su o omettere false per l'autenticazione basata su token.

Per altre informazioni sull'autenticazione cookiebasata su , vedere Testare l'accesso in precedenza in questo articolo.

Autenticazione basata su token

Se useCookies viene false omesso, l'autenticazione basata su token è abilitata. Il corpo della risposta include le proprietà seguenti:

{
  "tokenType": "string",
  "accessToken": "string",
  "expiresIn": 0,
  "refreshToken": "string"
}

Per altre informazioni su queste proprietà, vedere AccessTokenResponse.

Inserire il token di accesso in un'intestazione per effettuare richieste autenticate, come illustrato nell'esempio seguente

Authorization: Bearer {access token}

Quando il token di accesso sta per scadere, chiamare l'endpoint /refresh .

Usare l'endpoint POST /refresh

Per l'uso solo con l'autenticazione basata su token. Ottiene un nuovo token di accesso senza forzare l'accesso dell'utente. Chiamare questo endpoint quando il token di accesso sta per scadere.

Il corpo della richiesta contiene solo .RefreshToken Ecco un esempio di corpo della richiesta:

{
  "refreshToken": "string"
}

Se la chiamata ha esito positivo, il corpo della risposta è un nuovo AccessTokenResponse, come illustrato nell'esempio seguente:

{
  "tokenType": "string",
  "accessToken": "string",
  "expiresIn": 0,
  "refreshToken": "string"
}

Usare l'endpoint GET /confirmEmail

Se Identity è configurata per la conferma tramite posta elettronica, una chiamata all'endpoint /register invia un messaggio di posta elettronica contenente un collegamento all'endpoint /confirmEmail . Il collegamento contiene i parametri della stringa di query seguenti:

• userId
• code
• changedEmail - Incluso solo se l'utente ha modificato l'indirizzo di posta elettronica durante la registrazione.

Identity fornisce il testo predefinito per il messaggio di posta elettronica di conferma. Per impostazione predefinita, l'oggetto del messaggio di posta elettronica è "Conferma il messaggio di posta elettronica" e il corpo del messaggio di posta elettronica è simile all'esempio seguente:

 Please confirm your account by <a href='https://contoso.com/confirmEmail?userId={user ID}&code={generated code}&changedEmail={new email address}'>clicking here</a>.

Se la RequireConfirmedEmail proprietà è impostata su true, l'utente non può accedere finché l'indirizzo di posta elettronica non viene confermato facendo clic sul collegamento nel messaggio di posta elettronica. Endpoint /confirmEmail :

• Conferma l'indirizzo di posta elettronica e consente all'utente di accedere.
• Restituisce il testo "Grazie per confermare il messaggio di posta elettronica." nel corpo della risposta.

Per configurare Identity la conferma tramite posta elettronica, aggiungere il codice in Program.cs per impostare RequireConfirmedEmail true e aggiungere una classe che implementa al contenitore di inserimento delle dipendenze IEmailSender . Ad esempio:

builder.Services.Configure<IdentityOptions>(options =>
{
    options.SignIn.RequireConfirmedEmail = true;
});

builder.Services.AddTransient<IEmailSender, EmailSender>();

Per altre informazioni, vedere Conferma dell'account e ripristino della password in ASP.NET Core.

Identity fornisce testo predefinito per gli altri messaggi di posta elettronica che devono essere inviati, ad esempio per 2FA e reimpostazione della password. Per personalizzare questi messaggi di posta elettronica, fornire un'implementazione personalizzata dell'interfaccia IEmailSender . Nell'esempio precedente è EmailSender una classe che implementa IEmailSender. Per altre informazioni, incluso un esempio di classe che implementa IEmailSender, vedere Conferma dell'account e ripristino della password in ASP.NET Core.

Usare l'endpoint POST /resendConfirmationEmail

Invia un messaggio di posta elettronica solo se l'indirizzo è valido per un utente registrato.

Il corpo della richiesta contiene solo .Email Ecco un esempio di corpo della richiesta:

{
  "email": "string"
}

Per altre informazioni, vedere Usare l'endpoint GET /confirmEmail in precedenza in questo articolo.

Usare l'endpoint POST /forgotPassword

Genera un messaggio di posta elettronica contenente un codice di reimpostazione della password. Inviare il codice a /resetPassword con una nuova password.

Il corpo della richiesta contiene solo .Email Ecco un esempio:

{
  "email": "string"
}

Per informazioni su come abilitare Identity l'invio di messaggi di posta elettronica, vedere Usare l'endpointGET /confirmEmail.

Usare l'endpoint POST /resetPassword

Chiamare questo endpoint dopo aver ottenuto un codice di reimpostazione chiamando l'endpoint /forgotPassword .

Il corpo della richiesta richiede Email, ResetCodee NewPassword. Ecco un esempio:

{
  "email": "string",
  "resetCode": "string",
  "newPassword": "string"
}

Usare l'endpoint POST /manage/2fa

Configura l'autenticazione a due fattori (2FA) per l'utente. Quando la funzionalità 2FA è abilitata, l'accesso con esito positivo richiede un codice prodotto da un'app di autenticazione oltre all'indirizzo di posta elettronica e alla password.

Abilitare 2FA

Per abilitare 2FA per l'utente attualmente autenticato:

• Chiamare l'endpoint /manage/2fa , inviando un oggetto JSON vuoto ({}) nel corpo della richiesta.

• Il corpo della SharedKey risposta fornisce insieme ad altre proprietà che non sono necessarie a questo punto. La chiave condivisa viene usata per configurare l'app di autenticazione. Esempio di corpo della risposta:

  {
    "sharedKey": "string",
    "recoveryCodesLeft": 0,
    "recoveryCodes": null,
    "isTwoFactorEnabled": false,
    "isMachineRemembered": false
  }
  

• Usare la chiave condivisa per ottenere una password monouso basata sul tempo (TOTP). Per altre informazioni, vedere Abilitare la generazione di codice a matrice per le app di autenticazione TOTP in ASP.NET Core.

• Chiamare l'endpoint /manage/2fa , inviando TOTP e "enable": true nel corpo della richiesta. Ad esempio:

  {
    "enable": true,
    "twoFactorCode": "string"
  }
  

• Il corpo della risposta conferma che IsTwoFactorEnabled è true e fornisce .RecoveryCodes I codici di ripristino vengono usati per accedere quando l'app di autenticazione non è disponibile. Esempio di corpo della risposta dopo aver abilitato correttamente 2FA:

  {
    "sharedKey": "string",
    "recoveryCodesLeft": 10,
    "recoveryCodes": [
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string"
    ],
    "isTwoFactorEnabled": true,
    "isMachineRemembered": false
  }
  

Accedere con 2FA

Chiamare l'endpoint, inviare l'indirizzo /login di posta elettronica, la password e TOTP nel corpo della richiesta. Ad esempio:

{
  "email": "string",
  "password": "string",
  "twoFactorCode": "string"
}

Se l'utente non ha accesso all'app di autenticazione, accedere chiamando l'endpoint /login con uno dei codici di ripristino forniti quando è stata abilitata la funzionalità 2FA. Il corpo della richiesta è simile all'esempio seguente:

{
  "email": "string",
  "password": "string",
  "twoFactorRecoveryCode": "string"
}

Reimpostare i codici di ripristino

Per ottenere una nuova raccolta di codici di ripristino, chiamare questo endpoint con ResetRecoveryCodes impostato su true. Ecco un esempio di corpo della richiesta:

{
  "resetRecoveryCodes": true
}

Reimpostare la chiave condivisa

Per ottenere una nuova chiave condivisa casuale, chiamare questo endpoint con ResetSharedKey impostato su true. Ecco un esempio di corpo della richiesta:

{
  "resetSharedKey": true
}

La reimpostazione della chiave disabilita automaticamente il requisito di accesso a due fattori per l'utente autenticato fino a quando non viene riabilitato da una richiesta successiva.

Dimenticare la macchina

Per cancellare il cookie flag "ricordami" se presente, chiamare questo endpoint con ForgetMachine impostato su true. Ecco un esempio di corpo della richiesta:

{
  "forgetMachine": true
}

Questo endpoint non ha alcun impatto sull'autenticazione basata su token.

Usare l'endpoint GET /manage/info

Ottiene l'indirizzo di posta elettronica e lo stato di conferma tramite posta elettronica dell'utente connesso. Le attestazioni sono state omesse da questo endpoint per motivi di sicurezza. Se sono necessarie attestazioni, usare le API lato server per configurare un endpoint per le attestazioni. In alternativa, invece di condividere tutte le attestazioni degli utenti, fornire un endpoint di convalida che accetta un'attestazione e risponde se l'utente lo ha.

La richiesta non richiede parametri. Il corpo della risposta include le Email proprietà e IsEmailConfirmed , come nell'esempio seguente:

{
  "email": "string",
  "isEmailConfirmed": true
}

Usare l'endpoint POST /manage/info

Aggiorna l'indirizzo di posta elettronica e la password dell'utente connesso. Inviare NewEmail, NewPassworde OldPassword nel corpo della richiesta, come illustrato nell'esempio seguente:

{
  "newEmail": "string",
  "newPassword": "string",
  "oldPassword": "string"
}

Ecco un esempio del corpo della risposta:

{
  "email": "string",
  "isEmailConfirmed": false
}

Vedi anche

Per ulteriori informazioni, vedi le seguenti risorse:

• Scegliere una identity soluzione di gestione
• Identity soluzioni di gestione per le app Web .NET
• Autorizzazione semplice in ASP.NET Core
• Aggiungere, scaricare ed eliminare i dati Identity utente in un progetto ASP.NET Core
• Creare un'app ASP.NET Core con i dati utente protetti da autorizzazione
• Account confirmation and password recovery in ASP.NET Core (Conferma dell'account e recupero della password in ASP.NET Core)
• Abilitare la generazione di codice a matrice per le app di autenticazione TOTP in ASP.NET Core
• Back-end dell'API Web di esempio per spAS Il file .http mostra l'autenticazione basata su token. Ad esempio:
  • Non è impostato useCookies
  • Usa l'intestazione Authorization per passare il token
  • Mostra l'aggiornamento per estendere la sessione senza forzare nuovamente l'accesso dell'utente
• App Angular di esempio che usa Identity per proteggere un back-end dell'API Web