Autentikasi dan otorisasi dalam API minimal

Catatan

Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 10 dari artikel ini.

Peringatan

Versi ASP.NET Core ini tidak lagi didukung. Untuk informasi selengkapnya, lihat Kebijakan Dukungan .NET dan .NET Core. Untuk rilis saat ini, lihat versi .NET 9 dari artikel ini.

API minimal mendukung semua opsi autentikasi dan otorisasi yang tersedia di ASP.NET Core dan menyediakan beberapa fungsionalitas tambahan untuk meningkatkan pengalaman bekerja dengan autentikasi.

Konsep utama dalam autentikasi dan otorisasi

Autentikasi adalah proses penentuan identitas pengguna. Otorisasi adalah proses untuk menentukan apakah pengguna memiliki akses ke sumber daya. Skenario autentikasi dan otorisasi berbagi semantik implementasi serupa di ASP.NET Core. Autentikasi ditangani oleh layanan autentikasi, IAuthenticationService, yang digunakan oleh middleware autentikasi. Otorisasi ditangani oleh layanan otorisasi, IAuthorizationService, yang digunakan oleh middleware otorisasi.

Layanan autentikasi menggunakan pengendali autentikasi terdaftar untuk menyelesaikan tindakan terkait autentikasi. Misalnya, tindakan terkait autentikasi adalah mengautentikasi pengguna atau keluar dari pengguna. Skema autentikasi adalah nama yang digunakan untuk mengidentifikasi handler autentikasi dan opsi konfigurasinya secara unik. Penangan autentikasi bertanggung jawab untuk menerapkan strategi untuk autentikasi dan menghasilkan klaim pengguna yang diberikan strategi autentikasi tertentu, seperti OAuth atau OIDC. Opsi konfigurasi juga unik untuk suatu strategi dan menyediakan handler dengan konfigurasi yang berdampak pada perilaku autentikasi, seperti URI pengalihan.

Ada dua strategi untuk menentukan akses pengguna ke sumber daya di lapisan otorisasi:

• Strategi berbasis peran menentukan akses pengguna berdasarkan peran yang ditetapkan, seperti Administrator atau User. Untuk informasi selengkapnya tentang otorisasi berbasis peran, lihat dokumentasi otorisasi berbasis peran.
• Strategi berbasis klaim menentukan akses pengguna berdasarkan klaim yang dikeluarkan oleh otoritas pusat. Untuk informasi selengkapnya tentang otorisasi berbasis klaim, lihat dokumentasi otorisasi berbasis klaim.

Dalam ASP.NET Core, kedua strategi diambil ke dalam persyaratan otorisasi. Layanan otorisasi memanfaatkan penangan otorisasi untuk menentukan apakah pengguna tertentu memenuhi persyaratan otorisasi yang diterapkan ke sumber daya atau tidak.

Mengaktifkan autentikasi dalam aplikasi minimal

Untuk mengaktifkan autentikasi, panggil AddAuthentication untuk mendaftarkan layanan autentikasi yang diperlukan di penyedia layanan aplikasi.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Biasanya, strategi autentikasi tertentu digunakan. Dalam sampel berikut, aplikasi dikonfigurasi dengan dukungan untuk autentikasi berbasis pembawa JWT. Contoh ini memanfaatkan API yang tersedia dalam Microsoft.AspNetCore.Authentication.JwtBearer paket NuGet.

var builder = WebApplication.CreateBuilder(args);
// Requires Microsoft.AspNetCore.Authentication.JwtBearer
builder.Services.AddAuthentication().AddJwtBearer();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Secara default, WebApplication secara otomatis mendaftarkan middleware autentikasi dan otorisasi jika layanan autentikasi dan otorisasi tertentu diaktifkan. Dalam sampel berikut, tidak perlu memanggil UseAuthentication atau UseAuthorization mendaftarkan middleware karena WebApplication melakukan ini secara otomatis setelah AddAuthentication atau AddAuthorization dipanggil.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Dalam beberapa kasus, seperti mengontrol urutan middleware, perlu untuk secara eksplisit mendaftarkan autentikasi dan otorisasi. Dalam sampel berikut, middleware autentikasi dieksekusi setelah middleware CORS dieksekusi. Untuk informasi selengkapnya tentang middleware dan perilaku otomatis ini, lihat Middleware di aplikasi API Minimal.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCors();
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/", () => "Hello World!");
app.Run();

Mengonfigurasi strategi autentikasi

Strategi autentikasi biasanya mendukung berbagai konfigurasi yang dimuat melalui opsi. Aplikasi minimal mendukung opsi pemuatan dari konfigurasi untuk strategi autentikasi berikut:

• Berbasis token JWT
• Berbasis Koneksi OpenID

Kerangka kerja ASP.NET Core mengharapkan untuk menemukan opsi ini di bawah bagian Authentication:Schemes:{SchemeName} dalam konfigurasi. Dalam sampel berikut, dua skema yang berbeda, Bearer dan LocalAuthIssuer, didefinisikan dengan opsi masing-masing. Opsi Authentication:DefaultScheme ini dapat digunakan untuk mengonfigurasi strategi autentikasi default yang digunakan.

{
  "Authentication": {
    "DefaultScheme":  "LocalAuthIssuer",
    "Schemes": {
      "Bearer": {
        "ValidAudiences": [
          "https://localhost:7259",
          "http://localhost:5259"
        ],
        "ValidIssuer": "dotnet-user-jwts"
      },
      "LocalAuthIssuer": {
        "ValidAudiences": [
          "https://localhost:7259",
          "http://localhost:5259"
        ],
        "ValidIssuer": "local-auth"
      }
    }
  }
}

Dalam Program.cs, dua strategi autentikasi berbasis pembawa JWT terdaftar, dengan:

• Nama skema "Bearer".
• Nama skema "LocalAuthIssuer".

"Bearer" adalah skema default khas dalam aplikasi yang mendukung autentikasi JWT bearer, tetapi skema default dapat diganti dengan mengatur properti DefaultScheme seperti dalam contoh sebelumnya.

Nama skema digunakan untuk mengidentifikasi strategi autentikasi secara unik dan digunakan sebagai kunci pencarian saat menyelesaikan opsi autentikasi dari konfigurasi, seperti yang ditunjukkan dalam contoh berikut:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication()
  .AddJwtBearer()
  .AddJwtBearer("LocalAuthIssuer");
  
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Mengonfigurasi kebijakan otorisasi dalam aplikasi minimal

Autentikasi digunakan untuk mengidentifikasi dan memvalidasi identitas pengguna terhadap API. Otorisasi digunakan untuk memvalidasi dan memverifikasi akses ke sumber daya dalam API dan difasilitasi oleh IAuthorizationService yang terdaftar oleh metode ekstensi AddAuthorization. Dalam skenario berikut, /hello sumber daya ditambahkan yang mengharuskan pengguna untuk menyajikan admin klaim peran dengan greetings_api klaim cakupan.

Mengonfigurasi persyaratan otorisasi pada sumber daya adalah proses dua langkah yang memerlukan:

1. Mengonfigurasi persyaratan otorisasi dalam kebijakan secara global.
2. Menerapkan kebijakan individual ke sumber daya.

Dalam kode berikut, AddAuthorizationBuilder dipanggil yang:

• Menambahkan layanan terkait otorisasi ke kontainer DI.
• Mengembalikan AuthorizationBuilder yang dapat digunakan untuk mendaftarkan kebijakan otorisasi secara langsung.

Kode ini membuat kebijakan otorisasi baru, bernama admin_greetings, yang merangkum dua persyaratan otorisasi:

• Persyaratan berbasis peran melalui RequireRole untuk pengguna dengan peran admin.
• Persyaratan berbasis klaim melalui RequireClaim bahwa pengguna harus memberikan greetings_api klaim cakupan.

Kebijakan admin_greetings disediakan sebagai kebijakan wajib untuk endpoint /hello.

using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthorizationBuilder()
  .AddPolicy("admin_greetings", policy =>
        policy
            .RequireRole("admin")
            .RequireClaim("scope", "greetings_api"));

var app = builder.Build();

app.MapGet("/hello", () => "Hello world!")
  .RequireAuthorization("admin_greetings");

app.Run();

Gunakan dotnet user-jwts untuk pengujian pengembangan

Sepanjang artikel ini, digunakan aplikasi yang dikonfigurasi dengan autentikasi berbasis pembawa JWT. Autentikasi berbasis pembawa JWT mengharuskan klien menyajikan token di header permintaan untuk memvalidasi identitas dan klaim mereka. Biasanya, token ini dikeluarkan oleh otoritas pusat, seperti server identitas.

Saat mengembangkan pada komputer lokal, dotnet user-jwts alat ini dapat digunakan untuk membuat token pembawa.

dotnet user-jwts create

Catatan

Saat dipanggil pada proyek, alat secara otomatis menambahkan opsi autentikasi yang cocok dengan token yang dihasilkan ke appsettings.json.

Token dapat dikonfigurasi dengan berbagai kustomisasi. Misalnya, untuk membuat token untuk role admin dan cakupan greetings_api yang diharapkan oleh kebijakan otorisasi dalam kode di atas:

dotnet user-jwts create --scope "greetings_api" --role "admin"

Token yang dihasilkan kemudian dapat dikirim sebagai bagian dari header dalam alat pengujian pilihan. Misalnya, dengan curl:

curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/hello

Untuk informasi selengkapnya tentang alat ini dotnet user-jwts , baca dokumentasi lengkapnya.