Mulai cepat: Memasukkan pengguna di aplikasi web ASP.NET Core

Dalam panduan cepat ini, Anda membuat aplikasi web ASP.NET Core yang mendaftarkan pengguna masuk dengan Microsoft Entra ID menggunakan Microsoft.Identity.Web. Anda dapat membuat perancah proyek baru dari templat atau menambahkan autentikasi ke aplikasi yang sudah ada.

Jika Anda tidak memiliki penyewa Microsoft Entra, buat akun gratis sebelum memulai.

Prasyarat

• .NET 9 SDK
• Penyewa Microsoft Entra ID
• Pendaftaran aplikasi di penyewa Microsoft Entra Anda. Jika Anda perlu membuatnya, lihat Mendaftarkan aplikasi Anda.

Membuat proyek dari templat

Cara tercepat untuk memulai adalah dengan membuat perancah proyek baru dengan autentikasi yang telah dikonfigurasi sebelumnya.

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

dotnet new webapp --auth SingleOrg --name MyWebApp
cd MyWebApp

Templat menghasilkan proyek dengan Microsoft.Identity.Web yang sudah dikonfigurasi. Anda hanya perlu memberikan detail pendaftaran aplikasi Anda.

Buka appsettings.json dan ganti nilai placeholder dengan ID Aplikasi (klien) dan ID Direktori (penyewa) dari pendaftaran aplikasi Anda:

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

Mulai aplikasi untuk memverifikasi bahwa proses masuk berfungsi:

dotnet run

Navigasi ke https://localhost:5001 dan pilih Masuk. Jika perintah masuk Microsoft muncul, konfigurasinya sudah benar.

Menambahkan autentikasi ke aplikasi web yang sudah ada

Jika Anda memiliki aplikasi ASP.NET Core yang sudah ada, ikuti langkah-langkah ini untuk menambahkan Microsoft Entra masuk.

Menginstal paket NuGet

Tambahkan pustaka Microsoft.Identity.Web. Paket Microsoft.Identity.Web menangani autentikasi, dan Microsoft.Identity.Web.UI menyediakan komponen UI masuk dan keluar bawaan:

dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.UI

Mengonfigurasi layanan autentikasi

Buka Program.cs dan tambahkan layanan autentikasi. Kode berikut mendaftarkan autentikasi OpenID Connect dengan Microsoft Entra, memungkinkan akuisisi token untuk panggilan API hilir, dan menambahkan UI masuk/keluar:

using Microsoft.Identity.Web;
using Microsoft.Identity.Web.UI;

var builder = WebApplication.CreateBuilder(args);

// Add authentication
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApp(builder.Configuration, "AzureAd")
                .EnableTokenAcquisitionToCallDownstreamApi() // Optional: if calling APIs
                .AddInMemoryTokenCaches(); // For production, use distributed cache

// Add Razor Pages or MVC
builder.Services.AddRazorPages()
    .AddMicrosoftIdentityUI(); // Adds sign-in/sign-out UI

var app = builder.Build();

// Configure middleware
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();

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

app.MapRazorPages();
app.MapControllers();

app.Run();

Tambahkan konfigurasi Microsoft Entra

Buka appsettings.json dan tambahkan bagian AzureAd . Ganti nilai tempat penampung dengan ID Aplikasi (klien) pendaftaran aplikasi Anda. Atur TenantId ke audiens yang sesuai untuk aplikasi Anda:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "common",
    "ClientId": "your-client-id-from-app-registration",
    "CallbackPath": "/signin-oidc"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Identity.Web": "Information"
    }
  }
}

Nilai TenantId menentukan akun mana yang dapat masuk:

Lindungi halaman Anda

Tambahkan atribut [Authorize] ke halaman atau pengontrol yang memerlukan masuk.

Untuk Halaman Razor, [Authorize] atribut mengalihkan pengguna yang tidak diautentikasi ke halaman masuk. Setelah masuk, klaim pengguna seperti Name dan preferred_username tersedia melalui User objek:

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

[Authorize] //  Require authentication
public class IndexModel : PageModel
{
    public void OnGet()
    {
        var userName = User.Identity?.Name;
        var userEmail = User.FindFirst("preferred_username")?.Value;
    }
}

Untuk pengontrol MVC, atribut yang sama [Authorize] berlaku di tingkat pengontrol atau tindakan:

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

[Authorize] //  Require authentication
public class HomeController : Controller
{
    public IActionResult Index()
    {
        var userName = User.Identity?.Name;
        return View();
    }
}

Menambahkan tautan masuk dan keluar

Tambahkan tautan navigasi ke tata letak Anda sehingga pengguna bisa masuk dan keluar. Rute area MicrosoftIdentity disediakan oleh paket Microsoft.Identity.Web.UI. Markup Razor berikut ini secara kondisional merender Keluar atau Masuk berdasarkan status autentikasi pengguna:

<ul class="navbar-nav">
    @if (User.Identity?.IsAuthenticated == true)
    {
        <li class="nav-item">
            <span class="nav-link">Hello @User.Identity.Name!</span>
        </li>
        <li class="nav-item">
            <a class="nav-link" asp-area="MicrosoftIdentity" asp-controller="Account" asp-action="SignOut">Sign out</a>
        </li>
    }
    else
    {
        <li class="nav-item">
            <a class="nav-link" asp-area="MicrosoftIdentity" asp-controller="Account" asp-action="SignIn">Sign in</a>
        </li>
    }
</ul>

Jalankan dan uji

Mulai aplikasi untuk memverifikasi bahwa autentikasi berfungsi:

dotnet run

Navigasi ke https://localhost:5001. Anda akan melihat tautan Masuk . Pilih itu untuk mengonfirmasi bahwa alur masuk Microsoft berhasil diselesaikan.

Daftarkan aplikasi Anda

Jika Anda belum memiliki pendaftaran aplikasi, ikuti langkah-langkah ini untuk membuatnya di portal Azure.

1. Masuk ke portal Azure.
2. Navigate ke Microsoft Entra ID>Pendaftaran aplikasi>Pendaftaran baru.
3. Masukkan nama tampilan (misalnya, "Aplikasi Web Saya").
4. Pilih jenis akun yang didukung:
   • Single tenant — Hanya pengguna di organisasi Anda saja
   • Multi-tenancy — Pengguna di organisasi mana pun
   • PenyewaMulti + pribadi — Semua akun Microsoft
5. Di bawah URI Pengalihan, atur platform ke Web dan masukkan https://localhost:5001/signin-oidc.
6. Pilih Daftarkan.
7. Pada halaman gambaran umum, salin ID Aplikasi (klien) dan ID Direktori (penyewa). Anda memerlukan nilai ini untuk bidang ClientId dan TenantId di appsettings.json.

Mengonfigurasi pengaturan opsional

Skenario Anda mungkin memerlukan pengaturan tambahan ini.

Aktifkan penerbitan token ID — Beberapa skenario autentikasi hibrid mengharuskan token ID dikeluarkan langsung dari titik akhir otorisasi. Alur kode otorisasi (digunakan oleh Microsoft. Identity.Web) adalah pendekatan yang direkomendasikan. Hanya aktifkan pengaturan ini jika skenario Anda secara khusus memerlukannya:

1. Di pendaftaran aplikasi Anda, buka Autentikasi.
2. Di bawah Pemberian implisit dan alur hibrid, pilih token ID.
3. Pilih Simpan.

Konfigurasi URL logout saluran depan — Memastikan pengguna keluar dari aplikasi Anda ketika mereka logout dari Microsoft Entra:

1. Di pendaftaran aplikasi Anda, buka Autentikasi.
2. Di bawah URL keluar saluran depan, masukkan https://localhost:5001/signout-oidc.
3. Pilih Simpan.

Memecahkan masalah kesalahan umum

Jika Anda mengalami masalah selama login, periksa kesalahan umum berikut.

Konten terkait

• Memanggil API hilir dari aplikasi web
• Otorisasi
• Gambaran umum tentang cache token
• Mulai cepat: API Web