Mengonfigurasi autentikasi OpenID Connect Web (UI) di ASP.NET Core

Artikel ini membahas area berikut:

Apa itu klien interaktif rahasia OpenID Connect
Membuat klien OpenID Connect di ASP.NET Core
Contoh klien OpenID Connect dengan cuplikan kode
Menggunakan klien penyedia OpenID Connect pihak ketiga
Backend untuk arsitektur keamanan frontend (BFF)
Fitur lanjutan, standar, memperluas klien OpenID Connect

Untuk pengalaman alternatif menggunakan Microsoft Authentication Library for .NET, Microsoft Identity Web, dan Microsoft Entra ID, lihat Panduan Cepat: Masuk pengguna dan memanggil Microsoft Graph API dari aplikasi web ASP.NET Core (dokumentasi Azure).

Untuk contoh menggunakan server OIDC ID Eksternal Microsoft Entra, lihat untuk contoh masuk pengguna ke aplikasi web ASP.NET Core di penyewa eksternal dan Aplikasi web ASP.NET Core yang mengautentikasi pengguna dengan ID Eksternal Microsoft Entra menggunakan Microsoft Identity Web.

Apa itu klien interaktif rahasia OpenID Connect

OpenID Connect dapat digunakan untuk menerapkan autentikasi di aplikasi ASP.NET Core. Cara yang disarankan adalah menggunakan klien rahasia OpenID Connect menggunakan alur kode. Menggunakan Kunci Bukti untuk Pertukaran Kode oleh Klien Publik OAuth (PKCE) direkomendasikan untuk implementasi ini. Klien aplikasi dan pengguna aplikasi diautentikasi dalam alur rahasia. Klien aplikasi menggunakan rahasia klien atau pernyataan klien untuk mengautentikasi.

Klien OpenID Connect/OAuth publik tidak lagi direkomendasikan untuk aplikasi web.

Alur default berfungsi seperti yang ditunjukkan dalam diagram berikut:

Klien rahasia aliran kode OIDC menggunakan PKCE

OpenID Connect hadir dalam banyak variasi dan semua implementasi server memiliki parameter dan persyaratan yang sedikit berbeda. Beberapa server tidak mendukung titik akhir info pengguna, beberapa masih tidak mendukung PKCE dan yang lain memerlukan parameter khusus dalam permintaan token. Pernyataan klien dapat digunakan alih-alih rahasia klien. Standar baru juga ada yang menambahkan keamanan ekstra di atas OpenID Connect Core, misalnya FAPI, CIBA atau DPoP untuk API hilir.

Catatan

Dari .NET 9, Permintaan Otorisasi Yang Didorong OAuth 2.0 (PAR) RFC 9126 digunakan per default, jika server OpenID Connect mendukung ini. Ini adalah alur tiga langkah dan bukan alur dua langkah seperti yang ditunjukkan di atas. (Permintaan Info Pengguna adalah langkah opsional.)

Membuat klien alur kode Open ID Connect menggunakan Razor Pages

Bagian berikut menunjukkan cara mengimplementasikan klien OpenID Connect dalam proyek halaman ASP.NET Core Razor kosong. Logika yang sama dapat diterapkan ke proyek web ASP.NET Core dengan hanya integrasi UI yang berbeda.

Menambahkan dukungan OpenID Connect

Tambahkan paket Microsoft.AspNetCore.Authentication.OpenIdConnect Nuget ke proyek ASP.NET Core.

Menyiapkan klien OpenID Connect

Tambahkan autentikasi ke aplikasi web menggunakan builder.Services di file Program.cs. Konfigurasi bergantung pada server OpenID Connect. Setiap server OpenID Connect memerlukan perbedaan kecil dalam penyiapan.

Handler OpenID Connect digunakan untuk tantangan dan signout. cookie digunakan untuk menangani sesi di aplikasi web. Skema default untuk autentikasi dapat ditentukan sebagaimana diperlukan.

Untuk informasi selengkapnya, lihat panduan ASP.NET Core authentication-handler.

builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
})
.AddCookie()
.AddOpenIdConnect(options =>
{
    var oidcConfig = builder.Configuration.GetSection("OpenIDConnectSettings");

    options.Authority = oidcConfig["Authority"];
    options.ClientId = oidcConfig["ClientId"];
    options.ClientSecret = oidcConfig["ClientSecret"];

    options.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.ResponseType = OpenIdConnectResponseType.Code;

    options.SaveTokens = true;
    options.GetClaimsFromUserInfoEndpoint = true;

    options.MapInboundClaims = false;
    options.TokenValidationParameters.NameClaimType = JwtRegisteredClaimNames.Name;
    options.TokenValidationParameters.RoleClaimType = "roles";
});

Untuk detail tentang opsi OpenID Connect yang berbeda, lihat Mengamankan Blazor Web App ASP.NET Core dengan OpenID Connect (OIDC).

Untuk berbagai kemungkinan pemetaan klaim, lihat Memetakan, menyesuaikan, dan mengubah klaim di ASP.NET Core.

Catatan

Namespace berikut diperlukan:

using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Authentication.OpenIdConnect;
using Microsoft.IdentityModel.Protocols.OpenIdConnect;
using Microsoft.IdentityModel.Tokens;

Menyiapkan properti konfigurasi

Tambahkan pengaturan klien OpenID Connect ke properti konfigurasi aplikasi. Pengaturan harus cocok dengan konfigurasi klien di server OpenID Connect. Tidak ada rahasia yang harus dipertahankan dalam pengaturan aplikasi di mana mereka mungkin secara tidak sengaja diperiksa. Rahasia harus disimpan di lokasi yang aman seperti Azure Key Vault di lingkungan produksi atau di rahasia pengguna di lingkungan pengembangan. Untuk informasi selengkapnya, lihat Penyimpanan rahasia aplikasi yang aman dalam pengembangan di ASP.NET Core.

"OpenIDConnectSettings": {
  // OpenID Connect URL. (The base URL for the /.well-known/openid-configuration)
  "Authority": "<Authority>",
  // client ID from the OpenID Connect server
  "ClientId": "<Client ID>",
  //"ClientSecret": "--stored-in-user-secrets-or-key-vault--"
},

Konfigurasi jalur panggilan balik keluar

SignedOutCallbackPath (kunci konfigurasi: "SignedOutCallbackPath") adalah jalur permintaan dalam jalur dasar aplikasi yang diintersepsi oleh pengendali OpenID Connect, di mana agen pengguna pertama kali diarahkan kembali setelah keluar dari penyedia identitas. Aplikasi sampel tidak menetapkan nilai untuk jalur karena nilai default "/signout-callback-oidc" digunakan. Setelah mencegat permintaan, handler OpenID Connect mengalihkan ke SignedOutRedirectUri atau RedirectUri, jika ditentukan.

Konfigurasikan jalur callback saat keluar dalam pendaftaran penyedia OIDC aplikasi. Dalam contoh berikut, penanda {PORT} adalah port aplikasi:

https://localhost:{PORT}/signout-callback-oidc

Catatan

Saat menggunakan Microsoft Entra ID, atur jalur di konfigurasi platform Web entri URI Pengalihan di portal Entra atau Microsoft Azure. Port tidak diperlukan untuk alamat localhost saat menggunakan Entra. Sebagian besar penyedia OIDC lainnya memerlukan port yang benar. Jika Anda tidak menambahkan URI jalur yang keluar setelah log-out ke pendaftaran aplikasi di Entra, Entra menolak untuk mengalihkan pengguna kembali ke aplikasi dan hanya menyuruh pengguna untuk menutup jendela browser mereka.

Perbarui metode alur ASP.NET Core di kelas program.

Metode UseRouting harus diimplementasikan sebelum metode UseAuthorization.

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

app.UseRouting();
app.UseAuthentication();
// Authorization is applied for middleware after the UseAuthorization method
app.UseAuthorization();
app.MapRazorPages();

Paksa otorisasi

Tambahkan atribut [Authorize] ke halaman Razor yang dilindungi:

[Authorize]

Pendekatan yang lebih baik adalah memaksa otorisasi untuk seluruh aplikasi dan memilih keluar untuk halaman yang tidak aman:

var requireAuthPolicy = new AuthorizationPolicyBuilder()
    .RequireAuthenticatedUser()
    .Build();

builder.Services.AddAuthorizationBuilder()
    .SetFallbackPolicy(requireAuthPolicy);

Menolak otorisasi di titik akhir publik dengan menerapkan [AllowAnonymous] atribut ke titik akhir publik. Misalnya, lihat bagian Tambahkan halaman dan Logout.cshtmlSignedOut.cshtml baru Razor ke proyek dan TerapkanLogin.

Menambahkan halaman `Logout.cshtml` dan `SignedOut.cshtml`Razor baru ke proyek

Pengguna harus keluar untuk mengakhiri sesi cookie dan sesi OpenID Connect. Seluruh aplikasi perlu mengalihkan ke server OpenID Connect untuk keluar. Setelah berhasil keluar, aplikasi membuka rute RedirectUri.

Terapkan halaman logout default dan ubah kode halaman Razor Logout menjadi seperti berikut:

[Authorize]
public class LogoutModel : PageModel
{
    public IActionResult OnGetAsync()
    {
        return SignOut(new AuthenticationProperties
        {
            RedirectUri = "/SignedOut"
        },
        // Clear auth cookie
        CookieAuthenticationDefaults.AuthenticationScheme,
        // Redirect to OIDC provider signout endpoint
        OpenIdConnectDefaults.AuthenticationScheme);
    }
}

SignedOut.cshtml memerlukan atribut [AllowAnonymous]:

[AllowAnonymous]
public class SignedOutModel : PageModel
{
    public void OnGet()
    {
    }
}

Menerapkan halaman `Login`

Halaman LoginRazor juga dapat diimplementasikan untuk memanggil ChallengeAsync secara langsung dengan AuthPropertiesyang diperlukan. Ini tidak diperlukan jika aplikasi web memerlukan autentikasi dan tantangan default digunakan.

Halaman Login.cshtml memerlukan atribut [AllowAnonymous]:

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

namespace RazorPageOidc.Pages;

[AllowAnonymous]
public class LoginModel : PageModel
{
    [BindProperty(SupportsGet = true)]
    public string? ReturnUrl { get; set; }

    public async Task OnGetAsync()
    {
        var properties = GetAuthProperties(ReturnUrl);
        await HttpContext.ChallengeAsync(properties);
    }

    private static AuthenticationProperties GetAuthProperties(string? returnUrl)
    {
        const string pathBase = "/";

        // Prevent open redirects.
        if (string.IsNullOrEmpty(returnUrl))
        {
            returnUrl = pathBase;
        }
        else if (!Uri.IsWellFormedUriString(returnUrl, UriKind.Relative))
        {
            returnUrl = new Uri(returnUrl, UriKind.Absolute).PathAndQuery;
        }
        else if (returnUrl[0] != '/')
        {
            returnUrl = $"{pathBase}{returnUrl}";
        }

        return new AuthenticationProperties { RedirectUri = returnUrl };
    }
}

@if (Context.User.Identity!.IsAuthenticated)
{
	<li class="nav-item">
		<a class="nav-link text-dark" asp-area="" asp-page="/Logout">Logout</a>
	</li>

	<span class="nav-link text-dark">Hi @Context.User.Identity.Name</span>
}
else
{
	<li class="nav-item">
		<a class="nav-link text-dark" asp-area="" asp-page="/Index">Login</a>
	</li>
}

Contoh dengan cuplikan kode

Contoh Menggunakan titik akhir Info Pengguna

Opsi OpenID Connect dapat digunakan untuk memetakan klaim, menerapkan handler, atau bahkan menyimpan token dalam sesi untuk penggunaan nanti.

Opsi Scope dapat digunakan untuk meminta klaim yang berbeda atau token refresh yang dikirim sebagai informasi ke server OpenID Connect. Meminta offline_access meminta server untuk mengembalikan token referensi yang dapat digunakan untuk me-refresh sesi tanpa mengautentikasi pengguna aplikasi lagi.

services.AddAuthentication(options =>
{
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
})
.AddCookie()
.AddOpenIdConnect(OpenIdConnectDefaults.AuthenticationScheme, options =>
{
    var oidcConfig = builder.Configuration.GetSection("OpenIDConnectSettings");
    options.Authority = oidcConfig["IdentityProviderUrl"];
    options.ClientSecret = oidcConfig["ClientSecret"];
    options.ClientId = oidcConfig["Audience"];
    options.ResponseType = OpenIdConnectResponseType.Code;

    options.Scope.Clear();
    options.Scope.Add("openid");
    options.Scope.Add("profile");
    options.Scope.Add("email");
    options.Scope.Add("offline_access");

    options.ClaimActions.Remove("amr");
    options.ClaimActions.MapUniqueJsonKey("website", "website");

    options.GetClaimsFromUserInfoEndpoint = true;
    options.SaveTokens = true;

    // .NET 9 feature
    options.PushedAuthorizationBehavior = PushedAuthorizationBehavior.Require;

    options.TokenValidationParameters.NameClaimType = "name";
    options.TokenValidationParameters.RoleClaimType = "role";
});

Menerapkan penyedia identitas Microsoft

Microsoft memiliki beberapa penyedia identitas dan implementasi OpenID Connect. Microsoft memiliki server OpenID Connect yang berbeda:

Microsoft Entra ID
Microsoft Entra External ID
Azure AD B2C

Jika mengautentikasi menggunakan salah satu penyedia identitas Microsoft di ASP.NET Core, disarankan untuk menggunakan paket Microsoft.Identity.Web Nuget.

Paket Microsoft.Identity.Web Nuget adalah klien spesifik Microsoft yang dibangun di atas klien ASP.NET Core OpenID Connect dengan beberapa perubahan pada klien default.

Menggunakan klien penyedia OpenID Connect pihak ketiga

Banyak implementasi server OpenID Connect membuat paket Nuget yang dioptimalkan untuk implementasi OpenID Connect yang sama. Paket ini mengimplementasikan klien OpenID Connect khusus dengan ekstra yang diperlukan oleh server OpenID Connect tertentu. Microsoft.Identity.Web adalah salah satu contohnya.

Jika menerapkan beberapa klien OpenID Connect dari server OpenID Connect yang berbeda dalam satu aplikasi, biasanya lebih baik kembali menggunakan implementasi default ASP.NET Core karena klien yang berbeda dapat mengubah beberapa opsi yang memengaruhi klien lainnya.

Penyedia Web OpenIddict adalah implementasi klien yang mendukung banyak implementasi server yang berbeda.

IdentityModel adalah pustaka pembantu standar .NET untuk identitas berbasis klaim, OAuth 2.0 dan OpenID Connect. Ini juga dapat digunakan untuk membantu implementasi klien.

Backend untuk arsitektur keamanan frontend (BFF)

Tidak disarankan lagi untuk menerapkan klien publik OpenID Connect untuk aplikasi web apa pun.

Untuk informasi selengkapnya, lihat draf OAuth 2.0 untuk Aplikasi Browser-Based.

Jika menerapkan aplikasi web yang tidak memiliki backend independen, sebaiknya gunakan pola Backend for Frontend (BFF) arsitektur keamanan. Pola ini dapat diimplementasikan dengan cara yang berbeda, tetapi autentikasi selalu diimplementasikan di backend, dan tidak ada data sensitif yang dikirim ke klien web untuk alur otorisasi atau autentikasi lebih lanjut.

Fitur lanjutan, standar, memperluas klien OIDC

Pencatatan

Men-debug klien OpenID Connect bisa sulit. Data informasi pengidentifikasi pribadi (PII) tidak dicatat secara default. Jika debugging dalam status pengembangan, IdentityModelEventSource.ShowPII dapat digunakan untuk mencatat data pribadi sensitif. Jangan sebarkan aplikasi dengan IdentityModelEventSource.ShowPII ke server produktif.

//using ...

using Microsoft.IdentityModel.Logging;

var builder = WebApplication.CreateBuilder(args);

//... code 

var app = builder.Build();

IdentityModelEventSource.ShowPII = true;

//... code 

app.Run();

Untuk informasi selengkapnya, lihat Logging.

Catatan

Anda mungkin ingin menurunkan tingkat log yang dikonfigurasi untuk melihat semua log yang diperlukan.

Kustomisasi Parameter OIDC dan OAuth

Opsi handler autentikasi OAuth dan OIDC (AdditionalAuthorizationParameters) memungkinkan penyesuaian parameter pesan otorisasi yang biasanya disertakan sebagai bagian dari string kueri pengalihan.

Memetakan klaim dari OpenID Connect

Untuk informasi selengkapnya, lihat Memetakan, menyesuaikan, dan mengubah klaim di ASP.NET Core.

Blazor OpenID Connect

Untuk informasi selengkapnya, lihat Mengamankan Blazor Web App ASP.NET Core dengan OpenID Connect (OIDC).

Standar

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-01-22

Bagikan melalui

Mengonfigurasi autentikasi OpenID Connect Web (UI) di ASP.NET Core

Apa itu klien interaktif rahasia OpenID Connect

Membuat klien alur kode Open ID Connect menggunakan Razor Pages

Menambahkan dukungan OpenID Connect

Menyiapkan klien OpenID Connect

Menyiapkan properti konfigurasi

Konfigurasi jalur panggilan balik keluar

Perbarui metode alur ASP.NET Core di kelas program.

Paksa otorisasi

Menambahkan halaman Logout.cshtml dan SignedOut.cshtmlRazor baru ke proyek

Menerapkan halaman Login

Menambahkan tombol masuk dan keluar untuk pengguna

Contoh dengan cuplikan kode

Contoh Menggunakan titik akhir Info Pengguna

Menerapkan penyedia identitas Microsoft

Menggunakan klien penyedia OpenID Connect pihak ketiga

Backend untuk arsitektur keamanan frontend (BFF)

Fitur lanjutan, standar, memperluas klien OIDC

Pencatatan

Kustomisasi Parameter OIDC dan OAuth

Memetakan klaim dari OpenID Connect

Blazor OpenID Connect

Standar

Saran dan Komentar

Sumber Daya Tambahan:

Menambahkan halaman `Logout.cshtml` dan `SignedOut.cshtml`Razor baru ke proyek

Menerapkan halaman `Login`