Cara menggunakan Identity untuk mengamankan backend API Web untuk SPAs

ASP.NET Core Identity menyediakan API yang menangani autentikasi, otorisasi, dan manajemen identitas. API memungkinkan untuk mengamankan titik akhir backend API Web dengan cookieautentikasi berbasis. Ada opsi berbasis token untuk klien yang tidak dapat menggunakannya cookie.

Artikel ini menunjukkan cara menggunakan Identity untuk mengamankan backend API Web untuk SPAs seperti aplikasi Angular, React, dan Vue. API backend yang sama dapat digunakan untuk mengamankan Blazor WebAssembly aplikasi.

Prasyarat

Langkah-langkah yang ditunjukkan dalam artikel ini menambahkan autentikasi dan otorisasi ke aplikasi ASP.NET Core Web API yang:

• Belum dikonfigurasi untuk autentikasi.
• Target atau yang lebih net8.0 baru.
• Dapat berupa API minimal atau API berbasis pengontrol.

Beberapa instruksi pengujian dalam artikel ini menggunakan antarmuka pengguna Swagger yang disertakan dengan templat proyek. Antarmuka pengguna Swagger tidak diperlukan untuk digunakan Identity dengan backend API Web.

Instal paket NuGet

Instal paket NuGet berikut:

• Microsoft.AspNetCore.Identity.EntityFrameworkCore - Memungkinkan Identity untuk bekerja dengan Entity Framework Core (EF Core).
• Salah satu yang memungkinkan EF Core untuk bekerja dengan database, seperti salah satu paket berikut:
  • Microsoft.EntityFrameworkCore.SqlServer atau
  • Microsoft.EntityFrameworkCore.Sqlite atau
  • Microsoft.EntityFrameworkCore.InMemory.

Untuk cara tercepat untuk memulai, gunakan database dalam memori.

Ubah database nanti ke SQLite atau SQL Server untuk menyimpan data pengguna antar sesi saat menguji atau untuk penggunaan produksi. Itu memperkenalkan beberapa kompleksitas dibandingkan dengan dalam memori, karena mengharuskan database dibuat melalui migrasi, seperti yang EF Core ditunjukkan dalam tutorial memulai.

Instal paket ini dengan menggunakan manajer paket NuGet di Visual Studio atau perintah CLI tambahkan paket dotnet.

Buat IdentityDbContext

Tambahkan kelas bernama ApplicationDbContext yang mewarisi dari 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)
    { }
}

Kode yang ditampilkan menyediakan konstruktor khusus yang memungkinkan untuk mengonfigurasi database untuk lingkungan yang berbeda.

Tambahkan satu atau beberapa arahan berikut sesuai using kebutuhan saat menambahkan kode yang diperlihatkan dalam langkah-langkah ini.

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

EF Core Mengonfigurasi konteks

Seperti disebutkan sebelumnya, cara paling sederhana untuk memulai adalah dengan menggunakan database dalam memori. Dengan setiap eksekusi dalam memori dimulai dengan database baru, dan tidak perlu menggunakan migrasi. Setelah panggilan ke WebApplication.CreateBuilder(args), tambahkan kode berikut untuk dikonfigurasi Identity untuk menggunakan database dalam memori:

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

Untuk menyimpan data pengguna antar sesi saat menguji atau untuk penggunaan produksi, ubah database nanti ke SQLite atau SQL Server.

Menambahkan Identity layanan ke kontainer

Setelah panggilan ke WebApplication.CreateBuilder(args), panggil AddAuthorization untuk menambahkan layanan ke kontainer injeksi dependensi (DI):

builder.Services.AddAuthorization();

Mengaktifkan Identity API

Setelah panggilan ke WebApplication.CreateBuilder(args), panggil AddIdentityApiEndpoints<TUser>(IServiceCollection) dan AddEntityFrameworkStores<TContext>(IdentityBuilder).

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

Secara default, token cookies dan kepemilikan diaktifkan. Cookies dan token dikeluarkan saat masuk jika useCookies parameter string kueri di titik akhir login adalah true.

Rute peta Identity

Setelah panggilan ke builder.Build(), panggil MapIdentityApi<TUser>(IEndpointRouteBuilder) untuk memetakan Identity titik akhir:

app.MapIdentityApi<IdentityUser>();

Mengamankan titik akhir yang dipilih

Untuk mengamankan titik akhir, gunakan RequireAuthorization metode ekstensi pada Map{Method} panggilan yang menentukan rute. Contohnya:

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

Metode ini RequireAuthorization juga dapat digunakan untuk:

• Titik akhir UI Swagger Aman, seperti yang ditunjukkan dalam contoh berikut:

  app.MapSwagger().RequireAuthorization();
  

• Amankan dengan klaim atau izin tertentu, seperti yang ditunjukkan dalam contoh berikut:

  .RequireAuthorization("Admin");
  

Dalam proyek API web berbasis pengontrol, titik akhir aman dengan menerapkan atribut [Authorize] ke pengontrol atau tindakan.

Menguji API

Cara cepat untuk menguji autentikasi adalah dengan menggunakan database dalam memori dan antarmuka pengguna Swagger yang disertakan dengan templat proyek. Langkah-langkah berikut menunjukkan cara menguji API dengan antarmuka pengguna Swagger. Pastikan bahwa titik akhir antarmuka pengguna Swagger tidak diamankan.

Mencoba mengakses titik akhir aman

• Jalankan aplikasi dan navigasikan ke antarmuka pengguna Swagger.
• Perluas titik akhir aman, seperti /weatherforecast dalam proyek yang dibuat oleh templat API web.
• Pilih Coba.
• Pilih Jalankan. Responsnya adalah 401 - not authorized.

Uji pendaftaran

• Perluas /register dan pilih Cobalah.

• Di bagian Parameter UI, isi permintaan sampel ditampilkan:

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

• Ganti "string" dengan alamat email dan kata sandi yang valid, lalu pilih Jalankan.

  Untuk mematuhi aturan validasi kata sandi default, panjang kata sandi harus setidaknya enam karakter dan berisi setidaknya satu dari masing-masing karakter berikut:

  • Huruf besar
  • Huruf kecil
  • Digit numerik
  • Karakter non-nufanumerik

  Jika Anda memasukkan alamat email yang tidak valid atau kata sandi yang buruk, hasilnya menyertakan kesalahan validasi. Berikut adalah contoh isi respons dengan kesalahan validasi:

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

  Kesalahan dikembalikan dalam format ProblemDetails sehingga klien dapat mengurainya dan menampilkan kesalahan validasi sesuai kebutuhan.

  Pendaftaran yang berhasil menghasilkan 200 - OK respons.

Uji login

• Perluas /login dan pilih Cobalah. Contoh isi permintaan menunjukkan dua parameter tambahan:

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

  Properti ON tambahan JStidak diperlukan untuk contoh ini dan dapat dihapus. Atur useCookies ke true.

• Ganti "string" dengan alamat email dan kata sandi yang Anda gunakan untuk mendaftar, lalu pilih Jalankan.

  Login yang berhasil menghasilkan 200 - OK respons dengan cookie di header respons.

Coba lagi titik akhir aman

Setelah berhasil masuk, jalankan ulang titik akhir aman. Autentikasi cookie dikirim secara otomatis dengan permintaan, dan titik akhir diotorisasi. CookieAutentikasi berbasis aman bawaan ke browser dan "hanya berfungsi."

Pengujian dengan klien nonbrowser

Beberapa klien web mungkin tidak menyertakan cookies di header secara default:

• Jika Anda menggunakan alat untuk menguji API, Anda mungkin perlu mengaktifkannya cookiedi pengaturan.

• API JavaScript fetch tidak menyertakan cookiesecara default. Aktifkan dengan mengatur credentials ke nilai include dalam opsi.

• Yang HttpClient berjalan di Blazor WebAssembly aplikasi memerlukan HttpRequestMessage untuk menyertakan kredensial, seperti contoh berikut:

  request.SetBrowserRequestCredential(BrowserRequestCredentials.Include);
  

Menggunakan autentikasi berbasis token

Untuk klien yang tidak mendukung cookie, API login menyediakan parameter untuk meminta token. Token kustom (yang merupakan milik platform identitas ASP.NET Core) dikeluarkan yang dapat digunakan untuk mengautentikasi permintaan berikutnya. Token diteruskan di Authorization header sebagai token pembawa. Token refresh juga disediakan. Token ini memungkinkan aplikasi untuk meminta token baru ketika yang lama kedaluwarsa tanpa memaksa pengguna untuk masuk lagi.

Token bukan on Web Token standar JS(JWT). Penggunaan token kustom disengaja, karena API bawaan Identity dimaksudkan terutama untuk skenario sederhana. Opsi token tidak dimaksudkan untuk menjadi penyedia layanan identitas berfitur lengkap atau server token, tetapi sebagai alternatif untuk cookie opsi untuk klien yang tidak dapat menggunakannya cookie.

Untuk menggunakan autentikasi berbasis token, atur useCookies parameter string kueri ke false saat memanggil /login titik akhir. Token menggunakan skema autentikasi pembawa . Menggunakan token yang dikembalikan dari panggilan ke /login, panggilan berikutnya ke titik akhir yang dilindungi harus menambahkan header Authorization: Bearer <token> di mana <token> adalah token akses. Untuk informasi selengkapnya, lihat Menggunakan POST /login titik akhir nanti di artikel ini.

Keluar

Untuk menyediakan cara bagi pengguna untuk keluar, tentukan /logout titik akhir seperti contoh berikut:

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

Berikan objek ON kosong JS({}) di isi permintaan saat memanggil titik akhir ini. Kode berikut adalah contoh panggilan ke titik akhir keluar:

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

Titik MapIdentityApi<TUser> akhir

Panggilan untuk MapIdentityApi<TUser> menambahkan titik akhir berikut ke aplikasi:

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

POST /register Menggunakan titik akhir

Isi permintaan harus memiliki Email properti dan Password :

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

Untuk informasi selengkapnya, lihat:

• Uji pendaftaran sebelumnya dalam artikel ini.
• RegisterRequest.

POST /login Menggunakan titik akhir

Dalam isi permintaan, Email dan Password diperlukan. Jika autentikasi dua faktor (2FA) diaktifkan, baik TwoFactorCode atau TwoFactorRecoveryCode diperlukan. Jika 2FA tidak diaktifkan, hilangkan keduanya twoFactorCode dan twoFactorRecoveryCode. Untuk informasi selengkapnya, lihat Menggunakan POST /manage/2fa titik akhir nanti di artikel ini.

Berikut adalah contoh isi permintaan dengan 2FA tidak diaktifkan:

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

Berikut adalah contoh isi permintaan dengan 2FA diaktifkan:

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

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

Titik akhir mengharapkan parameter string kueri:

• useCookies - Atur ke true untuk cookieautentikasi berbasis. Atur ke false atau hilangkan untuk autentikasi berbasis token.

Untuk informasi selengkapnya tentang cookieautentikasi berbasis, lihat Menguji login sebelumnya di artikel ini.

Autentikasi berbasis token

Jika useCookies atau dihilangkan false , autentikasi berbasis token diaktifkan. Isi respons mencakup properti berikut:

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

Untuk informasi selengkapnya tentang properti ini, lihat AccessTokenResponse.

Letakkan token akses di header untuk membuat permintaan terautentikasi, seperti yang ditunjukkan dalam contoh berikut

Authorization: Bearer {access token}

Saat token akses akan kedaluwarsa, panggil titik akhir /refresh .

POST /refresh Menggunakan titik akhir

Untuk digunakan hanya dengan autentikasi berbasis token. Mendapatkan token akses baru tanpa memaksa pengguna untuk masuk lagi. Panggil titik akhir ini saat token akses akan kedaluwarsa.

Isi permintaan hanya RefreshTokenberisi . Berikut adalah contoh isi permintaan:

{
  "refreshToken": "string"
}

Jika panggilan berhasil, isi respons adalah baru AccessTokenResponse, seperti yang ditunjukkan dalam contoh berikut:

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

GET /confirmEmail Menggunakan titik akhir

Jika Identity disiapkan untuk konfirmasi email, panggilan yang berhasil ke /register titik akhir akan mengirim email yang berisi tautan ke /confirmEmail titik akhir. Tautan berisi parameter string kueri berikut:

• userId
• code
• changedEmail - Disertakan hanya jika pengguna mengubah alamat email selama pendaftaran.

Identity menyediakan teks default untuk email konfirmasi. Secara default, subjek email adalah "Konfirmasi email Anda" dan isi email terlihat seperti contoh berikut:

 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 Jika properti diatur ke true, pengguna tidak dapat masuk hingga alamat email dikonfirmasi dengan mengklik tautan dalam email. Titik /confirmEmail akhir:

• Mengonfirmasi alamat email dan memungkinkan pengguna untuk masuk.
• Mengembalikan teks "Terima kasih telah mengonfirmasi email Anda." di isi respons.

Untuk menyiapkan Identity konfirmasi email, tambahkan kode untuk Program.cs diatur RequireConfirmedEmail ke true dan tambahkan kelas yang diterapkan IEmailSender ke kontainer DI. Contohnya:

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

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

Untuk informasi selengkapnya, lihat Konfirmasi akun dan pemulihan kata sandi di ASP.NET Core.

Identity menyediakan teks default untuk email lain yang perlu dikirim juga, seperti untuk 2FA dan pengaturan ulang kata sandi. Untuk menyesuaikan email ini, berikan implementasi IEmailSender kustom antarmuka. Dalam contoh sebelumnya, EmailSender adalah kelas yang mengimplementasikan IEmailSender. Untuk informasi selengkapnya, termasuk contoh kelas yang menerapkan IEmailSender, lihat Konfirmasi akun dan pemulihan kata sandi di ASP.NET Core.

POST /resendConfirmationEmail Menggunakan titik akhir

Mengirim email hanya jika alamat tersebut valid untuk pengguna terdaftar.

Isi permintaan hanya Emailberisi . Berikut adalah contoh isi permintaan:

{
  "email": "string"
}

Untuk informasi selengkapnya, lihat Menggunakan GET /confirmEmail titik akhir sebelumnya di artikel ini.

POST /forgotPassword Menggunakan titik akhir

Menghasilkan email yang berisi kode reset kata sandi. Kirim kode tersebut ke /resetPassword dengan kata sandi baru.

Isi permintaan hanya Emailberisi . Berikut contohnya:

{
  "email": "string"
}

Untuk informasi tentang cara mengaktifkan Identity untuk mengirim email, lihat Menggunakan GET /confirmEmail titik akhir.

POST /resetPassword Menggunakan titik akhir

Panggil titik akhir ini setelah mendapatkan kode reset dengan memanggil /forgotPassword titik akhir.

Isi permintaan memerlukan Email, , ResetCodedan NewPassword. Berikut contohnya:

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

POST /manage/2fa Menggunakan titik akhir

Mengonfigurasi autentikasi dua faktor (2FA) untuk pengguna. Ketika 2FA diaktifkan, login yang berhasil memerlukan kode yang dihasilkan oleh aplikasi pengautentikasi selain alamat email dan kata sandi.

Aktifkan 2FA

Untuk mengaktifkan 2FA untuk pengguna yang saat ini diautentikasi:

• /manage/2fa Panggil titik akhir, kirim objek ON kosong JS({}) di isi permintaan.

• Isi respons menyediakan SharedKey bersama dengan beberapa properti lain yang tidak diperlukan pada saat ini. Kunci bersama digunakan untuk menyiapkan aplikasi pengautentikasi. Contoh badan respons:

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

• Gunakan kunci bersama untuk mendapatkan kata sandi satu kali berbasis waktu (TOTP). Untuk informasi selengkapnya, lihat Mengaktifkan pembuatan kode QR untuk aplikasi pengautentikasi TOTP di ASP.NET Core.

• /manage/2fa Panggil titik akhir, kirim TOTP dan "enable": true di isi permintaan. Contohnya:

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

• Isi respons mengonfirmasi bahwa IsTwoFactorEnabled itu benar dan menyediakan RecoveryCodes. Kode pemulihan digunakan untuk masuk saat aplikasi pengautentikasi tidak tersedia. Contoh isi respons setelah berhasil mengaktifkan 2FA:

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

Masuk dengan 2FA

/login Panggil titik akhir, kirim alamat email, kata sandi, dan TOTP di isi permintaan. Contohnya:

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

Jika pengguna tidak memiliki akses ke aplikasi pengautentikasi, masuk dengan memanggil /login titik akhir dengan salah satu kode pemulihan yang disediakan saat 2FA diaktifkan. Isi permintaan terlihat seperti contoh berikut:

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

Mengatur ulang kode pemulihan

Untuk mendapatkan kumpulan kode pemulihan baru, panggil titik akhir ini dengan ResetRecoveryCodes diatur ke true. Berikut adalah contoh isi permintaan:

{
  "resetRecoveryCodes": true
}

Mereset kunci bersama

Untuk mendapatkan kunci bersama acak baru, panggil titik akhir ini dengan ResetSharedKey diatur ke true. Berikut adalah contoh isi permintaan:

{
  "resetSharedKey": true
}

Mengatur ulang kunci secara otomatis menonaktifkan persyaratan masuk dua faktor untuk pengguna yang diautentikasi hingga diaktifkan kembali oleh permintaan selanjutnya.

Lupakan mesin

Untuk menghapus cookie "ingat bendera saya" jika ada, panggil titik akhir ini dengan ForgetMachine diatur ke true. Berikut adalah contoh isi permintaan:

{
  "forgetMachine": true
}

Titik akhir ini tidak berdampak pada autentikasi berbasis token.

GET /manage/info Menggunakan titik akhir

Mendapatkan alamat email dan status konfirmasi email pengguna yang masuk. Klaim dihilangkan dari titik akhir ini karena alasan keamanan. Jika klaim diperlukan, gunakan API sisi server untuk menyiapkan titik akhir untuk klaim. Atau alih-alih membagikan semua klaim pengguna, berikan titik akhir validasi yang menerima klaim dan merespons apakah pengguna memilikinya.

Permintaan tidak memerlukan parameter apa pun. Isi respons mencakup Email properti dan IsEmailConfirmed , seperti dalam contoh berikut:

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

POST /manage/info Menggunakan titik akhir

Memperbarui alamat email dan kata sandi pengguna yang masuk. Kirim NewEmail, NewPassword, dan OldPassword dalam isi permintaan, seperti yang ditunjukkan dalam contoh berikut:

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

Berikut contoh isi responsnya:

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

Lihat juga

Untuk informasi selengkapnya, lihat sumber daya berikut:

• Memilih solusi manajemen identitas
• Identity solusi manajemen untuk aplikasi web .NET
• Otorisasi sederhana di ASP.NET Core
• Menambahkan, mengunduh, dan menghapus data pengguna ke Identity dalam proyek ASP.NET Core
• Membuat aplikasi ASP.NET Core dengan data pengguna yang dilindungi oleh otorisasi
• Konfirmasi akun dan pemulihan kata sandi di ASP.NET Core
• Mengaktifkan pembuatan Kode QR untuk aplikasi pengautentikasi TOTP di ASP.NET Core
• Contoh backend API Web untuk SPAs File .http menunjukkan autentikasi berbasis token. Misalnya:
  • Tidak diatur useCookies
  • Menggunakan header Otorisasi untuk meneruskan token
  • Menampilkan refresh untuk memperpanjang sesi tanpa memaksa pengguna untuk masuk lagi
• Sampel aplikasi Angular yang menggunakan Identity untuk mengamankan backend API Web