Bagikan melalui

API web yang dilindungi: Konfigurasi kode

Berlaku untuk: Lingkaran hijau dengan simbol tanda centang putih yang menunjukkan konten berikut berlaku untuk penyewa tenaga kerja. Penyewa tenaga kerja (pelajari lebih lanjut)

Untuk mengonfigurasi kode untuk API web yang dilindungi, pahami:

  • Apa yang mendefinisikan API sebagai dilindungi.
  • Cara mengonfigurasi token pembawa.
  • Cara memvalidasi token.

Versi token yang diterima

Platform identitas Microsoft dapat mengeluarkan token v1.0 dan token v2.0. Untuk informasi selengkapnya tentang token ini, lihat Token akses.

Versi token yang mungkin diterima API Anda bergantung pada pilihan Jenis akun yang didukung saat Anda membuat pendaftaran aplikasi API web di portal Microsoft Azure.

  • Jika nilai Jenis akun yang didukung adalah Akun di direktori organisasi dan akun Microsoft pribadi apa pun (seperti Skype, Xbox, Outlook.com), versi token yang diterima harus v2.0.
  • Jika tidak, versi token yang diterima dapat v1.0.

Setelah membuat aplikasi, Anda dapat menentukan atau mengubah versi token yang diterima dengan mengikuti langkah-langkah berikut:

  1. Di pusat admin Microsoft Entra, pilih aplikasi Anda lalu pilih Manifes.
  2. Temukan properti accessTokenAcceptedVersion dalam manifes.
  3. Nilai tersebut menentukan versi token mana yang diterima API web oleh Microsoft Entra.
    • Jika nilainya adalah 2, API web akan menerima token v2.0.
    • Jika nilainya null, API web menerima token v1.0.
  4. Jika Anda mengubah versi token, pilih Simpan.

API web menentukan versi token mana yang diterimanya. Ketika klien meminta token untuk API web Anda dari platform identitas Microsoft, klien mendapatkan token yang menunjukkan versi token mana yang diterima API web.

Apa yang mendefinisikan ASP.NET dan ASP.NET Core API sebagai dilindungi?

Seperti aplikasi web, api web ASP.NET dan ASP.NET Core dilindungi karena tindakan pengontrolnya diawali dengan atribut [Otorisasi ]. Tindakan pengontrol hanya dapat dipanggil jika API dipanggil dengan identitas yang sah.

Pertimbangkan pertanyaan-pertanyaan berikut:

  • Hanya aplikasi dapat memanggil API web. Bagaimana cara API mengetahui identitas aplikasi yang memanggilnya?
  • Jika aplikasi memanggil API atas nama pengguna, apa identitas pengguna?

Token pembawa

Token pembawa yang diatur di dalam header saat aplikasi itu dipanggil menyimpan informasi tentang identitas aplikasi. Token ini juga menyimpan informasi tentang pengguna kecuali jika aplikasi web menerima panggilan antar layanan dari aplikasi daemon.

Berikut ini adalah contoh kode C# yang menunjukkan klien yang memanggil API setelah memperoleh token dengan Microsoft Authentication Library for .NET (MSAL.NET):

var scopes = new[] {$"api://.../access_as_user"};
var result = await app.AcquireToken(scopes)
                      .ExecuteAsync();

httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", result.AccessToken);

// Call the web API.
HttpResponseMessage response = await _httpClient.GetAsync(apiUri);

Penting

Aplikasi klien meminta token pembawa ke platform identitas Microsoft untuk API web. API adalah satu-satunya aplikasi yang harus memverifikasi token dan melihat klaim yang dikandungnya. Aplikasi klien tidak boleh mencoba memeriksa klaim yang ada di dalam token.

Di masa mendatang, API web mungkin mengharuskan token dienkripsi. Persyaratan ini akan mencegah akses untuk aplikasi klien yang dapat melihat token akses.

Konfigurasi JwtBearer

Bagian ini menjelaskan cara mengonfigurasi token pembawa.

File konfigurasi

Anda perlu menentukan TenantId hanya jika Anda ingin menerima token akses dari satu penyewa (aplikasi khusus bisnis). Jika tidak, itu dapat dibiarkan sebagai common. Nilai yang berbeda dapat berupa:

  • Sebuah GUID (ID Penyewa = ID Direktori)
  • common dapat berupa akun organisasi dan pribadi apa pun
  • organizations dapat menjadi organisasi apa pun
  • consumers adalah akun pribadi Microsoft
{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "Enter_the_Application_(client)_ID_here",
    "TenantId": "common"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Menggunakan URI ID Aplikasi kustom untuk API web

Jika Anda telah menerima URI ID Aplikasi default yang diusulkan oleh portal Microsoft Azure, Anda tidak perlu menentukan audiens. Jika tidak, Anda harus menambah properti Audience yang nilainya adalah URI ID Aplikasi untuk API web Anda. Ini biasanya dimulai dengan api://.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "Enter_the_Application_(client)_ID_here",
    "TenantId": "common",
    "Audience": "Enter_the_Application_ID_URI_here"
  },
}

Inisialisasi kode

Ketika aplikasi dipanggil pada tindakan pengontrol yang memegang atribut [Authorize], ASP.NET dan ASP.NET Core mengekstrak token akses dari token pembawa header Otorisasi. Token akses kemudian diteruskan ke middleware JwtBearer, yang memanggil Microsoft IdentityModel Extensions for .NET.

Microsoft.Identitas.Web

Microsoft menyarankan Anda menggunakan paket Microsoft.Identity.Web NuGet saat mengembangkan API web dengan ASP.NET Core.

Microsoft.Identity.Web menyediakan perekat antara ASP.NET Core, middleware autentikasi, dan Microsoft Authentication Library (MSAL) untuk .NET. Ini memungkinkan pengalaman pengembang yang lebih jelas dan lebih kuat dan memanfaatkan kekuatan platform identitas Microsoft dan Azure AD B2C.

ASP.NET untuk .NET 6.0

Untuk membuat proyek API web baru yang menggunakan Microsoft.Identity.Web, gunakan templat proyek di CLI .NET 6.0 atau Visual Studio.

Dotnet Core CLI

# Create new web API that uses Microsoft.Identity.Web
dotnet new webapi --auth SingleOrg

Visual Studio - Untuk membuat proyek API web di Visual Studio, pilih File>Baru>Proyek>ASP.NET Core Web API.

Templat proyek .NET CLI dan Visual Studio membuat file Program.cs yang terlihat mirip dengan cuplikan kode ini. Perhatikan Microsoft.Identity.Web menggunakan direktif dan baris yang berisi autentikasi dan otorisasi.

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

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

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

app.MapControllers();

app.Run();
  • Last updated on