Panduan Cepat: Mengamankan API Web ASP.NET Core

Dalam panduan cepat ini, Anda melindungi API web ASP.NET Core dengan Microsoft Entra ID menggunakan Microsoft.Identity.Web. Anda menambahkan middleware autentikasi yang memvalidasi token pembawa dan membatasi akses ke pemanggil yang diotorisasi.

Jika Anda tidak memiliki langganan Azure, buatlah akun gratis sebelum Anda memulai.

Prasyarat

.NET 9 SDK
Penyewa layanan Microsoft Entra ID. Jika Anda tidak memilikinya, buat akun gratis.
Pendaftaran aplikasi untuk API Anda

Opsi 1: Buat dari templat (tercepat)

Gunakan templat ASP.NET Core dengan autentikasi Microsoft Entra bawaan untuk membuat perancah proyek API yang dilindungi.

1. Buat proyek

Jalankan perintah berikut untuk membuat proyek API web baru dengan autentikasi organisasi tunggal dan navigasikan ke direktori proyek:

dotnet new webapi --auth SingleOrg --name MyWebApi
cd MyWebApi

2. Mengonfigurasi pendaftaran aplikasi

Ganti nilai placeholder di appsettings.json dengan detail pendaftaran aplikasi Microsoft Entra Anda.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-api-client-id"
  }
}

3. Jalankan API

Mulai aplikasi:

dotnet run

API Anda sekarang dilindungi di https://localhost:5001.

Selesai! Permintaan sekarang memerlukan token akses yang valid.

Opsi 2: Tambahkan ke API Web yang sudah ada

Jika Anda sudah memiliki API web ASP.NET Core, tambahkan autentikasi Microsoft Entra dengan langkah-langkah berikut.

1. Instal paket NuGet

Tambahkan Microsoft. Paket Identity.Web NuGet ke proyek Anda:

dotnet add package Microsoft.Identity.Web

2. Konfigurasi autentikasi di `Program.cs`

Daftarkan layanan autentikasi dan otorisasi di alur startup aplikasi Anda. Kode berikut mengonfigurasi autentikasi pembawa JWT dengan validasi Microsoft Entra:

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add authentication
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(builder.Configuration, "AzureAd");

// Add authorization
builder.Services.AddAuthorization();

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthentication(); //  Add authentication middleware
app.UseAuthorization();

app.MapControllers();

app.Run();

3. Tambahkan konfigurasi ke `appsettings.json`

Tambahkan bagian konfigurasi Microsoft Entra dengan detail penyewa dan aplikasi Anda. Atur tingkat pengelogan untuk Microsoft.Identity.Web ke Information untuk membantu memecahkan masalah validasi token:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-api-client-id"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Identity.Web": "Information"
    }
  }
}

4. Lindungi titik akhir API Anda

Terapkan atribut [Authorize] pada pengontrol atau tindakan yang memerlukan token akses yang valid.

Memerlukan autentikasi untuk semua titik akhir:

Pengontrol berikut memerlukan token akses yang valid untuk semua tindakan dan menunjukkan cara mengakses klaim pengguna:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[Authorize] //  Require valid access token
[ApiController]
[Route("api/[controller]")]
public class WeatherForecastController : ControllerBase
{
    [HttpGet]
    public IEnumerable<WeatherForecast> Get()
    {
        // Access user information
        var userId = User.FindFirst("oid")?.Value;
        var userName = User.Identity?.Name;

        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = "Protected data"
        });
    }
}

Memerlukan cakupan tertentu:

[RequiredScope] Gunakan atribut untuk memberlakukan izin terperindas pada tindakan individual:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Identity.Web;

[Authorize]
[ApiController]
[Route("api/[controller]")]
public class TodoController : ControllerBase
{
    [HttpGet]
    [RequiredScope("access_as_user")] //  Require specific scope
    public IActionResult GetAll()
    {
        return Ok(new[] { "Todo 1", "Todo 2" });
    }

    [HttpPost]
    [RequiredScope("write")] //  Different scope for write operations
    public IActionResult Create([FromBody] string item)
    {
        return Created("", item);
    }
}

5. Jalankan dan uji

Mulai aplikasi dan verifikasi bahwa permintaan yang tidak diautentikasi ditolak:

dotnet run

Uji dengan alat seperti Postman atau curl. Permintaan tidak diautentikasi mengembalikan 401 Unauthorized:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://localhost:5001/api/weatherforecast

Keberhasilan! API Anda sekarang memvalidasi token pembawa.

Penyiapan pendaftaran aplikasi

Sebelum API Anda dapat memvalidasi token, Anda memerlukan pendaftaran aplikasi Microsoft Entra. Ikuti langkah-langkah ini di portal Azure.

1. Daftarkan API Anda

Masuk ke portal Azure
Navigasi ke Microsoft Entra ID>Pendaftaran aplikasi>Pendaftaran baru
Masukkan nama (misalnya, "API Web Saya")
Pilih tenant tunggal (paling umum untuk API)
Tidak diperlukan URI pengalihan untuk API
Klik Daftar

2. Mengekspos cakupan API

Tentukan izin (cakupan) yang dapat diminta aplikasi klien saat memanggil API Anda.

Di pendaftaran aplikasi API Anda, buka Mengekspos API
Klik Tambahkan cakupan
Terima URI ID Aplikasi default atau sesuaikan (misalnya, api://your-api-client-id)
Tambahkan cakupan:
- Nama cakupan:access_as_user
- Siapa yang dapat menyetujui: Admin dan pengguna
- Nama tampilan persetujuan admin: "Akses API Web Saya"
- Deskripsi persetujuan admin: "Memungkinkan aplikasi mengakses API web atas nama pengguna yang masuk"
Klik Tambahkan cakupan

3. Perhatikan ID aplikasi

Salin ID Aplikasi (klien) dari halaman gambaran umum pendaftaran aplikasi. Nilai ini adalah ClientId Anda di appsettings.json.

Membuat pendaftaran aplikasi klien (untuk pengujian)

Untuk menguji API yang dilindungi, daftarkan aplikasi klien terpisah yang memperoleh token dan memanggil API.

1. Daftarkan aplikasi klien

Dalam Microsoft Entra ID>Pendaftaran aplikasi, buat pendaftaran lain
Beri nama (misalnya, "Klien API Saya")
Pilih jenis akun
Menambahkan URI pengalihan: https://localhost:7000/signin-oidc (jika aplikasi web)
Klik Daftar

2. Berikan izin API

Berikan izin aplikasi klien untuk memanggil API Anda dengan cakupan yang Anda tentukan.

Di pendaftaran aplikasi klien, buka izin API
Klik Tambahkan izin>API Saya
Pilih pendaftaran API Anda
Periksa cakupan access_as_user
Klik Tambahkan izin
Klik Berikan persetujuan admin (jika diperlukan)

3. Buat rahasia klien (untuk klien rahasia)

Jika aplikasi klien Anda berjalan di server (bukan browser atau perangkat seluler), buat rahasia klien untuk autentikasi.

Pergi ke Sertifikat & Rahasia
Klik Rahasia klien baru
Menambahkan deskripsi dan kedaluwarsa
Klik Tambahkan
Salin nilai rahasia segera - Anda tidak akan dapat melihatnya lagi

Menguji API yang dilindungi

Verifikasi bahwa API Anda memvalidasi token dengan benar dengan mengirim permintaan terautentikasi.

Menggunakan Postman

Siapkan autentikasi OAuth 2.0 di Postman untuk memperoleh token dan memanggil API Anda.

Membuat permintaan baru di Postman
Siapkan autentikasi OAuth 2.0:
- Jenis Pemberian: Kode Otorisasi (untuk konteks pengguna) atau Kredensial Klien (untuk konteks aplikasi)
- URL Autentikasi:https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
- URL Akses Token:https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
- ID Klien: ID aplikasi klien Anda
- Rahasia Klien: Rahasia aplikasi klien Anda
- Lingkup:api://your-api-client-id/access_as_user
Klik Dapatkan Token Akses Baru
Gunakan token untuk memanggil API Anda

Menggunakan kode (contoh C#)

Contoh berikut menggunakan MSAL.NET untuk memperoleh token dengan alur kredensial klien dan memanggil API yang dilindungi:

// In a console app or client application
using Microsoft.Identity.Client;

var app = ConfidentialClientApplicationBuilder
    .Create("client-app-id")
    .WithClientSecret("client-secret")
    .WithAuthority("https://login.microsoftonline.com/{tenant-id}")
    .Build();

var result = await app.AcquireTokenForClient(
    new[] { "api://your-api-client-id/.default" }
).ExecuteAsync();

var accessToken = result.AccessToken;

// Use the token to call your API
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", accessToken);

var response = await client.GetAsync("https://localhost:5001/api/weatherforecast");

Opsi konfigurasi umum

Microsoft. Identity.Web mendukung beberapa pola konfigurasi untuk skenario yang berbeda.

Memerlukan cakupan tertentu dalam konfigurasi

Alih-alih menggunakan [RequiredScope] atribut , Anda dapat mengonfigurasi cakupan yang diperlukan secara global di appsettings.json:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-api-client-id",
    "Scopes": "access_as_user"
  }
}

Menerima token dari beberapa penyewa

Untuk menerima token dari penyewa Microsoft Entra apa pun, atur TenantId ke common:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "common",
    "ClientId": "your-api-client-id"
  }
}

Mengonfigurasi validasi token

Jika API Anda memanggil API hilir (seperti Microsoft Graph), aktifkan akuisisi token dan konfigurasikan cache token:

builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi() // If your API calls other APIs
    .AddInMemoryTokenCaches();

Langkah berikutnya

Sekarang setelah Anda memiliki API yang dilindungi, jelajahi topik-topik ini:

Panggil downstream API - Memanggil Microsoft Graph atau API lainnya atas nama pengguna.
Mengonfigurasi cache token - Strategi cache produksi untuk skenario OBO.
Proses jangka panjang - Menangani pekerjaan latar belakang dengan token OBO.
Pasang di belakang gateway API - Azure API Management, Azure Front Door, Application Gateway.

Troubleshooting

401 Tidak Sah

Masalah: API mengembalikan 401 bahkan dengan token.

Kemungkinan penyebabnya:

Audiens token (aud klaim) tidak cocok dengan API Anda ClientId
Token kedaluwarsa
Token adalah untuk penyewa yang salah
Cakupan yang diperlukan hilang

Solusi: Dekode token di jwt.ms dan verifikasi klaim. Lihat Pencatatan & Diagnostik untuk pemecahan masalah terperinci.

AADSTS50013: Tanda tangan tidak valid

Masalah: Validasi tanda tangan token gagal.

Solusi: Pastikan TenantId dan ClientId Anda sudah benar. Token harus dikeluarkan oleh otoritas yang diharapkan. Aktifkan pengelogan terperinci untuk melihat kesalahan validasi.

Lingkup tidak ditemukan dalam token

Masalah:[RequiredScope] atribut gagal.

Solution:

Memverifikasi bahwa aplikasi klien memiliki izin ke cakupan
Pastikan persetujuan admin diberikan (jika diperlukan)
Lihat Panduan Otorisasi untuk pola validasi cakupan lengkap
Periksa apakah cakupan diminta saat memperoleh token (misalnya, api://your-api/.default atau cakupan tertentu)

Lihat selengkapnya:Panduan Pemecahan Masalah API Web

Panduan otorisasi - Atribut RequiredScope, kebijakan otorisasi, pemfilteran penyewa
Panduan kustomisasi - Mengonfigurasi opsi pembawa JWT dan parameter validasi
Pengelogan dan diagnostik - Memecahkan masalah autentikasi dengan ID korelasi
Tutorial API web yang dilindungi
sampel API

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-29