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 pengamanan titik akhir dari backend API Web dengan autentikasi berbasis cookie. Opsi berbasis token tersedia untuk klien yang tidak dapat menggunakan cookie, tetapi dalam menggunakan ini Anda bertanggung jawab untuk memastikan token tetap aman. Sebaiknya gunakan cookie untuk aplikasi berbasis browser, karena, secara default, browser secara otomatis menanganinya tanpa mengeksposnya ke JavaScript.

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 net8.0 atau yang lebih.
• 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 menggunakan Identity dengan backend API Web.

Menginstal 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. Ini memperkenalkan beberapa kompleksitas dibandingkan dengan penyimpanan dalam memori, sebab mengharuskan database dibuat melalui migrasi, seperti yang diperlihatkan dalam EF Core 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 lebih arahan berikut ini using sesuai kebutuhan saat menambahkan kode yang diperlihatkan dalam langkah-langkah ini.

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

Konfigurasi konteks EF Core

Seperti disebutkan sebelumnya, cara paling sederhana untuk memulai adalah dengan menggunakan database dalam memori. Dalam mode in-memory, setiap kali dijalankan menggunakan 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, cookie dan token kepemilikan diaktifkan. Cookies dan token diberikan saat login jika parameter string kueri useCookies di titik akhir login adalah true.

Peta rute Identity

Setelah memanggil builder.Build(), panggil MapIdentityApi<TUser>(IEndpointRouteBuilder) untuk memetakan endpoint Identity:

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:

• Amankan titik akhir UI Swagger, 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.

Pendaftaran ujian

• 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
  • Angka
  • Karakter non-alfanumerik

  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 masuk

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

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

  Properti JSON tambahan tidak 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 cookie di header secara default:

• Jika Anda menggunakan alat untuk menguji API, Anda mungkin perlu mengaktifkan cookie di pengaturan.

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

• HttpClient yang berjalan dalam aplikasi Blazor WebAssembly perlu agar HttpRequestMessage menyertakan kredensial, seperti contoh berikut:

  request.SetBrowserRequestCredential(BrowserRequestCredentials.Include);
  

Menggunakan autentikasi berbasis token

Sebaiknya gunakan cookie di aplikasi berbasis browser, karena, secara default, browser secara otomatis menanganinya tanpa mengeksposnya ke JavaScript.

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 JSON Web Token standar (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 opsi cookie untuk klien yang tidak dapat menggunakan 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 gunakan POST /login endpoint di artikel ini nanti.

Keluar Akun

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 JSON kosong ({}) 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 akhir MapIdentityApi<TUser>

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

Gunakan titik akhir POST /register

Isi permintaan harus memiliki properti Email dan Password

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

Untuk informasi selengkapnya, lihat:

• Pendaftaran uji sebelumnya dalam artikel ini.
• RegisterRequest.

Gunakan titik akhir POST /login

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 gunakan POST /manage/2fa endpoint di artikel ini nanti.

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 menggunakan parameter string kueri:

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

Untuk informasi selengkapnya tentang autentikasi berbasis cookie, lihat pengujian login sebelumnya dalam artikel ini.

Autentikasi berbasis token

Jika useCookies adalah false atau dihilangkan, 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 hampir kedaluwarsa, panggil endpoint /refresh.

Gunakan titik akhir POST /refresh

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 berisi RefreshToken. 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"
}

Gunakan titik akhir GET /confirmEmail

Jika Identity disiapkan untuk konfirmasi email, panggilan yang berhasil ke /register titik akhir akan mengirim email yang berisi tautan ke /confirmEmail titik akhir. Tautan ini 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 untuk konfirmasi email, tambahkan kode di Program.cs untuk menyetel RequireConfirmedEmail ke true dan tambahkan kelas yang mengimplementasikan IEmailSender ke dalam 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 antarmuka IEmailSender kustom. 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.

Gunakan titik akhir POST /resendConfirmationEmail

Mengirim email hanya jika alamat tersebut valid untuk pengguna terdaftar.

Isi permintaan hanya berisi Email. Berikut adalah contoh isi permintaan:

{
  "email": "string"
}

Untuk informasi selengkapnya, lihat Gunakan GET /confirmEmail endpoint sebelumnya di artikel ini.

Gunakan titik akhir POST /forgotPassword

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

Isi permintaan hanya berisi Email. Berikut contohnya:

{
  "email": "string"
}

Untuk informasi tentang cara mengaktifkan Identity untuk mengirim email, lihat Gunakan GET /confirmEmail endpoint.

Gunakan titik akhir POST /resetPassword

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

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

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

Gunakan titik akhir POST /manage/2fa

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 JSON kosong ({}) 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 isi respons:

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

• Gunakan kunci yang dibagikan untuk memperoleh 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, login dengan memanggil endpoint /login menggunakan 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 memperoleh kunci bersama acak yang baru, panggil titik akhir ini dengan mengatur ResetSharedKey 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 flag "ingat saya" jika ada, panggil endpoint ini dengan cookie diatur ke true. Berikut adalah contoh isi permintaan:

{
  "forgetMachine": true
}

Titik akhir ini tidak berdampak pada autentikasi berbasis token.

Gunakan titik akhir GET /manage/info

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 properti Email dan IsEmailConfirmed, seperti dalam contoh berikut:

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

Gunakan titik akhir POST /manage/info

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