Så här använder du Identity för att skydda en webb-API-serverdel för SPA:er

ASP.NET Core Identity tillhandahåller API:er som hanterar autentisering, auktorisering och identitetshantering. API:erna gör det möjligt att skydda slutpunkter för en webb-API-serverdel med cookie-baserad autentisering. Ett tokenbaserat alternativ är tillgängligt för klienter som inte kan använda cookies, men när du använder detta ansvarar du för att säkerställa att token hålls säkra. Vi rekommenderar att du använder cookies för webbläsarbaserade program, eftersom webbläsaren som standard hanterar dem automatiskt utan att exponera dem för JavaScript.

Den här artikeln visar hur du använder Identity för att skydda en webb-API-serverdel för SPA:er som Angular, React och Vue-appar. Samma serverdels-API:er kan användas för att skydda Blazor WebAssembly appar.

Förutsättningar

Stegen som visas i den här artikeln lägger till autentisering och auktorisering i en ASP.NET Core Web API-app som:

• Har inte redan konfigurerats för autentisering.
• Mål net8.0 eller senare.
• Kan vara antingen minimalt API eller kontrollantbaserat API.

Några av testinstruktionerna i den här artikeln använder Swagger-användargränssnittet som ingår i projektmallen. Swagger-användargränssnittet krävs inte för att använda Identity med en webb-API-backend.

Installera NuGet-paket

Installera följande NuGet-paket:

• Microsoft.AspNetCore.Identity.EntityFrameworkCore – Gör att Identity kan arbeta med Entity Framework Core (EF Core).
• Ett som gör det möjligt för EF Core att arbeta med en databas, till exempel ett av följande paket:
  • Microsoft.EntityFrameworkCore.SqlServer eller
  • Microsoft.EntityFrameworkCore.Sqlite eller
  • Microsoft.EntityFrameworkCore.InMemory.

Använd den minnesinterna databasen för att komma igång så snabbt som möjligt.

Ändra databasen senare till SQLite eller SQL Server för att spara användardata mellan sessioner vid testning eller för produktionsanvändning. Det ger en viss komplexitet jämfört med minnesintern, eftersom det kräver att databasen skapas via migreringar, som du ser i självstudiekursen EF Core komma igång.

Installera dessa paket med hjälp av NuGet-pakethanteraren i Visual Studio eller kommandot dotnet add package CLI.

Skapa en IdentityDbContext

Lägg till en klass med namnet ApplicationDbContext som ärver från 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)
    { }
}

Koden som visas innehåller en särskild konstruktor som gör det möjligt att konfigurera databasen för olika miljöer.

Lägg till ett eller flera av följande using direktiv efter behov när du lägger till koden som visas i de här stegen.

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

Konfigurera EF Core-kontexten

Som tidigare nämnts är det enklaste sättet att komma igång att använda minnesintern databas. Med minnesinternt börjar varje körning med en ny databas och du behöver inte använda migreringar. När anropet till WebApplication.CreateBuilder(args)lägger du till följande kod för att konfigurera Identity att använda en minnesintern databas:

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

Om du vill spara användardata mellan sessioner vid testning eller för produktionsanvändning ändrar du databasen senare till SQLite eller SQL Server.

Lägga till Identity tjänster i containern

Efter anropet till WebApplication.CreateBuilder(args)anropar du AddAuthorization för att lägga till tjänster i di-containern (dependency injection):

builder.Services.AddAuthorization();

Aktivera Identity API:er

Efter anropet till WebApplication.CreateBuilder(args)anropar du AddIdentityApiEndpoints<TUser>(IServiceCollection) och AddEntityFrameworkStores<TContext>(IdentityBuilder).

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

Som standard aktiveras både cookies och egna token. Cookies och token utfärdas vid inloggning om frågesträngsparametern useCookies i inloggningsslutpunkten är true.

Kartlägg rutterna Identity

Efter anropet till builder.Build()anropar du MapIdentityApi<TUser>(IEndpointRouteBuilder) för att mappa Identity slutpunkter:

app.MapIdentityApi<IdentityUser>();

Skydda valda slutpunkter

Om du vill skydda en slutpunkt använder du RequireAuthorization-tilläggsmetoden på Map{Method}-anropet som definierar vägen. Till exempel:

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

Metoden RequireAuthorization kan också användas för att:

• Skydda Swagger UI-slutpunkter, som du ser i följande exempel:

  app.MapSwagger().RequireAuthorization();
  

• Skydda med ett specifikt anspråk eller behörighet, som du ser i följande exempel:

  .RequireAuthorization("Admin");
  

I ett kontrollantbaserat webb-API-projekt skyddar du slutpunkter genom att tillämpa attributet [Authorize] på en kontrollant eller åtgärd.

Testa API:et

Ett snabbt sätt att testa autentisering är att använda den minnesinterna databasen och Swagger-användargränssnittet som ingår i projektmallen. Följande steg visar hur du testar API:et med Swagger-användargränssnittet. Kontrollera att slutpunkterna för Swagger-användargränssnittet inte är skyddade.

Försök att komma åt en säker slutpunkt

• Kör appen och navigera till Swagger-användargränssnittet.
• Expandera en skyddad slutpunkt, till exempel /weatherforecast i ett projekt som skapats av webb-API-mallen.
• Välj Prova.
• Välj Kör. Svaret är 401 - not authorized.

Testregistrering

• Expandera /register och välj Prova.

• I avsnittet Parametrar i användargränssnittet visas ett exempel på begärandetext:

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

• Ersätt "sträng" med en giltig e-postadress och ett giltigt lösenord och välj sedan Utför.

  För att uppfylla standardreglerna för lösenordsverifiering måste lösenordet vara minst sex tecken långt och innehålla minst ett av följande tecken:

  • Versal bokstav
  • Gemener bokstav
  • Siffra
  • Icke-numeriskt tecken

  Om du anger en ogiltig e-postadress eller ett felaktigt lösenord innehåller resultatet valideringsfelen. Här är ett exempel på en svarstext med valideringsfel:

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

  Felen returneras i ProblemDetails format så att klienten kan parsa dem och visa valideringsfel efter behov.

  En lyckad registrering resulterar i ett 200 - OK-svar.

Testinlogg

• Expandera /login och välj Prova. Exempeltexten för begäran visar två ytterligare parametrar:

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

  De extra JSON-egenskaperna behövs inte för det här exemplet och kan tas bort. Ange useCookies till true.

• Ersätt "text" med den e-postadress och det lösenord som du använde när du registrerade dig, och välj sedan Kör.

  En lyckad inloggning resulterar i ett 200 - OK svar med en cookie i svarshuvudet.

Testa den skyddade slutpunkten igen

Efter en lyckad inloggning kör du den skyddade slutpunkten igen. Autentiseringen cookie skickas automatiskt med begäran och slutpunkten är auktoriserad. Cookie-baserad autentisering är säkert inbyggd i webbläsaren och "fungerar bara".

Testa med nonbrowser-klienter

Vissa webbklienter kanske inte innehåller cookies i rubriken som standard:

• Om du använder ett verktyg för att testa API:er kan du behöva aktivera cookies i inställningarna.

• JavaScript-fetch API innehåller inte cookies som standard. Aktivera dem genom att ange credentials till värdet include i alternativen.

• En HttpClient som körs i en Blazor WebAssembly app behöver HttpRequestMessage för att inkludera autentiseringsuppgifter, som i följande exempel:

  request.SetBrowserRequestCredential(BrowserRequestCredentials.Include);
  

Använda tokenbaserad autentisering

Vi rekommenderar att du använder cookies i webbläsarbaserade program eftersom webbläsaren som standard hanterar dem automatiskt utan att exponera dem för JavaScript.

En anpassad token (en som är skyddad för ASP.NET Core-identitetsplattformen) utfärdas som kan användas för att autentisera efterföljande begäranden. Token skickas i Authorization-huvudet som en bärartoken. En uppdateringstoken tillhandahålls också. Med den här token kan programmet begära en ny token när den gamla upphör att gälla utan att tvinga användaren att logga in igen.

Tokenen är inte standard-JSON-webbtokens (JWT). Användningen av anpassade token är avsiktlig eftersom det inbyggda Identity-API:et främst är avsett för enkla scenarier. Tokenalternativet är inte avsett att vara en komplett identitetstjänstleverantör eller tokenserver, utan i stället ett alternativ till alternativet cookie för klienter som inte kan använda cookies.

Om du vill använda tokenbaserad autentisering anger du useCookies frågesträngsparametern till false när du anropar /login slutpunkten. Tokens använder autentiseringsschemat för bärare . Med hjälp av token som returneras från anropet till /loginbör efterföljande anrop till skyddade slutpunkter lägga till headern Authorization: Bearer <token> där <token> är åtkomsttoken. Mer information finns i Använd POST /login slutpunkten senare i den här artikeln.

Logga ut

Definiera en /logout slutpunkt som i följande exempel för att ge användaren ett sätt att logga ut:

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

Ange ett tomt JSON-objekt ({}) i begärandetexten när du anropar den här slutpunkten. Följande kod är ett exempel på ett anrop till utloggningsslutpunkten:

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

Slutpunkterna för MapIdentityApi<TUser>

Anropet till MapIdentityApi<TUser> lägger till följande slutpunkter i appen:

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

Använd POST /register slutpunkten

Begärandetexten måste ha egenskaper för Email och Password:

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

Mer information finns i:

• Testregistrering som omtals tidigare i den här artikeln.
• RegisterRequest.

Använd POST /login-slutpunkten

I begärandetexten krävs Email och Password. Om tvåfaktorautentisering (2FA) är aktiverat krävs antingen TwoFactorCode eller TwoFactorRecoveryCode. Om 2FA inte är aktiverat utelämnar du både twoFactorCode och twoFactorRecoveryCode. Mer information finns i Använd POST /manage/2fa slutpunkten senare i den här artikeln.

Här är ett exempel på begärandetext med 2FA inte aktiverat:

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

Här är exempel på begärandetext med 2FA aktiverat:

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

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

Slutpunkten förväntar sig en frågesträngsparameter:

• useCookies – Ange till true för cookie-baserad autentisering. Ange till false eller utelämna för tokenbaserad autentisering.

Mer information om cookie-baserad autentisering finns i Testa inloggning tidigare i den här artikeln.

Tokenbaserad autentisering

Om useCookies är false eller utelämnas aktiveras tokenbaserad autentisering. Svarstexten innehåller följande egenskaper:

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

Mer information om dessa egenskaper finns i AccessTokenResponse.

Placera åtkomsttoken i en rubrik för att göra autentiserade begäranden, enligt följande exempel

Authorization: Bearer {access token}

När åtkomsttoken snart upphör att gälla anropar du slutpunkten /refresh.

Använd POST /refresh slutpunkten

Endast för användning med tokenbaserad autentisering. Hämtar en ny åtkomsttoken utan att tvinga användaren att logga in igen. Anropa den här slutpunkten när åtkomsttoken håller på att gå ut.

Begärandetexten innehåller endast RefreshToken. Här är ett exempel på begärandetext:

{
  "refreshToken": "string"
}

Om anropet lyckas är svarstexten en ny AccessTokenResponse, som du ser i följande exempel:

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

Använd GET /confirmEmail slutpunkten

Om Identity har konfigurerats för e-postbekräftelse skickar ett lyckat samtal till /register-slutpunkten ett e-postmeddelande som innehåller en länk till /confirmEmail slutpunkten. Länken innehåller följande frågesträngsparametrar:

• userId
• code
• changedEmail – Ingår endast om användaren ändrade e-postadressen under registreringen.

Identity innehåller standardtext för bekräftelsemeddelandet. Som standard är e-postämnet "Bekräfta din e-post" och e-posttexten ser ut som i följande exempel:

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

Om egenskapen RequireConfirmedEmail är inställd på truekan användaren inte logga in förrän e-postadressen har bekräftats genom att klicka på länken i e-postmeddelandet. Slutpunkten /confirmEmail:

• Bekräftar e-postadressen och gör det möjligt för användaren att logga in.
• Returnerar texten "Tack för att du bekräftar din e-post." i svarstexten.

Om du vill konfigurera Identity för e-postbekräftelse lägger du till kod i Program.cs för att ange RequireConfirmedEmail till true och lägga till en klass som implementerar IEmailSender i DI-containern. Till exempel:

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

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

Mer information finns i Kontobekräftelse och lösenordsåterställning i ASP.NET Core.

Identity innehåller standardtext för andra e-postmeddelanden som också måste skickas, till exempel för 2FA och lösenordsåterställning. Om du vill anpassa dessa e-postmeddelanden tillhandahåller du en anpassad implementering av IEmailSender-gränssnittet. I föregående exempel är EmailSender en klass som implementerar IEmailSender. Mer information, inklusive ett exempel på en klass som implementerar IEmailSender, finns i Kontobekräftelse och lösenordsåterställning i ASP.NET Core.

Använd POST /resendConfirmationEmail slutpunkten

Skickar endast ett e-postmeddelande om adressen är giltig för en registrerad användare.

Begärandetexten innehåller endast Email. Här är ett exempel på begärandetext:

{
  "email": "string"
}

Mer information finns i Använd GET /confirmEmail slutpunkten tidigare i den här artikeln.

Använd POST /forgotPassword slutpunkten

Genererar ett e-postmeddelande som innehåller en lösenordsåterställningskod. Skicka koden till /resetPassword med ett nytt lösenord.

Begärandetexten innehåller endast Email. Här är ett exempel:

{
  "email": "string"
}

Information om hur du aktiverar Identity för att skicka e-postmeddelanden finns i Använd GET /confirmEmail-slutpunkten.

Använd POST /resetPassword slutpunkten

Anropa den här slutpunkten när du har fått en återställningskod genom att anropa slutpunkten /forgotPassword.

Begärandetexten kräver Email, ResetCodeoch NewPassword. Här är ett exempel:

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

Använd POST /manage/2fa slutpunkten

Konfigurerar tvåfaktorautentisering (2FA) för användaren. När 2FA är aktiverat kräver lyckad inloggning en kod som skapats av en autentiseringsapp utöver e-postadressen och lösenordet.

Aktivera 2FA

Så här aktiverar du 2FA för den autentiserade användaren:

• Anropa /manage/2fa slutpunkten och skicka ett tomt JSON-objekt ({}) i begärandetexten.

• Svarstexten innehåller SharedKey tillsammans med några andra egenskaper som inte behövs just nu. Den delade nyckeln används för att konfigurera autentiseringsappen. Exempel på svarstext:

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

• Använd den delade nyckeln för att hämta ett tidsbaserat engångslösenord (TOTP). Mer information finns i Aktivera QR-kodgenerering för TOTP-autentiseringsappar i ASP.NET Core.

• Anropa endpoint /manage/2fa och skicka TOTP och "enable": true i begäran. Till exempel:

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

• Svarstexten bekräftar att IsTwoFactorEnabled är sant och ger RecoveryCodes. Återställningskoderna används för att logga in när autentiseringsappen inte är tillgänglig. Exempel på svarstext efter aktivering av 2FA:

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

Logga in med 2FA

Anropa /login slutpunkten och skicka e-postadressen, lösenordet och TOTP i begärandetexten. Till exempel:

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

Om användaren inte har åtkomst till autentiseringsappen loggar du in genom att anropa /login slutpunkten med en av återställningskoderna som angavs när 2FA aktiverades. Begärandetexten ser ut som i följande exempel:

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

Återställa återställningskoderna

Om du vill hämta en ny samling återställningskoder anropar du den här slutpunkten med ResetRecoveryCodes inställd på true. Här är ett exempel på begärandetext:

{
  "resetRecoveryCodes": true
}

Återställa den delade nyckeln

Om du vill hämta en ny slumpmässig delad nyckel anropar du den här slutpunkten med ResetSharedKey inställd på true. Här är ett exempel på begärandetext:

{
  "resetSharedKey": true
}

Om du återställer nyckeln inaktiveras automatiskt kravet på tvåfaktorinloggning för den autentiserade användaren tills den återaktiveras av en senare begäran.

Glöm maskinen

Om du vill rensa cookie "kom ihåg mig-flaggan" om den är närvarande anropar du den här slutpunkten med ForgetMachine inställd till true. Här är ett exempel på begärandetext:

{
  "forgetMachine": true
}

Den här slutpunkten påverkar inte tokenbaserad autentisering.

Använd slutpunkten GET /manage/info

Hämtar e-postadress och e-postbekräftelsestatus för den inloggade användaren. Anspråk utelämnades från den här slutpunkten av säkerhetsskäl. Om anspråk behövs använder du API:erna på serversidan för att konfigurera en slutpunkt för anspråk. Eller i stället för att dela alla användares anspråk anger du en valideringsslutpunkt som accepterar ett anspråk och svarar på om användaren har det.

Begäran kräver inga parametrar. Svarstexten innehåller egenskaperna Email och IsEmailConfirmed, som i följande exempel:

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

Använd POST /manage/info slutpunkten

Uppdaterar e-postadressen och lösenordet för den inloggade användaren. Skicka NewEmail, NewPasswordoch OldPassword i begärandetexten, som du ser i följande exempel:

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

Här är ett exempel på svarstexten:

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

Se även

Mer information finns i följande resurser:

• Välj en lösning för identitetshantering
• Identity hanteringslösningar för .NET-webbappar
• Enkel auktorisering i ASP.NET Core
• Lägg till, ladda ned och ta bort användardata till Identity i ett ASP.NET Core-projekt
• Skapa en ASP.NET Core-app med användardata som skyddas av auktorisering
• Kontobekräftelse och lösenordsåterställning i ASP.NET Core
• Aktivera QR-kodgenerering för TOTP-autentiseringsappar i ASP.NET Core
• Exempelwebb-API-serverdelen för SPA:er .http-filen visar tokenbaserad autentisering. Till exempel:
  • Anger inte useCookies
  • Använder Authorization-headern för att skicka en token
  • Visar uppdatering för att utöka sessionen utan att tvinga användaren att logga in igen
• Angular-exempelapp som använder Identity för att skydda en webb-API-serverdel