Identity Použití k zabezpečení back-endu webového rozhraní API pro služby SPA

ASP.NET Core Identity poskytuje rozhraní API, která zpracovávají ověřování, autorizaci a správu identit. Rozhraní API umožňují zabezpečit koncové body back-endu webového rozhraní API pomocí cookieověřování na základě. Existuje možnost založená na tokenech pro klienty, kteří nemůžou používat cookie.

Tento článek ukazuje, jak zabezpečit Identity back-end webového rozhraní API pro služby SPA, jako jsou aplikace Angular, React a Vue. Stejná back-endová rozhraní API je možné použít k zabezpečení Blazor WebAssembly aplikací.

Požadavky

Kroky uvedené v tomto článku přidávají ověřování a autorizaci do aplikace ASP.NET Core Web API, která:

• Není nakonfigurovaná pro ověřování.
• Cíle net8.0 nebo novější.
• Může to být buď minimální rozhraní API, nebo rozhraní API založené na kontroleru.

Některé pokyny k testování v tomto článku používají uživatelské rozhraní Swagger, které je součástí šablony projektu. Uživatelské rozhraní Swagger není nutné používat Identity s back-endem webového rozhraní API.

Instalace balíčků NuGet

Nainstalujte následující balíčky NuGet:

• Microsoft.AspNetCore.Identity.EntityFrameworkCore – Umožňuje Identity pracovat s Entity Framework Core (EF Core).
• Ten, který umožňuje EF Core pracovat s databází, například s jedním z následujících balíčků:
  • Microsoft.EntityFrameworkCore.SqlServer nebo
  • Microsoft.EntityFrameworkCore.Sqlite nebo
  • Microsoft.EntityFrameworkCore.InMemory.

Pro nejrychlejší způsob, jak začít, použijte databázi v paměti.

Později změňte databázi na SQLite nebo SQL Server, aby se při testování nebo použití v produkčním prostředí uložila uživatelská data mezi relacemi. To představuje určitou složitost v porovnání s pamětí, protože vyžaduje vytvoření databáze prostřednictvím migrací, jak je znázorněno v úvodním EF Core kurzu.

Nainstalujte tyto balíčky pomocí správce balíčků NuGet v sadě Visual Studio nebo příkazu dotnet add package CLI.

Vytvoření IdentityDbContext

Přidejte třídu s názvem ApplicationDbContext , která dědí z 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)
    { }
}

Zobrazený kód poskytuje speciální konstruktor, který umožňuje konfigurovat databázi pro různá prostředí.

Při přidávání kódu uvedeného v tomto postupu přidejte jednu nebo více následujících using direktiv podle potřeby.

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

EF Core Konfigurace kontextu

Jak už jsme uvedli dříve, nejjednodušší způsob, jak začít, je použít databázi v paměti. Při každém spuštění v paměti začíná nová databáze a není nutné používat migrace. Po volání WebApplication.CreateBuilder(args)přidejte následující kód, který nakonfiguruje Identity použití databáze v paměti:

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

Pokud chcete uložit uživatelská data mezi relacemi při testování nebo použití v produkčním prostředí, změňte databázi později na SQLite nebo SQL Server.

Přidání Identity služeb do kontejneru

Po volání WebApplication.CreateBuilder(args)volání volání AddAuthorization přidat služby do kontejneru injektáž závislostí (DI):

builder.Services.AddAuthorization();

Aktivace Identity rozhraní API

Po volání WebApplication.CreateBuilder(args), volání AddIdentityApiEndpoints<TUser>(IServiceCollection) a AddEntityFrameworkStores<TContext>(IdentityBuilder).

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

Ve výchozím nastavení se aktivují tokeny i cookieproprietární tokeny. CookieTokeny a tokeny se vydávají při přihlášení, pokud useCookies je trueparametr řetězce dotazu v koncovém bodu přihlášení .

Mapování Identity tras

Po volání builder.Build()volání volání MapIdentityApi<TUser>(IEndpointRouteBuilder) namapujte Identity koncové body:

app.MapIdentityApi<IdentityUser>();

Zabezpečení vybraných koncových bodů

K zabezpečení koncového bodu použijte metodu RequireAuthorization rozšíření pro Map{Method} volání, která definuje trasu. Příklad:

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

Metodu RequireAuthorization lze použít také k:

• Zabezpečení koncových bodů uživatelského rozhraní Swagger, jak je znázorněno v následujícím příkladu:

  app.MapSwagger().RequireAuthorization();
  

• Zabezpečení pomocí konkrétní deklarace identity nebo oprávnění, jak je znázorněno v následujícím příkladu:

  .RequireAuthorization("Admin");
  

V projektu webového rozhraní API založeném na kontroleru zabezpečte koncové body použitím atributu [Authorize] na kontroler nebo akci.

Testování rozhraní API

Rychlý způsob, jak otestovat ověřování, je použít databázi v paměti a uživatelské rozhraní Swagger, které je součástí šablony projektu. Následující kroky ukazují, jak otestovat rozhraní API pomocí uživatelského rozhraní Swagger. Ujistěte se, že koncové body uživatelského rozhraní Swagger nejsou zabezpečené.

Pokus o přístup k zabezpečenému koncovému bodu

• Spusťte aplikaci a přejděte do uživatelského rozhraní Swaggeru.
• Rozbalte zabezpečený koncový bod, například /weatherforecast v projektu vytvořeném šablonou webového rozhraní API.
• Vyberte Vyzkoušet.
• Vyberte Provést. Odpověď je 401 - not authorized.

Test registrace

• Rozbalte /register a vyberte Vyzkoušet.

• V části Parametry uživatelského rozhraní se zobrazí text ukázkového požadavku:

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

• Nahraďte řetězec platnou e-mailovou adresou a heslem a pak vyberte Spustit.

  Aby bylo možné dodržovat výchozí ověřovací pravidla hesla, musí mít heslo alespoň šest znaků a musí obsahovat alespoň jeden z následujících znaků:

  • Velké písmeno
  • Malá písmena
  • Číselná číslice
  • Nonalphanumeric character

  Pokud zadáte neplatnou e-mailovou adresu nebo chybné heslo, výsledek bude obsahovat chyby ověření. Tady je příklad textu odpovědi s chybami ověření:

  {
    "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')."
      ]
    }
  }
  

  Chyby se vrátí ve formátu ProblemDetails , aby je klient mohl parsovat a zobrazovat chyby ověření podle potřeby.

  Výsledkem úspěšné registrace je 200 - OK odpověď.

Testovací přihlášení

• Rozbalte /login a vyberte Vyzkoušet. Příklad textu požadavku ukazuje dva další parametry:

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

  V tomto příkladu nejsou potřeba další JSvlastnosti ON a je možné je odstranit. Nastavte useCookies na hodnotu true.

• Nahraďte řetězec e-mailovou adresou a heslem, které jste použili k registraci, a pak vyberte Spustit.

  Úspěšné přihlášení způsobí 200 - OK odpověď s hlavičkou cookie odpovědi.

Opětovné otestování zabezpečeného koncového bodu

Po úspěšném přihlášení spusťte zabezpečený koncový bod znovu. cookie Ověřování se automaticky odešle s požadavkem a koncový bod je autorizovaný. CookieOvěřování založené na základě je bezpečně integrované v prohlížeči a "funguje".

Testování s využitím nepobrojených klientů

Někteří weboví klienti nemusí ve výchozím nastavení do hlavičky zahrnout cookie:

• Pokud používáte nástroj pro testování rozhraní API, možná budete muset povolit cookienastavení.

• Rozhraní JAVAScript fetch API ve výchozím nastavení neobsahuje cookie. Povolte je nastavením credentials na hodnotu include v možnostech.

• Spuštění HttpClient v Blazor WebAssembly aplikaci musí HttpRequestMessage obsahovat přihlašovací údaje, jako je následující příklad:

  request.SetBrowserRequestCredential(BrowserRequestCredentials.Include);
  

Použití ověřování na základě tokenů

Pro klienty, kteří nepodporují cookiepřihlášení, poskytuje rozhraní API pro přihlášení parametr pro vyžádání tokenů. Vystavil se vlastní token (který je proprietární pro platformu identit ASP.NET Core), který se dá použít k ověřování následných požadavků. Token se předá v hlavičce Authorization jako nosný token. K dispozici je také obnovovací token. Tento token umožňuje aplikaci požádat o nový token, když vyprší platnost starého tokenu, aniž by ho vynutíte, aby se znovu přihlásil.

Tokeny nejsou standardní JSna webových tokenech (JWT). Použití vlastních tokenů je záměrné, protože integrované Identity rozhraní API je určené především pro jednoduché scénáře. Možnost tokenu není určená jako plnohodnotný zprostředkovatel služby identity nebo server tokenů, ale alternativou cookie k možnosti pro klienty, kteří nemůžou používat cookie.

Pokud chcete použít ověřování na základě tokenu, nastavte useCookies parametr řetězce dotazu na false při volání koncového /login bodu. Tokeny používají schéma nosné ověřování. Použití tokenu vráceného z volání /login, následná volání chráněných koncových bodů by měla přidat hlavičku Authorization: Bearer <token> , kde <token> je přístupový token. Další informace najdete v části Použití koncového POST /login bodu dále v tomto článku.

Odhlásit se

Pokud chcete uživateli poskytnout způsob, jak se odhlásit, definujte /logout koncový bod jako v následujícím příkladu:

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

Při volání tohoto koncového bodu zadejte prázdný JSobjekt ON ({}) v textu požadavku. Následující kód je příkladem volání koncového bodu odhlášení:

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

Koncové MapIdentityApi<TUser> body

Volání pro MapIdentityApi<TUser> přidání následujících koncových bodů do aplikace:

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

Použití koncového POST /register bodu

Text požadavku musí mít Email a Password vlastnosti:

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

Další informace naleznete v tématu:

• Otestujte registraci dříve v tomto článku.
• RegisterRequest.

Použití koncového POST /login bodu

V textu Email požadavku a Password jsou povinné. Pokud je povolené dvojúrovňové ověřování (2FA), buď TwoFactorCode nebo TwoFactorRecoveryCode je povinné. Pokud 2FA není povolená, vynecháte obojí twoFactorCode i twoFactorRecoveryCode. Další informace najdete v části Použití koncového POST /manage/2fa bodu dále v tomto článku.

Tady je příklad textu požadavku s nepovoleným 2FA:

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

Tady jsou příklady textu požadavku s povoleným 2FA:

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

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

Koncový bod očekává parametr řetězce dotazu:

• useCookies – Nastavte na truecookieověřování na základě. false Nastavte nebo vynecháte ověřování na základě tokenu.

Další informace o cookieověřování na základě informací naleznete v části Testování přihlášení dříve v tomto článku.

Ověřování na základě tokenů

Pokud useCookies je nebo je false vynecháno, je povolené ověřování na základě tokenu. Text odpovědi obsahuje následující vlastnosti:

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

Další informace o těchto vlastnostech naleznete v tématu AccessTokenResponse.

Vložte přístupový token do hlavičky pro provedení ověřených požadavků, jak je znázorněno v následujícím příkladu.

Authorization: Bearer {access token}

Když platnost přístupového tokenu brzy vyprší, zavolejte koncový bod /refresh .

Použití koncového POST /refresh bodu

Pro použití pouze s ověřováním na základě tokenu. Získá nový přístupový token bez vynucení opětovného přihlášení uživatele. Volání tohoto koncového bodu, když platnost přístupového tokenu brzy vyprší.

Text požadavku obsahuje pouze RefreshToken. Tady je příklad textu požadavku:

{
  "refreshToken": "string"
}

Pokud je volání úspěšné, text odpovědi je nový AccessTokenResponse, jak je znázorněno v následujícím příkladu:

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

Použití koncového GET /confirmEmail bodu

Pokud Identity je nastavené potvrzení e-mailu, úspěšné volání koncového /register bodu odešle e-mail, který obsahuje odkaz na /confirmEmail koncový bod. Odkaz obsahuje následující parametry řetězce dotazu:

• userId
• code
• changedEmail – Zahrnuta pouze v případě, že uživatel během registrace změnil e-mailovou adresu.

Identity poskytuje výchozí text pro potvrzovací e-mail. Předmět e-mailu je ve výchozím nastavení "Potvrdit e-mail" a text e-mailu vypadá jako v následujícím příkladu:

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

RequireConfirmedEmail Pokud je vlastnost nastavená na true, uživatel se nemůže přihlásit, dokud se e-mailová adresa nepotvrdí kliknutím na odkaz v e-mailu. Koncový /confirmEmail bod:

• Potvrdí e-mailovou adresu a povolí uživateli přihlášení.
• Vrátí text "Děkujeme vám za potvrzení e-mailu" v textu odpovědi.

Pokud chcete nastavit Identity potvrzení e-mailu, přidejte kódProgram.cs, do kterého chcete true nastavit RequireConfirmedEmail a přidat třídu, která implementuje IEmailSender do kontejneru DI. Příklad:

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

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

Další informace najdete v tématu Potvrzení účtu a obnovení hesla v ASP.NET Core.

Identity poskytuje výchozí text pro ostatní e-maily, které je potřeba odeslat, například pro 2FA a resetování hesla. Pokud chcete tyto e-maily přizpůsobit, zadejte vlastní implementaci IEmailSender rozhraní. V předchozím příkladu je třída, EmailSender která implementuje IEmailSender. Další informace, včetně příkladu třídy, která implementuje IEmailSender, naleznete v tématu Potvrzení účtu a obnovení hesla v ASP.NET Core.

Použití koncového POST /resendConfirmationEmail bodu

Odešle e-mail pouze v případě, že je adresa platná pro registrovaného uživatele.

Text požadavku obsahuje pouze Email. Tady je příklad textu požadavku:

{
  "email": "string"
}

Další informace najdete v tématu Použití koncového GET /confirmEmail bodu výše v tomto článku.

Použití koncového POST /forgotPassword bodu

Vygeneruje e-mail, který obsahuje kód pro resetování hesla. Odešlete tento kód /resetPassword s novým heslem.

Text požadavku obsahuje pouze Email. Tady je příklad:

{
  "email": "string"
}

Informace o tom, jak povolit Identity odesílání e-mailů, najdete v tématu Použití koncového GET /confirmEmail bodu.

Použití koncového POST /resetPassword bodu

Volání tohoto koncového bodu po získání kódu pro resetování voláním koncového /forgotPassword bodu

Text požadavku vyžaduje Email, ResetCodea NewPassword. Tady je příklad:

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

Použití koncového POST /manage/2fa bodu

Konfiguruje dvoufaktorové ověřování (2FA) pro uživatele. Pokud je povolené 2FA, vyžaduje úspěšné přihlášení kromě e-mailové adresy a hesla kód vytvořený ověřovací aplikací.

Povolení 2FA

Povolení 2FA pro aktuálně ověřeného uživatele:

• /manage/2fa Zavolejte koncový bod a v textu požadavku odešlete prázdný JSobjekt ON ({}).

• Tělo odpovědi poskytuje SharedKey spolu s některými dalšími vlastnostmi, které nejsou v tomto okamžiku potřeba. Sdílený klíč slouží k nastavení ověřovací aplikace. Příklad textu odpovědi:

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

• Sdílený klíč použijte k získání jednorázového hesla založeného na čase (TOTP). Další informace najdete v tématu Povolení generování kódu QR pro ověřovací aplikace TOTP v ASP.NET Core.

• /manage/2fa Zavolejte koncový bod, odešlete TOTP a "enable": true v textu požadavku. Příklad:

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

• Tělo odpovědi potvrzuje, že IsTwoFactorEnabled je pravdivé a poskytuje RecoveryCodes. Kódy obnovení se používají k přihlášení, když ověřovací aplikace není dostupná. Příklad textu odpovědi po úspěšném povolení 2FA:

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

Přihlášení pomocí 2FA

/login Zavolejte koncový bod, odešlete e-mailovou adresu, heslo a HESLO v textu požadavku. Příklad:

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

Pokud uživatel nemá přístup k ověřovací aplikaci, přihlaste se voláním /login koncového bodu pomocí jednoho z kódů obnovení, které byly poskytnuty při povolení 2FA. Text požadavku vypadá jako v následujícím příkladu:

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

Resetování kódů obnovení

Pokud chcete získat novou kolekci kódů obnovení, zavolejte tento koncový bod s nastaveným ResetRecoveryCodes na true. Tady je příklad textu požadavku:

{
  "resetRecoveryCodes": true
}

Resetování sdíleného klíče

Pokud chcete získat nový náhodný sdílený klíč, zavolejte tento koncový bod s nastaveným ResetSharedKey na true. Tady je příklad textu požadavku:

{
  "resetSharedKey": true
}

Resetováním klíče se automaticky zakáže požadavek na dvoufaktorové přihlášení ověřeného uživatele, dokud ho později nepovolíte.

Zapomeňte na počítač.

Pokud chcete vymazat cookie příznak "pamatovat si mě", zavolejte tento koncový bod s nastaveným ForgetMachine na true. Tady je příklad textu požadavku:

{
  "forgetMachine": true
}

Tento koncový bod nemá žádný vliv na ověřování založené na tokenech.

Použití koncového GET /manage/info bodu

Získá e-mailovou adresu a stav potvrzení e-mailu přihlášeného uživatele. Deklarace identity z tohoto koncového bodu byly z bezpečnostních důvodů vynechány. Pokud jsou deklarace identity potřeba, pomocí rozhraní API na straně serveru nastavte koncový bod pro deklarace identity. Nebo místo sdílení všech deklarací identity uživatelů zadejte ověřovací koncový bod, který přijímá deklaraci identity a odpovídá na to, jestli ho uživatel má.

Požadavek nevyžaduje žádné parametry. Tělo odpovědi obsahuje Email vlastnosti a IsEmailConfirmed vlastnosti, jak je znázorněno v následujícím příkladu:

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

Použití koncového POST /manage/info bodu

Aktualizace e-mailovou adresu a heslo přihlášeného uživatele. Odeslat NewEmail, NewPassworda OldPassword v textu požadavku, jak je znázorněno v následujícím příkladu:

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

Tady je příklad textu odpovědi:

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

Viz také

Další informace naleznete v následujících zdrojích:

• Volba řešení pro správu identit
• Identity řešení pro správu webových aplikací .NET
• Jednoduchá autorizace v ASP.NET Core
• Přidání, stažení a odstranění uživatelských dat do Identity projektu ASP.NET Core
• Vytvoření aplikace ASP.NET Core s uživatelskými daty chráněnými autorizací
• Potvrzení účtu a obnovení hesla v ASP.NET Core
• Povolení generování kódu QR pro ověřovací aplikace TOTP v ASP.NET Core
• Ukázkový back-end webového rozhraní API pro služby SPA: Soubor .http zobrazuje ověřování založené na tokenech. Příklad:
  • Nenastaví se useCookies
  • Použije autorizační hlavičku k předání tokenu.
  • Zobrazuje aktualizaci pro rozšíření relace bez vynucení opětovného přihlášení uživatele.
• Ukázková aplikace Angular, která používá Identity k zabezpečení back-endu webového rozhraní API