Jak použít Identity k zabezpečení backendu API pro jednostránkové aplikace

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-end webového rozhraní API pomocí ověřování na základě cookie. Možnost založená na tokenech je dostupná pro klienty, kteří nemůžou používat soubory cookie, ale za zajištění zabezpečení tokenů zodpovídáte. Doporučujeme používat soubory cookie pro aplikace založené na prohlížeči, protože ve výchozím nastavení je prohlížeč automaticky zpracovává, aniž by je zpřístupňuje JavaScriptu.

Tento článek ukazuje, jak pomocí Identity zabezpečit backend webového rozhraní API pro jednostránkové aplikace (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é pro použití Identity se zázemím 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řte 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;

Konfigurujte EF Core kontext

Jak už jsme uvedli dříve, nejjednodušší způsob, jak začít, je použít databázi v paměti. Při použití databáze v paměti každé spuštění začíná s čistou databází, 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 zavolání WebApplication.CreateBuilder(args) použijte AddAuthorization pro přidání služeb do kontejneru pro vkládání závislostí (DI):

builder.Services.AddAuthorization();

Aktivace Identity rozhraní API

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

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

Ve výchozím nastavení se aktivují soubory cookie i proprietární tokeny. Soubory cookie a tokeny se vydávají při přihlášení, pokud je parametr řetězce dotazu useCookies v koncovém bodu přihlášení true.

Mapování Identity tras

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

app.MapIdentityApi<IdentityUser>();

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

K zabezpečení koncového bodu použijte metodu rozšíření RequireAuthorization na volání Map{Method}, 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ího nároku 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.
• Rozšiřte zabezpečený koncový bod, například /weatherforecast v projektu vytvořeném pomocí šablony 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 "string" platnou e-mailovou adresou a heslem, poté zvolte 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
  • Nealfanumerický znak

  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 odpověď 200 - OK.

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ší vlastnosti JSON 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í má za následek 200 - OK odpověď s cookie v hlavičce 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 je bezpečně integrované v prohlížeči a funguje bez problémů.

Testování s neprohlížečovými klienty

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

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

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

• Provozování HttpClient v aplikaci Blazor WebAssembly potřebuje, aby HttpRequestMessage obsahoval přihlašovací údaje, jako v následujícím příkladu:

  request.SetBrowserRequestCredential(BrowserRequestCredentials.Include);
  

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

Doporučujeme používat soubory cookie v aplikacích založených na prohlížeči, protože ve výchozím nastavení je prohlížeč automaticky zpracovává, aniž by je zpřístupňuje JavaScriptu.

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í webové tokeny JSON (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 k možnosti cookie pro klienty, kteří nemůžou používat soubory 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 ověřování typu bearer. Při použití tokenu, který je vrácen z volání /login, by následná volání chráněných koncových bodů 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ý objekt JSON ({}) 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í k 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 /resetPassword
• POST /manage/2fa
• GET /manage/info
• POST /manage/info

Použijte POST /register koncový bod

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žijte POST /login koncový bod

V těle požadavku jsou Email a Password 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 true pro ověřování na základě cookie. Nastavte na false nebo vynechejte pro ověřování na základě tokenu.

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

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

Pokud je useCookies nebo 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ž má přístupový token brzy vypršet, zavolejte na koncový bod /refresh.

Použijte POST /refresh koncový bod

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. Zavolejte tento koncový bod, když se platnost přístupového tokenu chýlí ke konci.

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žijte GET /confirmEmail koncový bod

Pokud je Identity nastaveno pro potvrzení e-mailu, úspěšné volání na koncový bod /register odešle e-mail obsahující odkaz na koncový bod /confirmEmail. 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.

Pro nastavení Identity pro potvrzení e-mailu přidejte kód v Program.cs, který nastaví RequireConfirmedEmail na true a přidejte 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žijte POST /resendConfirmationEmail koncový bod

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žijte POST /forgotPassword koncový bod

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žijte POST /resetPassword koncový bod

Zavolejte tento koncový bod poté, co získáte kód pro resetování voláním koncového bodu /forgotPassword.

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

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

Použijte POST /manage/2fa koncový bod

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í.

Aktivujte 2FA

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

• Volání koncového /manage/2fa bodu, odeslání prázdného objektu JSON ({}) v textu požadavku

• 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.

• Zavolejte koncový bod /manage/2fa a 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

Zavolejte koncový bod /login a do textu požadavku odešlete e-mailovou adresu, heslo a TOTP. 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"
}

Obnovit kódy pro 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 a nastavte 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ě", pokud je přítomen, zavolejte tento koncový bod a nastavte 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žijte GET /manage/info koncový bod

Získá e-mailovou adresu a stav potvrzení e-mailu přihlášeného uživatele. Požadavky byly z tohoto bodu vynechány z bezpečnostních důvodů. 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 vlastnosti Email a IsEmailConfirmed, jak je znázorněno v následujícím příkladu:

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

Použijte POST /manage/info koncový bod

Aktualizuje 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:

• zvolit ř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í 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