Amankan ASP.NET Core Blazor Web App dengan OpenID Connect (OIDC)

2025-04-30

Catatan

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

Penting

Informasi ini berkaitan dengan produk pra-rilis yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Untuk rilis saat ini, lihat versi .NET 9 dari artikel ini.

Artikel ini menjelaskan cara mengamankan Blazor Web App dengan OpenID Connect (OIDC) menggunakan aplikasi sampel di dotnet/blazor-samples repositori GitHub (.NET 8 atau yang lebih baru) (cara mengunduh).

Untuk Microsoft Entra ID atau Azure AD B2C, Anda dapat menggunakan AddMicrosoftIdentityWebApp dari Microsoft Identity Web (Microsoft.Identity.Web paket NuGet, dokumentasi API), yang menambahkan penangan OIDC dan penangan autentikasi dengan setelan baku yang sesuai. Aplikasi sampel dan panduan dalam artikel ini tidak menggunakan Microsoft Identity Web. Panduan ini menunjukkan cara mengonfigurasi handler OIDC secara manual untuk penyedia OIDC apa pun. Untuk informasi selengkapnya tentang menerapkan Microsoft Identity Web, lihat Mengamankan ASP.NET Core Blazor Web App dengan ID Microsoft Entra.

Versi artikel ini mencakup penerapan OIDC tanpa mengadopsi pola Backend for Frontend (BFF) dengan aplikasi yang menggunakan rendering interaktif otomatis secara global (untuk server dan proyek .Client). Pola BFF berguna untuk membuat permintaan terautentikasi ke layanan eksternal. Ubah pemilih versi artikel menjadi pola BFF jika spesifikasi aplikasi memanggil untuk mengadopsi pola BFF.

Spesifikasi berikut diadopsi:

Blazor Web App menggunakan mode Render otomatis dengan interaktivitas global.
Layanan penyedia status autentikasi kustom digunakan oleh server dan aplikasi klien untuk menangkap status autentikasi pengguna dan mengalirkannya antara server dan klien.
Aplikasi ini adalah titik awal untuk alur autentikasi OIDC apa pun. OIDC dikonfigurasi secara manual di aplikasi dan tidak mengandalkan ID Microsoft Entra atau paket Web MicrosoftIdentity, aplikasi sampel juga tidak memerlukan hosting Microsoft Azure. Namun, aplikasi sampel dapat digunakan dengan Entra, Microsoft Identity Web, dan dihosting di Azure.
Pembaruan token otomatis tanpa interaksi.
Proyek API web terpisah menunjukkan panggilan API web yang aman untuk data cuaca.

Untuk pengalaman alternatif menggunakan Microsoft Authentication Library untuk .NET, Microsoft Identity Web, dan MICROSOFT Entra ID, lihat Mengamankan ASP.NET Core Blazor Web App dengan ID Microsoft Entra.

Contoh solusi

Aplikasi sampel terdiri dari proyek berikut:

BlazorWebAppOidc: Proyek sisi server dari Blazor Web App, yang berisi contoh titik akhir API Minimal untuk data cuaca.
BlazorWebAppOidc.Client: Proyek pihak klien dari Blazor Web App.
MinimalApiJwt: API backend web dengan endpoint Minimal API untuk data cuaca.

Akses sampel melalui folder versi terbaru di repositori sampel Blazor dengan tautan berikut. Sampel berada di folder BlazorWebAppOidc untuk .NET 8 atau yang lebih baru.

Mulai solusi dari Aspire/Aspire.AppHost proyek.

Menampilkan atau mengunduh kode sampel (cara mengunduh)

Fitur solusi sampel:

Pembaharuan token non-interaktif otomatis dengan bantuan pemulihan kustom cookie (CookieOidcRefresher.cs).
Data cuaca ditangani oleh titik akhir API Minimal (/weather-forecast) di file Program (Program.cs) proyek MinimalApiJwt. Titik akhir memerlukan otorisasi dengan memanggil RequireAuthorization. Untuk pengontrol apa pun yang Anda tambahkan ke proyek, tambahkan [Authorize] atribut ke pengontrol atau tindakan. Untuk informasi selengkapnya tentang memerlukan otorisasi di seluruh aplikasi melalui kebijakan otorisasi dan menolak otorisasi pada subset titik akhir publik, lihat Razor panduan Pages OIDC.
Aplikasi ini dengan aman memanggil API web untuk data cuaca:
- Saat merender komponen Weather di server, komponen tersebut menggunakan ServerWeatherForecaster untuk mendapatkan data cuaca dari API web dalam proyek MinimalApiJwt dengan menggunakan DelegatingHandler (TokenHandler) yang melampirkan token akses dari HttpContext ke dalam permintaan.
- Ketika komponen dirender pada klien, komponen menggunakan implementasi layanan ClientWeatherForecaster, yang memanfaatkan HttpClient yang pra-konfigurasi (dalam file Program proyek klien) untuk melakukan panggilan API web dari ServerWeatherForecaster proyek server.

Proyek server memanggil AddAuthenticationStateSerialization untuk menambahkan penyedia status autentikasi sisi server yang menggunakan PersistentComponentState untuk mengalirkan status autentikasi ke klien. Klien memanggil fungsi AddAuthenticationStateDeserialization untuk mendeserialisasi dan menggunakan status autentikasi yang diteruskan oleh server. Status autentikasi ditetapkan untuk masa hidup aplikasi WebAssembly.

Kelas PersistingAuthenticationStateProvider (PersistingAuthenticationStateProvider.cs) adalah sisi AuthenticationStateProvider server yang menggunakan PersistentComponentState untuk mengalirkan status autentikasi ke klien, yang kemudian diperbaiki selama masa pakai aplikasi WebAssembly.

Untuk informasi selengkapnya tentang panggilan API (web) menggunakan abstraksi layanan, Blazor Web Applihat Memanggil API web dari aplikasi ASP.NET CoreBlazor.

Pendaftaran aplikasi ID Microsoft Entra

Sebaiknya gunakan pendaftaran terpisah untuk aplikasi dan API web, bahkan ketika aplikasi dan API web berada dalam solusi yang sama. Panduan berikut ini adalah untuk BlazorWebAppOidc aplikasi dan MinimalApiJwt API web dari contoh solusi, tetapi panduan yang sama umumnya berlaku untuk pendaftaran berbasis Entra untuk aplikasi dan API web.

Daftarkan API web (MinimalApiJwt) terlebih dahulu sehingga Anda kemudian dapat memberikan akses ke API web saat mendaftarkan aplikasi. ID penyewa dan ID klien API web digunakan untuk mengonfigurasi API web di dalam file Program. Setelah mendaftarkan API web, ekspos API web di Pendaftaran aplikasi>Mengekspos API dengan nama cakupan Weather.Get. Rekam URI ID Aplikasi untuk digunakan dalam konfigurasi aplikasi.

Selanjutnya, daftarkan aplikasi (BlazorWebAppOidc/BlazorWebApOidc.Client) dengan konfigurasi platform Web dan URI Pengalihan (port tidak diperlukan). ID penyewa dan ID klien aplikasi, bersama dengan alamat dasar API web, URI ID Aplikasi, dan nama cakupan cuaca, berfungsi untuk mengonfigurasi aplikasi dalam file Program. Berikan izin API untuk mengakses API web di Pendaftaran aplikasi>Izin API. Jika spesifikasi keamanan aplikasi memanggilnya, Anda dapat memberikan persetujuan admin bagi organisasi untuk mengakses API web. Pengguna dan grup yang berwenang ditetapkan ke dalam Pendaftaran Aplikasi>Aplikasi Enterprise.

Di konfigurasi pendaftaran aplikasi pemberian implisit dan alur hibrid pada portal Entra atau Azure, jangan pilih kotak centang mana pun untuk titik akhir otorisasi untuk mengembalikan token Akses atau token ID. Handler OpenID Connect secara otomatis meminta token yang sesuai menggunakan kode yang dikembalikan dari titik akhir otorisasi.

Buat rahasia klien di pendaftaran aplikasi di portal Entra atau Microsoft Azure (Kelola>Sertifikat & rahasia>Rahasia klien baru). Simpan rahasia klien Value untuk digunakan pada bagian berikutnya.

Panduan konfigurasi Entra tambahan untuk pengaturan tertentu disediakan nanti di artikel ini.

Menetapkan rahasia klien

Bagian ini hanya berlaku untuk proyek server dari Blazor Web App (BlazorWebAppOidc proyek).

Peringatan

Jangan menyimpan rahasia aplikasi, string koneksi, kredensial, kata sandi, nomor identifikasi pribadi (PIN), kode C#/.NET privat, atau kunci/token privat dalam kode sisi klien, yang selalu tidak aman. Di lingkungan pengujian/penahapan dan produksi, kode sisi Blazor server dan API web harus menggunakan alur autentikasi aman yang menghindari mempertahankan kredensial dalam kode proyek atau file konfigurasi. Di luar pengujian pengembangan lokal, sebaiknya hindari penggunaan variabel lingkungan untuk menyimpan data sensitif, karena variabel lingkungan bukanlah pendekatan yang paling aman. Untuk pengujian pengembangan lokal, alat Secret Manager direkomendasikan untuk mengamankan data sensitif. Untuk informasi selengkapnya, lihat Mempertahankan data dan kredensial sensitif dengan aman.

Untuk pengujian pengembangan lokal, gunakan alat Secret Manager untuk menyimpan rahasia klien proyek server dengan kunci konfigurasi Blazor.

Proyek Blazor server belum diinisialisasi untuk alat Secret Manager. Gunakan shell perintah, seperti shell perintah Developer PowerShell di Visual Studio, untuk menjalankan perintah berikut. Sebelum menjalankan perintah, ubah direktori dengan cd perintah ke direktori proyek server. Perintah menetapkan pengidentifikasi rahasia pengguna (<UserSecretsId> dalam file proyek aplikasi server):

dotnet user-secrets init

Jalankan perintah berikut untuk mengatur rahasia klien. Placeholder {SECRET} adalah rahasia klien yang diperoleh dari registrasi aplikasi.

dotnet user-secrets set "Authentication:Schemes:MicrosoftOidc:ClientSecret" "{SECRET}"

Jika menggunakan Visual Studio, Anda dapat mengonfirmasi rahasia diatur dengan mengklik kanan proyek server di "Penjelajah Solusi" dan memilih "Kelola Rahasia Pengguna".

`MinimalApiJwt` proyek

Proyek MinimalApiJwt ini adalah API web backend untuk beberapa proyek frontend. Proyek mengonfigurasi titik akhir API Minimal untuk data cuaca.

File MinimalApiJwt.http dapat digunakan untuk menguji permintaan data cuaca. Perhatikan bahwa MinimalApiJwt proyek harus berjalan untuk menguji titik akhir, dan titik akhir dikodekan secara permanen ke dalam file. Untuk informasi selengkapnya, lihat Menggunakan file .http di Visual Studio 2022.

Proyek ini mencakup paket dan konfigurasi untuk menghasilkan dokumen OpenAPI dan UI Swagger di lingkungan Pengembangan. Untuk informasi selengkapnya, lihat Menggunakan dokumen OpenAPI yang dihasilkan.

Proyek ini membuat titik akhir API Minimal untuk data cuaca:

app.MapGet("/weather-forecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
}).RequireAuthorization();

Konfigurasikan proyek pada panggilan JwtBearerOptions dari AddJwtBearer dalam file Program proyek.

Menetapkan Otoritas Authority untuk melakukan panggilan OIDC. Sebaiknya gunakan pendaftaran aplikasi terpisah untuk proyek.MinimalApiJwt Otoritas cocok dengan issurer (iss) JWT yang dikembalikan oleh Penyedia Identitas.

jwtOptions.Authority = "{AUTHORITY}";

Format dari Otoritas bergantung pada tipe penyewa yang digunakan. Contoh berikut untuk Microsoft Entra ID menggunakan Tenant ID aaaabbbb-0000-cccc-1111-dddd2222eeee.

contoh Otoritas penyewa ME-ID:

jwtOptions.Authority = "https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/";

Contoh Otoritas penyewa AAD B2C:

jwtOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/";

Menetapkan Audiens untuk token OIDC yang diterima.

jwtOptions.Audience = "{APP ID URI}";

Catatan

Saat menggunakan Microsoft Entra ID, sesuaikan nilai hanya dengan jalur URI ID Aplikasi yang dikonfigurasi saat menambahkan Weather.Get ruang lingkup di bawah Mengekspos API di portal Entra atau Azure. Jangan sertakan nama cakupan, "Weather.Get," dalam nilai .

Format Audiens bergantung pada jenis penyewa yang digunakan. Contoh berikut untuk ID Microsoft Entra menggunakan ID contoso Penyewa dan ID Klien .11112222-bbbb-3333-cccc-4444dddd5555

contoh URI ID Aplikasi penyewa ME-ID:

jwtOptions.Audience = "api://11112222-bbbb-3333-cccc-4444dddd5555";

Contoh URI ID Aplikasi penyewa AAD B2C:

jwtOptions.Audience = "https://contoso.onmicrosoft.com/11112222-bbbb-3333-cccc-4444dddd5555";

Blazor Web App proyek server (`BlazorWebAppOidc`)

Proyek BlazorWebAppOidc ini adalah proyek sisi server dari Blazor Web App.

DelegatingHandler (TokenHandler) mengelola proses melampirkan token akses pengguna ke permintaan keluar. Handler token hanya dijalankan selama penyajian sisi server statis (SSR statis), jadi penggunaan HttpContext aman dalam skenario ini. Untuk informasi selengkapnya, lihat IHttpContextAccessor/HttpContext di aplikasi ASP.NET Core Blazor dan Blazor Web App.

TokenHandler.cs:

public class TokenHandler(IHttpContextAccessor httpContextAccessor) : 
    DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        if (httpContextAccessor.HttpContext is null)
        {
            throw new Exception("HttpContext not available");
        }

        var accessToken = await httpContextAccessor.HttpContext
            .GetTokenAsync("access_token");

        request.Headers.Authorization =
            new AuthenticationHeaderValue("Bearer", accessToken);

        return await base.SendAsync(request, cancellationToken);
    }
}

Dalam file proyek Program , handler token (TokenHandler) terdaftar sebagai layanan dan ditentukan sebagai handler pesan dengan AddHttpMessageHandler untuk membuat permintaan aman ke API web backend MinimalApiJwt menggunakan klien HTTP bernama ("ExternalApi").

builder.Services.AddScoped<TokenHandler>();

builder.Services.AddHttpClient("ExternalApi",
      client => client.BaseAddress = new Uri(builder.Configuration["ExternalApiUri"] ?? 
          throw new Exception("Missing base address!")))
      .AddHttpMessageHandler<TokenHandler>();

Dalam file proyek appsettings.json , konfigurasikan URI API eksternal:

"ExternalApiUri": "{BASE ADDRESS}"

Contoh:

"ExternalApiUri": "https://localhost:7277"

Konfigurasi berikut OpenIdConnectOptions ditemukan dalam file proyek Program pada panggilan ke AddOpenIdConnect:

PushedAuthorizationBehavior: Mengontrol dukungan Permintaan Otorisasi yang Didorong (PAR). Secara bawaan, pengaturannya adalah menggunakan PAR jika dokumen penemuan penyedia identitas (biasanya ditemukan di .well-known/openid-configuration) menyatakan dukungan untuk PAR. Jika Anda ingin memerlukan dukungan PAR untuk aplikasi, Anda dapat menetapkan nilai PushedAuthorizationBehavior.Require. PAR tidak didukung oleh Microsoft Entra, dan tidak ada rencana bagi Entra untuk mendukungnya di masa mendatang.

oidcOptions.PushedAuthorizationBehavior = PushedAuthorizationBehavior.UseIfAvailable;

SignInScheme: Mengatur skema autentikasi yang sesuai dengan middleware yang bertanggung jawab untuk mempertahankan identitas pengguna setelah autentikasi berhasil. Handler OIDC perlu menggunakan skema masuk yang mampu mempertahankan kredensial pengguna di seluruh permintaan. Baris berikut hadir hanya untuk tujuan demonstrasi. Jika dihilangkan, DefaultSignInScheme digunakan sebagai nilai fallback.

oidcOptions.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;

Cakupan untuk openid dan profile (Scope) (Opsional): Cakupan openid dan profile juga dikonfigurasi secara default karena diperlukan agar handler OIDC berfungsi, tetapi ini mungkin perlu ditambahkan kembali jika cakupan disertakan dalam Authentication:Schemes:MicrosoftOidc:Scope konfigurasi. Untuk panduan konfigurasi umum, lihat Konfigurasi di ASP.NET Core dan konfigurasi ASP.NET Core Blazor.

oidcOptions.Scope.Add(OpenIdConnectScope.OpenIdProfile);

SaveTokens: Menentukan apakah akses dan token refresh harus disimpan di AuthenticationProperties setelah otorisasi berhasil. Properti ini diatur ke true agar token refresh disimpan dan dapat disegarkan secara non-interaktif.

oidcOptions.SaveTokens = true;

Cakupan untuk akses offline (Scope): Cakupan offline_access diperlukan untuk token pembaruan.

oidcOptions.Scope.Add(OpenIdConnectScope.OfflineAccess);

Authority dan ClientId: Mengatur Otoritas dan ID Klien untuk panggilan OIDC.

oidcOptions.Authority = "{AUTHORITY}";
oidcOptions.ClientId = "{CLIENT ID}";

Contoh berikut menggunakan ID aaaabbbb-0000-cccc-1111-dddd2222eeee Penyewa dan ID Klien dari 00001111-aaaa-2222-bbbb-3333cccc4444:

oidcOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/";
oidcOptions.ClientId = "00001111-aaaa-2222-bbbb-3333cccc4444";

Untuk aplikasi multi-penyewa, wewenang "umum" harus digunakan. Anda juga dapat menggunakan otoritas "umum" untuk aplikasi penyewa tunggal, tetapi sebuah varian kustom IssuerValidator diperlukan, seperti yang ditunjukkan nanti di bagian ini.

oidcOptions.Authority = "https://login.microsoftonline.com/common/v2.0/";

ResponseType: Mengonfigurasi handler OIDC untuk hanya melakukan alur kode otorisasi. Pemberian implisit dan aliran hibrid tidak perlu dalam mode ini. Handler OIDC secara otomatis meminta token yang sesuai menggunakan kode yang dikembalikan dari titik akhir otorisasi.

oidcOptions.ResponseType = OpenIdConnectResponseType.Code;

MapInboundClaims dan konfigurasi NameClaimType dan RoleClaimType: Banyak server OIDC menggunakan "name" dan "role" daripada pengaturan default SOAP/WS-Fed di ClaimTypes. Ketika MapInboundClaims diatur ke false, handler tidak melakukan pemetaan klaim, dan nama klaim dari JWT digunakan langsung oleh aplikasi. Contoh berikut mengatur jenis klaim peran ke "roles," yang sesuai untuk ID Microsoft Entra (ME-ID). Lihat dokumentasi penyedia identitas Anda untuk informasi selengkapnya.

Catatan

MapInboundClaims harus diatur ke false untuk sebagian besar penyedia OIDC, yang mencegah penggantian nama klaim.

oidcOptions.MapInboundClaims = false;
oidcOptions.TokenValidationParameters.NameClaimType = "name";
oidcOptions.TokenValidationParameters.RoleClaimType = "roles";

Konfigurasi jalur: Jalur harus cocok dengan jalur URI pengalihan (jalur panggilan balik masuk) dan pengalihan pasca keluar (jalur panggilan balik keluar) yang dikonfigurasi saat mendaftarkan aplikasi dengan penyedia OIDC. Di portal Microsoft Azure, jalur dikonfigurasi di bilah Autentikasi pendaftaran aplikasi. Jalur masuk dan keluar harus didaftarkan sebagai URI pengalihan. Nilai defaultnya adalah /signin-oidc dan /signout-callback-oidc.

CallbackPath: Jalur permintaan dalam jalur dasar aplikasi di mana user-agent dikembalikan.

Konfigurasikan jalur panggilan balik saat logout di pendaftaran penyedia OIDC aplikasi. Dalam contoh berikut, placeholder {PORT} adalah port aplikasi:

https://localhost:{PORT}/signin-oidc

Catatan

Port tidak diperlukan untuk alamat localhost saat menggunakan Microsoft Entra ID. Sebagian besar penyedia OIDC lainnya memerlukan port yang benar.

SignedOutCallbackPath (kunci konfigurasi: "SignedOutCallbackPath"): Jalur permintaan dalam path dasar aplikasi yang dicegat oleh handler OIDC tempat agen pengguna pertama kali dikembalikan setelah keluar dari penyedia identitas. Aplikasi sampel tidak menetapkan nilai untuk jalur karena nilai default "/signout-callback-oidc" digunakan. Setelah mencegat permintaan, handler OIDC mengalihkan ke SignedOutRedirectUri atau RedirectUri, jika ditentukan.

Konfigurasikan jalur panggilan balik saat logout di pendaftaran penyedia OIDC aplikasi. Dalam contoh berikut, placeholder {PORT} adalah port aplikasi:

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

Catatan

Saat menggunakan ID Microsoft Entra, atur jalur dalam entri URI Pengalihan konfigurasi platform Web 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 pengembalian panggilan setelah logout ke pendaftaran aplikasi di Entra, Entra tidak akan mengalihkan pengguna kembali ke aplikasi dan hanya meminta untuk menutup jendela browser.

RemoteSignOutPath: Permintaan yang diterima pada jalur ini menyebabkan handler melakukan log-out menggunakan skema log-out.

Dalam contoh berikut, placeholder {PORT} adalah port aplikasi:

https://localhost/signout-oidc

Catatan

Saat menggunakan Microsoft Entra ID, atur URL keluar saluran depan di portal Entra atau Azure. Port tidak diperlukan untuk alamat localhost saat menggunakan Entra. Sebagian besar penyedia OIDC lainnya memerlukan port yang benar.

oidcOptions.CallbackPath = new PathString("{PATH}");
oidcOptions.SignedOutCallbackPath = new PathString("{PATH}");
oidcOptions.RemoteSignOutPath = new PathString("{PATH}");

Contoh (nilai default):

oidcOptions.CallbackPath = new PathString("/signin-oidc");
oidcOptions.SignedOutCallbackPath = new PathString("/signout-callback-oidc");
oidcOptions.RemoteSignOutPath = new PathString("/signout-oidc");

(Microsoft Azure hanya dengan titik akhir "umum") TokenValidationParameters.IssuerValidator: Banyak penyedia OIDC bekerja dengan validator penerbit default, tetapi kita perlu mengakomodasi penerbit yang diparameterkan dengan ID Penyewa ({TENANT ID}) yang dikembalikan oleh https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Untuk informasi selengkapnya, lihat SecurityTokenInvalidIssuerException dengan OpenID Connect dan titik akhir "umum" Microsoft Azure AD (AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet #1731).

Hanya untuk aplikasi yang menggunakan Microsoft Entra ID atau Azure AD B2C dengan titik akhir "umum":

var microsoftIssuerValidator = AadIssuerValidator.GetAadIssuerValidator(oidcOptions.Authority);
oidcOptions.TokenValidationParameters.IssuerValidator = microsoftIssuerValidator.Validate;

Blazor Web App proyek klien (`BlazorWebAppOidc.Client`)

Proyek BlazorWebAppOidc.Client ini adalah proyek sisi klien dari Blazor Web App.

Klien memanggil fungsi AddAuthenticationStateDeserialization untuk mendeserialisasi dan menggunakan status autentikasi yang diteruskan oleh server. Status autentikasi ditetapkan untuk masa hidup aplikasi WebAssembly.

Kelas PersistentAuthenticationStateProvider (PersistentAuthenticationStateProvider.cs) adalah sisi AuthenticationStateProvider klien yang menentukan status autentikasi pengguna dengan mencari data yang bertahan di halaman ketika dirender di server. Status autentikasi ditetapkan untuk masa hidup aplikasi WebAssembly.

Jika pengguna perlu masuk atau keluar, diperlukan pemuatan ulang halaman lengkap.

Aplikasi sampel hanya menyediakan nama pengguna dan email untuk tujuan tampilan.

Versi artikel ini mencakup penerapan OIDC tanpa mengadopsi pola Backend for Frontend (BFF) dengan aplikasi yang mengadopsi penyajian Server Interaktif global (proyek tunggal). Pola BFF berguna untuk membuat permintaan terautentikasi ke layanan eksternal. Ubah pemilih versi artikel menjadi pola BFF jika spesifikasi aplikasi memanggil untuk mengadopsi pola BFF dengan penyajian Otomatis Interaktif global.

Spesifikasi berikut diadopsi:

Blazor Web App menggunakan mode penyajian Server dengan interaktivitas global.
Aplikasi ini adalah titik awal untuk alur autentikasi OIDC apa pun. OIDC dikonfigurasi secara manual di aplikasi dan tidak mengandalkan ID Microsoft Entra atau paket Web MicrosoftIdentity, aplikasi sampel juga tidak memerlukan hosting Microsoft Azure. Namun, aplikasi sampel dapat digunakan dengan Entra, Microsoft Identity Web, dan dihosting di Azure.
Pembaruan token otomatis tanpa interaksi.
Proyek API web terpisah menunjukkan panggilan API web yang aman untuk data cuaca.

Contoh solusi

Aplikasi sampel terdiri dari proyek berikut:

BlazorWebAppOidcServer: Blazor Web App proyek sisi server (penyajian Server Interaktif global).
MinimalApiJwt: API backend web dengan endpoint Minimal API untuk data cuaca.

Akses sampel melalui folder versi terbaru di repositori sampel Blazor dengan tautan berikut. Sampel berada di folder BlazorWebAppOidcServer untuk .NET 8 atau yang lebih baru.

Menampilkan atau mengunduh kode sampel (cara mengunduh)

Pendaftaran aplikasi ID Microsoft Entra

Sebaiknya gunakan pendaftaran terpisah untuk aplikasi dan API web, bahkan ketika aplikasi dan API web berada dalam solusi yang sama. Panduan berikut ini adalah untuk BlazorWebAppOidcServer aplikasi dan MinimalApiJwt API web dari contoh solusi, tetapi panduan yang sama umumnya berlaku untuk pendaftaran berbasis Entra untuk aplikasi dan API web.

Selanjutnya, daftarkan aplikasi (BlazorWebAppOidcServer) dengan konfigurasi platform Web dan URI Pengalihanhttps://localhost/signin-oidc (port tidak diperlukan). ID penyewa dan ID klien aplikasi, bersama dengan alamat dasar API web, URI ID Aplikasi, dan nama cakupan cuaca, berfungsi untuk mengonfigurasi aplikasi dalam file Program. Berikan izin API untuk mengakses API web di Pendaftaran aplikasi>Izin API. Jika spesifikasi keamanan aplikasi memanggilnya, Anda dapat memberikan persetujuan admin bagi organisasi untuk mengakses API web. Pengguna dan grup yang berwenang ditetapkan ke dalam Pendaftaran Aplikasi>Aplikasi Enterprise.

Panduan konfigurasi Entra tambahan untuk pengaturan tertentu disediakan nanti di artikel ini.

Menetapkan rahasia klien

Bagian ini hanya berlaku untuk proyek server dari Blazor Web App (BlazorWebAppOidcServer proyek).

Peringatan

Untuk pengujian pengembangan lokal, gunakan alat Secret Manager untuk menyimpan rahasia klien proyek server dengan kunci konfigurasi Blazor.

dotnet user-secrets init

Jalankan perintah berikut untuk mengatur rahasia klien. Placeholder {SECRET} adalah rahasia klien yang diperoleh dari registrasi aplikasi.

dotnet user-secrets set "Authentication:Schemes:MicrosoftOidc:ClientSecret" "{SECRET}"

Jika menggunakan Visual Studio, Anda dapat mengonfirmasi rahasia diatur dengan mengklik kanan proyek di Penjelajah Solusi dan memilih Kelola Rahasia Pengguna.

`MinimalApiJwt` proyek

Proyek MinimalApiJwt ini adalah API web backend untuk beberapa proyek frontend. Proyek mengonfigurasi titik akhir API Minimal untuk data cuaca.

Proyek ini membuat titik akhir API Minimal untuk data cuaca:

app.MapGet("/weather-forecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
}).RequireAuthorization();

Konfigurasikan proyek pada panggilan JwtBearerOptions dari AddJwtBearer dalam file Program proyek.

jwtOptions.Authority = "{AUTHORITY}";

Format dari Otoritas bergantung pada tipe penyewa yang digunakan. Contoh berikut untuk Microsoft Entra ID menggunakan Tenant ID aaaabbbb-0000-cccc-1111-dddd2222eeee.

contoh Otoritas penyewa ME-ID:

jwtOptions.Authority = "https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/";

Contoh Otoritas penyewa AAD B2C:

jwtOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/";

Menetapkan Audiens untuk token OIDC yang diterima.

jwtOptions.Audience = "{APP ID URI}";

Catatan

Format Audiens bergantung pada jenis penyewa yang digunakan. Contoh berikut untuk ID Microsoft Entra menggunakan ID contoso Penyewa dan ID Klien .11112222-bbbb-3333-cccc-4444dddd5555

contoh URI ID Aplikasi penyewa ME-ID:

jwtOptions.Audience = "api://11112222-bbbb-3333-cccc-4444dddd5555";

Contoh URI ID Aplikasi penyewa AAD B2C:

jwtOptions.Audience = "https://contoso.onmicrosoft.com/11112222-bbbb-3333-cccc-4444dddd5555";

`BlazorWebAppOidcServer` proyek

Pembaharuan token non-interaktif otomatis dikelola dengan penyegar khusus cookie (CookieOidcRefresher.cs).

TokenHandler.cs:

public class TokenHandler(IHttpContextAccessor httpContextAccessor) : 
    DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        if (httpContextAccessor.HttpContext is null)
        {
            throw new Exception("HttpContext not available");
        }

        var accessToken = await httpContextAccessor.HttpContext
            .GetTokenAsync("access_token");

        request.Headers.Authorization =
            new AuthenticationHeaderValue("Bearer", accessToken);

        return await base.SendAsync(request, cancellationToken);
    }
}

builder.Services.AddScoped<TokenHandler>();

builder.Services.AddHttpClient("ExternalApi",
      client => client.BaseAddress = new Uri(builder.Configuration["ExternalApiUri"] ?? 
          throw new Exception("Missing base address!")))
      .AddHttpMessageHandler<TokenHandler>();

Komponen Weather menggunakan [Authorize] atribut untuk mencegah akses yang tidak sah. Untuk informasi selengkapnya tentang memerlukan otorisasi di seluruh aplikasi melalui kebijakan otorisasi dan menolak otorisasi pada subset titik akhir publik, lihat Razor panduan Pages OIDC.

Klien ExternalApi HTTP digunakan untuk membuat permintaan data cuaca ke API web yang aman. OnInitializedAsync Dalam peristiwa siklus hidup :Weather.razor

using var request = new HttpRequestMessage(HttpMethod.Get, "/weather-forecast");
var client = ClientFactory.CreateClient("ExternalApi");
using var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();

forecasts = await response.Content.ReadFromJsonAsync<WeatherForecast[]>() ??
    throw new IOException("No weather forecast!");

Dalam file proyek appsettings.json , konfigurasikan URI API eksternal:

"ExternalApiUri": "{BASE ADDRESS}"

Contoh:

"ExternalApiUri": "https://localhost:7277"

Konfigurasi berikut OpenIdConnectOptions ditemukan dalam file proyek Program pada panggilan ke AddOpenIdConnect:

oidcOptions.PushedAuthorizationBehavior = PushedAuthorizationBehavior.UseIfAvailable;

oidcOptions.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;

oidcOptions.Scope.Add(OpenIdConnectScope.OpenIdProfile);

Konfigurasikan Weather.Get cakupan untuk mengakses API web eksternal untuk data cuaca. Contoh berikut didasarkan pada penggunaan ID Entra di domain penyewa ME-ID. Dalam contoh berikut, placeholder {APP ID URI} ditemukan di portal Entra atau Azure di mana API web diekspos. Untuk penyedia identitas lainnya, gunakan ruang lingkup yang sesuai.

oidcOptions.Scope.Add("{APP ID URI}/Weather.Get");

Format cakupan tergantung pada jenis penyewa yang digunakan. Dalam contoh berikut, Domain Penyewa adalah contoso.onmicrosoft.com, dan ID Klien adalah 11112222-bbbb-3333-cccc-4444dddd5555.

contoh URI ID Aplikasi penyewa ME-ID:

oidcOptions.Scope.Add("api://11112222-bbbb-3333-cccc-4444dddd5555/Weather.Get");

Contoh URI ID Aplikasi penyewa AAD B2C:

oidcOptions.Scope.Add("https://contoso.onmicrosoft.com/11112222-bbbb-3333-cccc-4444dddd5555/Weather.Get");

oidcOptions.SaveTokens = true;

Cakupan untuk akses offline (Scope): Cakupan offline_access diperlukan untuk token pembaruan.

oidcOptions.Scope.Add(OpenIdConnectScope.OfflineAccess);

Authority dan ClientId: Mengatur Otoritas dan ID Klien untuk panggilan OIDC.

oidcOptions.Authority = "{AUTHORITY}";
oidcOptions.ClientId = "{CLIENT ID}";

Contoh berikut menggunakan ID aaaabbbb-0000-cccc-1111-dddd2222eeee Penyewa dan ID Klien dari 00001111-aaaa-2222-bbbb-3333cccc4444:

oidcOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/";
oidcOptions.ClientId = "00001111-aaaa-2222-bbbb-3333cccc4444";

oidcOptions.Authority = "https://login.microsoftonline.com/common/v2.0/";

oidcOptions.ResponseType = OpenIdConnectResponseType.Code;

Catatan

MapInboundClaims harus diatur ke false untuk sebagian besar penyedia OIDC, yang mencegah penggantian nama klaim.

oidcOptions.MapInboundClaims = false;
oidcOptions.TokenValidationParameters.NameClaimType = "name";
oidcOptions.TokenValidationParameters.RoleClaimType = "roles";

CallbackPath: Jalur permintaan dalam jalur dasar aplikasi di mana user-agent dikembalikan.

Konfigurasikan jalur panggilan balik saat logout di pendaftaran penyedia OIDC aplikasi. Dalam contoh berikut, placeholder {PORT} adalah port aplikasi:

https://localhost:{PORT}/signin-oidc

Catatan

Port tidak diperlukan untuk alamat localhost saat menggunakan Microsoft Entra ID. Sebagian besar penyedia OIDC lainnya memerlukan port yang benar.

Konfigurasikan jalur panggilan balik saat logout di pendaftaran penyedia OIDC aplikasi. Dalam contoh berikut, placeholder {PORT} adalah port aplikasi:

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

Catatan

RemoteSignOutPath: Permintaan yang diterima pada jalur ini menyebabkan handler melakukan log-out menggunakan skema log-out.

Dalam contoh berikut, placeholder {PORT} adalah port aplikasi:

https://localhost/signout-oidc

Catatan

oidcOptions.CallbackPath = new PathString("{PATH}");
oidcOptions.SignedOutCallbackPath = new PathString("{PATH}");
oidcOptions.RemoteSignOutPath = new PathString("{PATH}");

Contoh (nilai default):

oidcOptions.CallbackPath = new PathString("/signin-oidc");
oidcOptions.SignedOutCallbackPath = new PathString("/signout-callback-oidc");
oidcOptions.RemoteSignOutPath = new PathString("/signout-oidc");

Hanya untuk aplikasi yang menggunakan Microsoft Entra ID atau Azure AD B2C dengan titik akhir "umum":

var microsoftIssuerValidator = AadIssuerValidator.GetAadIssuerValidator(oidcOptions.Authority);
oidcOptions.TokenValidationParameters.IssuerValidator = microsoftIssuerValidator.Validate;

Versi artikel ini mencakup penerapan OIDC dengan pola Backend for Frontend (BFF). Jika spesifikasi aplikasi tidak memanggil untuk mengadopsi pola BFF, ubah pemilih versi artikel menjadi pola Non-BFF (Interactive Auto) (Penyajian Otomatis Interaktif) atau pola Non-BFF (Server Interaktif) (Penyajian Server Interaktif).

Prasyarat

.NET Aspire memerlukan Visual Studio versi 17.10 atau yang lebih baru.

Selain itu, lihat bagian Prasyarat di Panduan cepat: Bangun aplikasi .NET Aspire pertama Anda.

Contoh solusi

Aplikasi sampel terdiri dari proyek berikut:

.NET Aspire:
- Aspire.AppHost: Digunakan untuk mengelola masalah orkestrasi tingkat tinggi aplikasi.
- Aspire.ServiceDefaults: Berisi konfigurasi aplikasi default .NET Aspire yang dapat diperluas dan disesuaikan sesuai kebutuhan.
MinimalApiJwt: API web backend, berisi contoh titik akhir API Minimal untuk data cuaca.
BlazorWebAppOidc: Proyek sisi server dari Blazor Web App. Proyek ini menggunakan YARP untuk memproksi permintaan ke titik akhir prakiraan cuaca di proyek API web backend (MinimalApiJwt) dengan access_token yang disimpan dalam autentikasi cookie.
BlazorWebAppOidc.Client: Proyek pihak klien dari Blazor Web App.

Akses sampel melalui folder versi terbaru di repositori sampel Blazor dengan tautan berikut. Sampel berada di folder BlazorWebAppOidcBff untuk .NET 8 atau yang lebih baru.

Menampilkan atau mengunduh kode sampel (cara mengunduh)

Blazor Web App menggunakan mode Render otomatis dengan interaktivitas global.

Proyek server memanggil AddAuthenticationStateSerialization untuk menambahkan penyedia status autentikasi sisi server yang menggunakan PersistentComponentState untuk mengalirkan status autentikasi ke klien. Klien memanggil fungsi AddAuthenticationStateDeserialization untuk mendeserialisasi dan menggunakan status autentikasi yang diteruskan oleh server. Status autentikasi ditetapkan untuk masa hidup aplikasi WebAssembly.

Kelas PersistingAuthenticationStateProvider (PersistingAuthenticationStateProvider.cs) adalah sisi AuthenticationStateProvider server yang menggunakan PersistentComponentState untuk mengalirkan status autentikasi ke klien, yang kemudian diperbaiki selama masa pakai aplikasi WebAssembly.

Aplikasi ini adalah titik awal untuk alur autentikasi OIDC apa pun. OIDC dikonfigurasi secara manual di aplikasi dan tidak mengandalkan ID Microsoft Entra atau paket Web MicrosoftIdentity, aplikasi sampel juga tidak memerlukan hosting Microsoft Azure. Namun, aplikasi sampel dapat digunakan dengan Entra, Microsoft Identity Web, dan dihosting di Azure.

Pembaharuan token non-interaktif otomatis dengan bantuan pemulihan kustom cookie (CookieOidcRefresher.cs).

Pola Backend for Frontend (BFF) diadopsi menggunakan .NET Aspire untuk penemuan layanan dan YARP untuk memproksi permintaan ke endpoint prakiraan cuaca pada aplikasi backend.

API web backend (MinimalApiJwt) menggunakan autentikasi pembawa JWT untuk memvalidasi token JWT yang disimpan oleh Blazor Web App dalam sesi masuk cookie.

Aspire meningkatkan pengalaman membangun aplikasi cloud-native .NET. Ini menyediakan serangkaian alat dan pola yang konsisten dan terarah untuk membangun dan menjalankan aplikasi terdistribusi.

YARP (Yet Another Reverse Proxy) adalah pustaka yang digunakan untuk membuat server proksi terbalik. MapForwarder Program dalam file proyek server menambahkan penerusan langsung permintaan HTTP yang cocok dengan pola yang ditentukan ke tujuan tertentu menggunakan konfigurasi default untuk permintaan keluar, transformasi yang disesuaikan, dan klien HTTP default:

Saat merender komponen Weather di server, komponen menggunakan kelas ServerWeatherForecaster untuk mem-proxy permintaan data cuaca dengan token akses pengguna. IHttpContextAccessor.HttpContext menentukan apakah HttpContext tersedia untuk digunakan oleh metode GetWeatherForecastAsync. Untuk informasi selengkapnya, lihat komponen ASP.NET CoreRazor.
Ketika komponen dirender pada klien, komponen menggunakan implementasi layanan ClientWeatherForecaster, yang memanfaatkan HttpClient yang sudah dikonfigurasi sebelumnya (di dalam file Program proyek klien) untuk melakukan panggilan API web ke proyek server. Titik akhir API Minimal (/weather-forecast) yang ditentukan dalam file proyek Program server mengubah permintaan dengan token akses pengguna untuk mendapatkan data cuaca.

Untuk informasi selengkapnya tentang .NET Aspire, lihat Ketersediaan .NET AspireUmum : Menyederhanakan Pengembangan Cloud-Native .NET (Mei 2024).

Untuk informasi selengkapnya tentang panggilan API (web) menggunakan abstraksi layanan, Blazor Web Applihat Memanggil API web dari aplikasi ASP.NET CoreBlazor.

Pendaftaran aplikasi ID Microsoft Entra

Panduan konfigurasi Entra tambahan untuk pengaturan tertentu disediakan nanti di artikel ini.

Menetapkan rahasia klien

Bagian ini hanya berlaku untuk proyek server dari Blazor Web App (BlazorWebAppOidc proyek).

Peringatan

Untuk pengujian pengembangan lokal, gunakan alat Secret Manager untuk menyimpan rahasia klien proyek server dengan kunci konfigurasi Blazor.

dotnet user-secrets init

Jalankan perintah berikut untuk mengatur rahasia klien. Placeholder {SECRET} adalah rahasia klien yang diperoleh dari registrasi aplikasi.

dotnet user-secrets set "Authentication:Schemes:MicrosoftOidc:ClientSecret" "{SECRET}"

Jika menggunakan Visual Studio, Anda dapat mengonfirmasi rahasia diatur dengan mengklik kanan proyek server di "Penjelajah Solusi" dan memilih "Kelola Rahasia Pengguna".

.NET Aspire Proyek

Untuk informasi selengkapnya tentang penggunaan .NET Aspire dan detail tentang proyek .AppHost dan aplikasi sampel .ServiceDefaults, lihat pada .NET Aspire dokumentasi.

Konfirmasikan bahwa Anda telah memenuhi prasyarat untuk .NET Aspire. Untuk informasi selengkapnya, lihat bagian Prasyarat dari Panduan Singkat: Buat aplikasi pertama .NET Aspire Anda.

Aplikasi sampel hanya mengonfigurasi profil peluncuran HTTP yang tidak aman (http) untuk digunakan selama pengujian pengembangan. Untuk informasi selengkapnya, termasuk contoh profil pengaturan peluncuran yang tidak aman dan aman, lihat Mengizinkan transportasi yang tidak aman dalam .NET Aspire (.NET Aspire dokumentasi).

`MinimalApiJwt` proyek

Proyek MinimalApiJwt ini adalah API web backend untuk beberapa proyek frontend. Proyek mengonfigurasi titik akhir API Minimal untuk data cuaca. Permintaan dari Blazor Web App proyek sisi server (BlazorWebAppOidc) diproksikan ke MinimalApiJwt proyek.

Titik akhir data prakiraan cuaca yang aman ada di file proyek Program :

app.MapGet("/weather-forecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
}).RequireAuthorization();

Metode RequireAuthorization ekstensi memerlukan otorisasi untuk definisi rute. Untuk pengontrol apa pun yang Anda tambahkan ke proyek, tambahkan [Authorize] atribut ke pengontrol atau tindakan.

Konfigurasikan proyek pada panggilan JwtBearerOptions dari AddJwtBearer dalam file Program proyek.

jwtOptions.Authority = "{AUTHORITY}";

Format dari Otoritas bergantung pada tipe penyewa yang digunakan. Contoh berikut untuk Microsoft Entra ID menggunakan Tenant ID aaaabbbb-0000-cccc-1111-dddd2222eeee.

contoh Otoritas penyewa ME-ID:

jwtOptions.Authority = "https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/";

Contoh Otoritas penyewa AAD B2C:

jwtOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/";

Menetapkan Audiens untuk token OIDC yang diterima.

jwtOptions.Audience = "{APP ID URI}";

Catatan

Format Audiens bergantung pada jenis penyewa yang digunakan. Contoh berikut untuk ID Microsoft Entra menggunakan ID contoso Penyewa dan ID Klien .11112222-bbbb-3333-cccc-4444dddd5555

contoh URI ID Aplikasi penyewa ME-ID:

jwtOptions.Audience = "api://11112222-bbbb-3333-cccc-4444dddd5555";

Contoh URI ID Aplikasi penyewa AAD B2C:

jwtOptions.Audience = "https://contoso.onmicrosoft.com/11112222-bbbb-3333-cccc-4444dddd5555";

Proyek sisi server Blazor Web App (`BlazorWebAppOidc`)

Bagian ini menjelaskan cara mengonfigurasi proyek sisi Blazor server.

Konfigurasi berikut OpenIdConnectOptions ditemukan dalam file proyek Program pada panggilan ke AddOpenIdConnect.

oidcOptions.PushedAuthorizationBehavior = PushedAuthorizationBehavior.UseIfAvailable;

oidcOptions.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;

oidcOptions.Scope.Add(OpenIdConnectScope.OpenIdProfile);

SaveTokens: Menentukan apakah akses dan token refresh harus disimpan di AuthenticationProperties setelah otorisasi berhasil. Nilai diatur ke true untuk mengautentikasi permintaan data cuaca dari proyek API web backend (MinimalApiJwt).

oidcOptions.SaveTokens = true;

Cakupan untuk akses offline (Scope): Cakupan offline_access diperlukan untuk token pembaruan.

oidcOptions.Scope.Add(OpenIdConnectScope.OfflineAccess);

Cakupan untuk mendapatkan data cuaca dari API web (Scope): Konfigurasikan Weather.Get cakupan untuk mengakses API web eksternal untuk data cuaca. Dalam contoh berikut, placeholder {APP ID URI} ditemukan di portal Entra atau Azure di mana API web diekspos. Untuk penyedia identitas lainnya, gunakan ruang lingkup yang sesuai.

oidcOptions.Scope.Add("{APP ID URI}/Weather.Get");

Format cakupan tergantung pada jenis penyewa yang digunakan. Dalam contoh berikut, Domain Penyewa adalah contoso.onmicrosoft.com, dan ID Klien adalah 11112222-bbbb-3333-cccc-4444dddd5555.

contoh URI ID Aplikasi penyewa ME-ID:

oidcOptions.Scope.Add("api://11112222-bbbb-3333-cccc-4444dddd5555/Weather.Get");

Contoh URI ID Aplikasi penyewa AAD B2C:

oidcOptions.Scope.Add("https://contoso.onmicrosoft.com/11112222-bbbb-3333-cccc-4444dddd5555/Weather.Get");

Authority dan ClientId: Mengatur Otoritas dan ID Klien untuk panggilan OIDC.

oidcOptions.Authority = "{AUTHORITY}";
oidcOptions.ClientId = "{CLIENT ID}";

Contoh berikut menggunakan ID aaaabbbb-0000-cccc-1111-dddd2222eeee Penyewa dan ID Klien dari 00001111-aaaa-2222-bbbb-3333cccc4444:

oidcOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/";
oidcOptions.ClientId = "00001111-aaaa-2222-bbbb-3333cccc4444";

oidcOptions.Authority = "https://login.microsoftonline.com/common/v2.0/";

oidcOptions.ResponseType = OpenIdConnectResponseType.Code;

MapInboundClaims dan konfigurasi NameClaimType dan RoleClaimType: Banyak server OIDC menggunakan "name" dan "role" daripada pengaturan default SOAP/WS-Fed di ClaimTypes. Ketika MapInboundClaims diatur ke false, handler tidak melakukan pemetaan klaim dan nama klaim dari JWT digunakan langsung oleh aplikasi. Contoh berikut mengatur jenis klaim peran ke "roles," yang sesuai untuk ID Microsoft Entra (ME-ID). Lihat dokumentasi penyedia identitas Anda untuk informasi selengkapnya.

Catatan

MapInboundClaims harus diatur ke false untuk sebagian besar penyedia OIDC, yang mencegah penggantian nama klaim.

oidcOptions.MapInboundClaims = false;
oidcOptions.TokenValidationParameters.NameClaimType = "name";
oidcOptions.TokenValidationParameters.RoleClaimType = "roles";

Konfigurasikan jalur panggilan balik saat logout di pendaftaran penyedia OIDC aplikasi. Dalam contoh berikut, placeholder {PORT} adalah port aplikasi:

https://localhost:{PORT}/signin-oidc

Catatan

Port tidak diperlukan untuk alamat localhost saat menggunakan Microsoft Entra ID. Sebagian besar penyedia OIDC lainnya memerlukan port yang benar.

Konfigurasikan jalur panggilan balik saat logout di pendaftaran penyedia OIDC aplikasi. Dalam contoh berikut, placeholder {PORT} adalah port aplikasi:

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

Catatan

RemoteSignOutPath: Permintaan yang diterima pada jalur ini menyebabkan handler melakukan log-out menggunakan skema log-out.

Dalam contoh berikut, placeholder {PORT} adalah port aplikasi:

https://localhost/signout-oidc

Catatan

oidcOptions.CallbackPath = new PathString("{PATH}");
oidcOptions.SignedOutCallbackPath = new PathString("{PATH}");
oidcOptions.RemoteSignOutPath = new PathString("{PATH}");

Contoh (nilai default):

oidcOptions.CallbackPath = new PathString("/signin-oidc");
oidcOptions.SignedOutCallbackPath = new PathString("/signout-callback-oidc");
oidcOptions.RemoteSignOutPath = new PathString("/signout-oidc");

Hanya untuk aplikasi yang menggunakan Microsoft Entra ID atau Azure AD B2C dengan titik akhir "umum":

var microsoftIssuerValidator = AadIssuerValidator.GetAadIssuerValidator(oidcOptions.Authority);
oidcOptions.TokenValidationParameters.IssuerValidator = microsoftIssuerValidator.Validate;

Proyek Blazor Web App sisi klien (`BlazorWebAppOidc.Client`)

Proyek BlazorWebAppOidc.Client ini adalah proyek sisi klien dari Blazor Web App.

Jika pengguna perlu masuk atau keluar, diperlukan pemuatan ulang halaman lengkap.

Aplikasi sampel hanya menyediakan nama pengguna dan email untuk tujuan tampilan.

Hanya melakukan serialisasi klaim nama dan klaim peran

Bagian ini hanya berlaku untuk pola non-BFF (Interactive Auto) dan pola BFF (Interactive Auto) dan aplikasi sampelnya.

Dalam file Program, setiap klaim dijadikan serial dengan mengatur SerializeAllClaims ke true. Jika Anda hanya ingin nama dan klaim peran diserialisasikan untuk CSR, hapus opsi tersebut atau atur ke false.

Pasok konfigurasi dengan penyedia konfigurasi JSON (pengaturan aplikasi)

Proyek solusi sampel mengonfigurasi autentikasi pembawa OIDC dan JWT dalam file Program mereka untuk membuat pengaturan konfigurasi mudah ditemukan menggunakan pelengkapan otomatis C#. Aplikasi profesional biasanya menggunakan penyedia konfigurasi untuk mengonfigurasi opsi OIDC, seperti penyedia konfigurasi JSON default. Penyedia konfigurasi JSON memuat konfigurasi dari file pengaturan aplikasi appsettings.json/appsettings.{ENVIRONMENT}.json, di mana {ENVIRONMENT} tempat penampung adalah lingkungan berjalan aplikasi. Ikuti panduan di bagian ini untuk menggunakan file pengaturan aplikasi untuk konfigurasi.

Dalam file pengaturan aplikasi (appsettings.json) dari BlazorWebAppOidc atau BlazorWebAppOidcServer proyek, tambahkan konfigurasi JSON berikut:

"Authentication": {
  "Schemes": {
    "MicrosoftOidc": {
      "Authority": "https://login.microsoftonline.com/{TENANT ID (BLAZOR APP)}/v2.0/",
      "ClientId": "{CLIENT ID (BLAZOR APP)}",
      "CallbackPath": "/signin-oidc",
      "SignedOutCallbackPath": "/signout-callback-oidc",
      "RemoteSignOutPath": "/signout-oidc",
      "SignedOutRedirectUri": "/",
      "Scope": [
        "openid",
        "profile",
        "offline_access",
        "{APP ID URI (WEB API)}/Weather.Get"
      ]
    }
  }
},

Perbarui tempat penampung dalam konfigurasi sebelumnya agar sesuai dengan nilai yang digunakan aplikasi dalam Program file:

{TENANT ID (BLAZOR APP)}: Id penyewa dari aplikasi Blazor.
{CLIENT ID (BLAZOR APP)}: Id Blazor Klien aplikasi.
{APP ID URI (WEB API)}: URI ID Aplikasi dari API web.

Otoritas "umum" (https://login.microsoftonline.com/common/v2.0/) harus digunakan untuk aplikasi multi-tenant. Untuk menggunakan Otoritas "umum" untuk aplikasi penyewa tunggal, lihat bagian Menggunakan Otoritas "umum" untuk aplikasi penyewa tunggal .

Perbarui nilai lain dalam konfigurasi sebelumnya agar sesuai dengan nilai kustom/non-default yang digunakan dalam file Program.

Konfigurasi secara otomatis diambil oleh pembuat autentikasi.

Hapus baris berikut dari Program file:

- oidcOptions.Scope.Add(OpenIdConnectScope.OpenIdProfile);
- oidcOptions.Scope.Add("...");
- oidcOptions.CallbackPath = new PathString("...");
- oidcOptions.SignedOutCallbackPath = new PathString("...");
- oidcOptions.RemoteSignOutPath = new PathString("...");
- oidcOptions.Authority = "...";
- oidcOptions.ClientId = "...";

ConfigureCookieOidc Dalam metode CookieOidcServiceCollectionExtensions.cs, hapus baris berikut:

- oidcOptions.Scope.Add(OpenIdConnectScope.OfflineAccess);

MinimalApiJwt Dalam proyek, tambahkan konfigurasi pengaturan aplikasi berikut ke appsettings.json file:

"Authentication": {
  "Schemes": {
    "Bearer": {
      "Authority": "https://sts.windows.net/{TENANT ID (WEB API)}/",
      "ValidAudiences": [ "{APP ID URI (WEB API)}" ]
    }
  }
},

Perbarui tempat penampung dalam konfigurasi sebelumnya agar sesuai dengan nilai yang digunakan aplikasi dalam Program file:

{TENANT ID (WEB API)}: ID Penyewa API web.
{APP ID URI (WEB API)}: URI ID Aplikasi dari API web.

Format otoritas mengadopsi pola berikut:

ME-ID jenis penyewa: https://sts.windows.net/{TENANT ID}/
Jenis penyewa B2C: https://login.microsoftonline.com/{TENANT ID}/v2.0/

Format audiens mengadopsi pola berikut ({CLIENT ID} adalah Id Klien dari API web; {DIRECTORY NAME} adalah nama direktori, misalnya, contoso):

ME-ID jenis penyewa: api://{CLIENT ID}
Jenis penyewa B2C: https://{DIRECTORY NAME}.onmicrosoft.com/{CLIENT ID}

Konfigurasi secara otomatis diambil oleh pembangun autentikasi pembawa JWT.

Hapus baris berikut dari Program file:

- jwtOptions.Authority = "...";
- jwtOptions.Audience = "...";

Untuk informasi selengkapnya tentang konfigurasi, lihat sumber daya berikut ini:

Konfigurasi pada di ASP.NET Core
Konfigurasi ASP.NET Core Blazor

Menggunakan Otoritas "umum" untuk aplikasi penyewa tunggal

Anda dapat menggunakan Otoritas "umum" untuk aplikasi penyewa tunggal, tetapi Anda harus mengambil langkah-langkah berikut untuk menerapkan validator penerbit kustom.

Microsoft.IdentityModel.Validators Tambahkan paket NuGet ke BlazorWebAppOidcproyek , , BlazorWebAppOidcServeratau BlazorWebAppOidcBff .

Catatan

Untuk panduan tentang menambahkan paket ke aplikasi .NET, lihat artikel di bagian Menginstal dan mengelola paket di Alur kerja konsumsi paket (dokumentasi NuGet). Konfirmasikan versi paket yang benar di NuGet.org.

Di bagian atas Program file, jadikan Microsoft.IdentityModel.Validators namespace tersedia.

using Microsoft.IdentityModel.Validators;

Gunakan kode berikut dalam Program file tempat opsi OIDC dikonfigurasi:

var microsoftIssuerValidator = 
    AadIssuerValidator.GetAadIssuerValidator(oidcOptions.Authority);
oidcOptions.TokenValidationParameters.IssuerValidator = 
    microsoftIssuerValidator.Validate;

Untuk informasi selengkapnya, lihat SecurityTokenInvalidIssuerException dengan OpenID Connect dan titik akhir "umum" Microsoft Azure AD (AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet #1731).

Mengalihkan ke halaman beranda saat keluar

Komponen LogInOrOut (Layout/LogInOrOut.razor) mengatur bidang tersembunyi untuk URL pengembalian (ReturnUrl) ke URL saat ini (currentURL). Saat pengguna keluar dari aplikasi, IdP mengembalikan pengguna ke halaman tempat mereka keluar. Jika pengguna keluar dari halaman aman, mereka dikembalikan ke halaman aman yang sama dan dikirim kembali melalui proses autentikasi. Alur autentikasi ini wajar ketika pengguna perlu mengubah akun secara teratur.

Atau, gunakan komponen LogInOrOut berikut, yang tidak menyediakan URL pengembalian saat keluar.

Layout/LogInOrOut.razor:

<div class="nav-item px-3">
    <AuthorizeView>
        <Authorized>
            <form action="authentication/logout" method="post">
                <AntiforgeryToken />
                <button type="submit" class="nav-link">
                    <span class="bi bi-arrow-bar-left-nav-menu" aria-hidden="true">
                    </span> Logout
                </button>
            </form>
        </Authorized>
        <NotAuthorized>
            <a class="nav-link" href="authentication/login">
                <span class="bi bi-person-badge-nav-menu" aria-hidden="true"></span> 
                Login
            </a>
        </NotAuthorized>
    </AuthorizeView>
</div>

Penyegaran token

Implementasi penyegar cookie kustom (CookieOidcRefresher.cs) secara otomatis memperbarui klaim pengguna ketika sudah kedaluwarsa. Implementasi saat ini mengharapkan untuk menerima token ID dari endpoint token sebagai imbalan token refresh. Klaim dalam token ID ini kemudian digunakan guna memperbarui klaim pengguna.

Implementasi contoh tidak menyertakan kode untuk meminta klaim dari titik akhir UserInfo saat penyegaran token. Untuk informasi selengkapnya, lihat BlazorWebAppOidc AddOpenIdConnect with GetClaimsFromUserInfoEndpoint = true doesn't propogate [sic] role claims to client (dotnet/aspnetcore #58826).

Catatan

Beberapa penyedia identitas hanya mengembalikan token akses saat menggunakan token refresh. CookieOidcRefresher dapat diperbarui dengan logika tambahan untuk terus menggunakan kumpulan klaim sebelumnya yang disimpan dalam cookie autentikasi atau menggunakan token akses untuk meminta klaim dari titik akhir UserInfo.

Nonce kriptografi

Nonce adalah nilai string yang mengaitkan sesi klien dengan token ID untuk mengurangi serangan pemutaran ulang.

Jika Anda menerima kesalahan nonce selama pengembangan dan pengujian autentikasi, gunakan sesi browser InPrivate/incognito baru untuk setiap eksekusi pengujian, tidak peduli seberapa kecil perubahan yang dilakukan pada aplikasi atau pengguna uji karena data kedaluarsa cookie dapat menyebabkan kesalahan nonce. Untuk informasi selengkapnya, lihat bagian Cookie dan data situs .

Nonce tidak diperlukan dan tidak digunakan ketika token penyegaran ditukar dengan token akses baru. Di aplikasi contoh, CookieOidcRefresher (CookieOidcRefresher.cs) dengan sengaja mengatur OpenIdConnectProtocolValidator.RequireNonce ke false.

Peran aplikasi untuk aplikasi yang tidak terdaftar di Microsoft Entra (ME-ID)

Bagian ini berkaitan dengan aplikasi yang tidak menggunakan ID Microsoft Entra (ME-ID) sebagai penyedia identitas. Untuk aplikasi yang terdaftar dengan ME-ID, lihat bagian Peran aplikasi untuk aplikasi yang terdaftar di Microsoft Entra (ME-ID).

Konfigurasikan jenis klaim peran (TokenValidationParameters.RoleClaimType) di OpenIdConnectOptions dari Program.cs:

oidcOptions.TokenValidationParameters.RoleClaimType = "{ROLE CLAIM TYPE}";

Untuk banyak penyedia identitas OIDC, jenis klaim peran adalah role. Periksa dokumentasi penyedia identitas Anda untuk nilai yang tepat.

UserInfo Ganti kelas dalam BlazorWebAppOidc.Client proyek dengan kelas berikut.

UserInfo.cs:

using Microsoft.AspNetCore.Components.WebAssembly.Authentication;
using System.Security.Claims;

namespace BlazorWebAppOidc.Client;

// Add properties to this class and update the server and client 
// AuthenticationStateProviders to expose more information about 
// the authenticated user to the client.
public sealed class UserInfo
{
    public required string UserId { get; init; }
    public required string Name { get; init; }
    public required string[] Roles { get; init; }

    public const string UserIdClaimType = "sub";
    public const string NameClaimType = "name";
    private const string RoleClaimType = "role";

    public static UserInfo FromClaimsPrincipal(ClaimsPrincipal principal) =>
        new()
        {
            UserId = GetRequiredClaim(principal, UserIdClaimType),
            Name = GetRequiredClaim(principal, NameClaimType),
            Roles = principal.FindAll(RoleClaimType).Select(c => c.Value)
                .ToArray(),
        };

    public ClaimsPrincipal ToClaimsPrincipal() =>
        new(new ClaimsIdentity(
            Roles.Select(role => new Claim(RoleClaimType, role))
                .Concat([
                    new Claim(UserIdClaimType, UserId),
                    new Claim(NameClaimType, Name),
                ]),
            authenticationType: nameof(UserInfo),
            nameType: NameClaimType,
            roleType: RoleClaimType));

    private static string GetRequiredClaim(ClaimsPrincipal principal,
        string claimType) =>
            principal.FindFirst(claimType)?.Value ??
            throw new InvalidOperationException(
                $"Could not find required '{claimType}' claim.");
}

Pada titik ini, Razor komponen dapat mengadopsi otorisasi berbasis peran dan berbasis kebijakan. Peran aplikasi muncul dalam klaim role, satu klaim untuk setiap peran.

Peran aplikasi pada aplikasi yang terdaftar di Microsoft Entra (ME-ID)

Gunakan panduan di bagian ini untuk menerapkan peran aplikasi, ME-ID grup keamanan, dan ME-ID peran administrator bawaan untuk aplikasi menggunakan ID Microsoft Entra (ME-ID).

Pendekatan yang dijelaskan di bagian ini mengatur ME-ID untuk mengirimkan grup dan peran dalam header autentikasi cookie . Ketika pengguna hanya anggota dari beberapa grup dan peran keamanan, pendekatan berikut harus berfungsi untuk sebagian besar platform hosting tanpa mengalami masalah di mana header terlalu panjang, misalnya dengan hosting IIS yang memiliki batas panjang header default 16 KB (MaxRequestBytes). Jika panjang header adalah masalah karena keanggotaan grup atau peran yang tinggi, kami sarankan untuk tidak mengikuti panduan di bagian ini demi menerapkan Microsoft Graph untuk mendapatkan grup dan peran pengguna dari ME-ID secara terpisah, pendekatan yang tidak meningkatkan ukuran autentikasi cookie. Untuk informasi selengkapnya, lihat Permintaan Buruk - Permintaan Terlalu Panjang - Server IIS (dotnet/aspnetcore #57545).

Konfigurasikan jenis klaim peran (TokenValidationParameters.RoleClaimType) di OpenIdConnectOptionsProgram.cs. Atur nilai ke roles:

oidcOptions.TokenValidationParameters.RoleClaimType = "roles";

Meskipun Anda tidak dapat menetapkan peran ke grup tanpa akun ME-ID Premium, Anda dapat menetapkan peran kepada pengguna dan menerima klaim peran untuk pengguna dengan akun Azure standar. Panduan di bagian ini tidak memerlukan akun ME-ID Premium.

Saat bekerja dengan direktori default, ikuti panduan di Menambahkan peran aplikasi ke aplikasi Anda dan menerimanya dalam token ( dokumentasiME-ID) untuk mengonfigurasi dan menetapkan peran. Jika Anda tidak bekerja dengan direktori default, edit manifes aplikasi di portal Azure untuk membuat peran aplikasi secara manual dalam appRoles entri file manifes. Untuk informasi selengkapnya, lihat Mengonfigurasi klaim peran ( dokumentasiME-ID).

Grup keamanan Azure pengguna tiba dalam groups klaim, dan penetapan peran administrator ME-ID bawaan pengguna tiba dalam klaim ID yang sudah dikenal (wids). Nilai untuk kedua jenis klaim adalah GUID (Globally Unique Identifier). Saat diterima oleh aplikasi, klaim ini dapat digunakan untuk menetapkan peran dan otorisasi kebijakan dalam Razor komponen.

Dalam manifes aplikasi di portal Microsoft Azure, atur atribut ke groupMembershipClaimsAll. Nilai All mengakibatkan ME-ID mengirim semua grup keamanan/distribusi (groups klaim) dan peran (wids klaim) dari pengguna yang masuk. Untuk mengatur groupMembershipClaims atribut:

Buka pendaftaran aplikasi di portal Azure.
Pilih Kelola>Manifes di bar samping.
Temukan atribut groupMembershipClaims.
Atur nilai ke All ("groupMembershipClaims": "All").
Pilih tombol Simpan .

UserInfo Ganti kelas dalam BlazorWebAppOidc.Client proyek dengan kelas berikut.

UserInfo.cs:

using Microsoft.AspNetCore.Components.WebAssembly.Authentication;
using System.Security.Claims;

namespace BlazorWebAppOidc.Client;

// Add properties to this class and update the server and client 
// AuthenticationStateProviders to expose more information about 
// the authenticated user to the client.
public sealed class UserInfo
{
    public required string UserId { get; init; }
    public required string Name { get; init; }
    public required string[] Roles { get; init; }
    public required string[] Groups { get; init; }
    public required string[] Wids { get; init; }

    public const string UserIdClaimType = "sub";
    public const string NameClaimType = "name";
    private const string RoleClaimType = "roles";
    private const string GroupsClaimType = "groups";
    private const string WidsClaimType = "wids";

    public static UserInfo FromClaimsPrincipal(ClaimsPrincipal principal) =>
        new()
        {
            UserId = GetRequiredClaim(principal, UserIdClaimType),
            Name = GetRequiredClaim(principal, NameClaimType),
            Roles = principal.FindAll(RoleClaimType).Select(c => c.Value)
                .ToArray(),
            Groups = principal.FindAll(GroupsClaimType).Select(c => c.Value)
                .ToArray(),
            Wids = principal.FindAll(WidsClaimType).Select(c => c.Value)
                .ToArray(),
        };

    public ClaimsPrincipal ToClaimsPrincipal() =>
        new(new ClaimsIdentity(
            Roles.Select(role => new Claim(RoleClaimType, role))
                .Concat(Groups.Select(role => new Claim(GroupsClaimType, role)))
                .Concat(Wids.Select(role => new Claim(WidsClaimType, role)))
                .Concat([
                    new Claim(UserIdClaimType, UserId),
                    new Claim(NameClaimType, Name),
                ]),
            authenticationType: nameof(UserInfo),
            nameType: NameClaimType,
            roleType: RoleClaimType));

    private static string GetRequiredClaim(ClaimsPrincipal principal,
        string claimType) =>
            principal.FindFirst(claimType)?.Value ??
            throw new InvalidOperationException(
                $"Could not find required '{claimType}' claim.");
}

Pada titik ini, Razor komponen dapat mengadopsi otorisasi berbasis peran dan berbasis kebijakan:

Peran aplikasi muncul dalam klaim roles, satu klaim untuk setiap peran.
Kelompok keamanan muncul dalam groups klaim, satu klaim untuk setiap grup. GUID grup keamanan muncul di portal Microsoft Azure saat Anda membuat grup keamanan dan dicantumkan saat memilih Identity>Gambaran Umum>Grup>Tampilan.
Peran administrator ME-ID bawaan muncul dalam wids klaim, satu klaim untuk setiap peran. Klaim wids yang memiliki nilai b79fbf4d-3ef9-4689-8143-76b194e85509 selalu dikirim oleh ME-ID untuk akun non-tamu dari penyewa dan tidak merujuk pada peran administrator. GUID peran administrator (ID templat peran) muncul di portal Azure saat memilih Peran & admin, diikuti oleh elipsis (...) Deskripsi untuk peran yang tercantum. ID templat peran juga tercantum dalam peran bawaan Microsoft Entra (dokumentasi Entra).

Pecahkan masalah

Pembalakan

Aplikasi server adalah aplikasi ASP.NET Core standar. Lihat panduan pengelogan ASP.NET Core untuk mengaktifkan tingkat pengelogan yang lebih rendah di aplikasi server.

Untuk mengaktifkan pengelogan debug atau pelacakan untuk Blazor WebAssembly autentikasi, lihat bagian Pengelogan autentikasi klien pada pengelogan ASP.NET Core Blazor dengan pengaturan pemilih versi artikel ke ASP.NET Core di .NET 7 atau yang lebih baru.

Kesalahan umum

Debugger berhenti pada saat pengecualian terjadi selama proses logout dengan Microsoft Entra External ID.

Pengecualian berikut menghentikan debugger Visual Studio saat keluar dari Microsoft Entra External ID:

Uncaught TypeError TypeError: Failed to execute 'postMessage' on 'Window': The provided value cannot be converted to a sequence.

Pengecualian dilemparkan dari kode Entra JavaScript, jadi ini bukan masalah dengan ASP.NET Core. Pengecualian tidak memengaruhi fungsionalitas aplikasi dalam produksi, sehingga pengecualian dapat diabaikan selama pengujian pengembangan lokal.
Kesalahan konfigurasi aplikasi atau Identity Penyedia (IP)

Kesalahan yang paling umum disebabkan oleh konfigurasi yang salah. Berikut ini adalah beberapa contohnya:
- Bergantung pada persyaratan skenario, Otoritas, Instans, ID Penyewa, DOMAIN Penyewa, ID Klien, atau URI Pengalihan yang hilang atau salah mencegah aplikasi mengautentikasi klien.
- Cakupan permintaan yang salah mencegah klien mengakses titik akhir API web server.
- Izin API server yang salah atau hilang mencegah klien mengakses titik akhir API web server.
- Menjalankan aplikasi di port yang berbeda dari yang dikonfigurasi dalam URI Pengalihan registrasi aplikasi untuk IP. Perhatikan bahwa port tidak diperlukan untuk ID Microsoft Entra dan aplikasi yang berjalan di alamat pengujian pengembangan localhost, tetapi konfigurasi port aplikasi dan port tempat aplikasi berjalan harus cocok untuk alamat localhost non-pengujian.
Cakupan konfigurasi dalam artikel ini menunjukkan contoh konfigurasi yang benar. Periksa konfigurasi dengan hati-hati mencari kesalahan konfigurasi aplikasi dan IP.

Jika konfigurasi terlihat benar:
- Menganalisis log aplikasi.
- Periksa lalu lintas jaringan antara aplikasi klien dan IP atau aplikasi server dengan alat pengembang browser. Seringkali, pesan kesalahan yang tepat atau pesan dengan petunjuk tentang apa yang menyebabkan masalah dikembalikan ke klien oleh IP atau aplikasi server setelah membuat permintaan. Panduan alat pengembang dapat ditemukan dalam artikel berikut:
  - Google Chrome (dokumentasi Google)
  - Microsoft Edge
  - Mozilla Firefox (dokumentasi Mozilla)
Tim dokumentasi menanggapi umpan balik dokumen dan bug dalam artikel (buka masalah dari bagian Umpan balik halaman ini ) tetapi tidak dapat memberikan dukungan produk. Beberapa forum dukungan publik tersedia untuk membantu memecahkan masalah aplikasi. Kami merekomendasikan hal-hal berikut:
Forum sebelumnya tidak dimiliki atau dikendalikan oleh Microsoft.

Untuk laporan bug yang dapat direproduksi pada kerangka kerja non-keamanan, non-sensitif, dan non-rahasia, buka masalah dengan tim produk ASP.NET Core. Jangan buka masalah dengan unit produk sampai Anda menyelidiki penyebab masalah secara menyeluruh dan tidak dapat menyelesaikannya sendiri dan dengan bantuan komunitas di forum dukungan publik. Unit produk tidak dapat memecahkan masalah aplikasi individual yang rusak karena kesalahan konfigurasi sederhana atau kasus penggunaan yang melibatkan layanan pihak ketiga. Jika laporan bersifat sensitif atau rahasia atau menggambarkan potensi kelemahan keamanan dalam produk yang dapat dieksploitasi oleh penyidik cyber, lihat Melaporkan masalah keamanan dan bug (dotnet/aspnetcore repositori GitHub).
Pengguna yang tidak berwenang untuk ME-ID

info: Otorisasi Microsoft.AspNetCore.Authorization.DefaultAuthorizationService[2] gagal. Persyaratan ini tidak terpenuhi: DenyAnonymousAuthorizationRequirement: Memerlukan pengguna yang diautentikasi.

Kesalahan panggilan balik masuk dari ME-ID:
- Kesalahan: unauthorized_client
- Deskripsi: AADB2C90058: The provided application is not configured to allow public clients.
Untuk mengatasi masalah ini:
1. Di portal Microsoft Azure, akses manifes aplikasi.
2. Atur atribut menjadiallowPublicClientnull atau true.

Cookie dan data situs

Cookie dan data situs dapat bertahan di seluruh pembaruan aplikasi dan mengganggu pengujian dan pemecahan masalah. Hapus hal berikut saat membuat perubahan kode aplikasi, perubahan akun pengguna dengan penyedia, atau perubahan konfigurasi aplikasi penyedia:

Cookie masuk pengguna
Cookie aplikasi
Data situs yang di-cache dan disimpan

Salah satu pendekatan untuk mencegah cookie dan data situs yang masih ada mengganggu pengujian dan pemecahan masalah adalah dengan:

Mengonfigurasi peramban
- Gunakan browser untuk pengujian yang dapat Anda konfigurasi untuk menghapus semua cookie dan data situs setiap kali browser ditutup.
- Pastikan browser ditutup secara manual atau oleh IDE untuk setiap perubahan pada aplikasi, pengguna uji, atau konfigurasi penyedia.
Gunakan perintah kustom untuk membuka browser dalam mode InPrivate atau mode Penyamaran di Visual Studio.
- Buka kotak dialog Telusuri Dengan dari tombol Jalankan Visual Studio.
- Pilih tombol Tambahkan .
- Berikan jalur ke browser Anda di bidang Program . Jalur yang dapat dieksekusi berikut adalah lokasi penginstalan umum untuk Windows 10. Jika browser Anda diinstal di lokasi yang berbeda atau Anda tidak menggunakan Windows 10, berikan jalur ke file eksekusi browser tersebut.
  - Microsoft Edge: C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
  - Google Chrome: C:\Program Files (x86)\Google\Chrome\Application\chrome.exe
  - Mozilla Firefox: C:\Program Files\Mozilla Firefox\firefox.exe
- Di bidang Argumen, berikan opsi baris perintah yang digunakan browser untuk membuka dalam mode InPrivate atau Penyamaran. Beberapa browser memerlukan URL aplikasi.
  - Microsoft Edge: Gunakan -inprivate.
  - Google Chrome: Gunakan --incognito --new-window {URL}, di mana {URL} adalah URL untuk dibuka (misalnya, https://localhost:5001).
  - Mozilla Firefox: Gunakan -private -url {URL}, di mana {URL} adalah placeholder untuk URL yang akan dibuka (misalnya, https://localhost:5001).
- Berikan nama di bidang Nama yang mudah diingat. Contohnya,Firefox Auth Testing.
- Pilih tombol OK .
- Untuk menghindari harus memilih profil browser untuk setiap iterasi pengujian dengan aplikasi, atur profil sebagai default dengan tombol Atur sebagai Default .
- Pastikan bahwa browser ditutup oleh IDE untuk setiap perubahan yang dilakukan pada aplikasi, penguji, atau konfigurasi penyedia.

Peningkatan aplikasi

Aplikasi yang berfungsi mungkin gagal segera setelah meningkatkan .NET Core SDK pada komputer pengembangan atau mengubah versi paket dalam aplikasi. Dalam beberapa kasus, paket yang tidak melekat dapat merusak aplikasi saat melakukan peningkatan besar. Sebagian besar masalah ini dapat diperbaiki dengan mengikuti instruksi berikut:

Kosongkan cache paket NuGet sistem lokal dengan mengeksekusi dotnet nuget locals all --clear dari shell perintah.
Hapus folder bin dan obj dalam proyek.
Pulihkan dan bangun ulang proyek.
Hapus semua file di folder penyebaran di server sebelum menyebarkan ulang aplikasi.

Catatan

Penggunaan versi paket yang tidak kompatibel dengan kerangka kerja target aplikasi tidak didukung. Untuk informasi tentang paket, gunakan Galeri NuGet.

Memulai solusi dari proyek yang benar

Blazor Web Apps:

Untuk salah satu sampel pola Backend-for-Frontend (BFF), mulai solusi dari proyek ini Aspire/Aspire.AppHost.
Untuk salah satu sampel pola non-BFF, mulai implementasi dari proyek server.

Blazor Server:

Mulai solusi dari proyek server.

Memeriksa pengguna

Komponen berikut UserClaims dapat digunakan langsung di aplikasi atau berfungsi sebagai dasar untuk penyesuaian lebih lanjut.

UserClaims.razor:

@page "/user-claims"
@using System.Security.Claims
@using Microsoft.AspNetCore.Authorization
@attribute [Authorize]

<PageTitle>User Claims</PageTitle>

<h1>User Claims</h1>

@if (claims.Any())
{
    <ul>
        @foreach (var claim in claims)
        {
            <li><b>@claim.Type:</b> @claim.Value</li>
        }
    </ul>
}

@code {
    private IEnumerable<Claim> claims = Enumerable.Empty<Claim>();

    [CascadingParameter]
    private Task<AuthenticationState>? AuthState { get; set; }

    protected override async Task OnInitializedAsync()
    {
        if (AuthState == null)
        {
            return;
        }

        var authState = await AuthState;
        claims = authState.User.Claims;
    }
}

Sumber Daya Tambahan:

AzureAD/microsoft-identity-web Repositori GitHub: Panduan bermanfaat tentang menerapkan Microsoft Identity Web untuk ID Microsoft Entra dan Azure Active Directory B2C untuk aplikasi ASP.NET Core, termasuk tautan ke aplikasi sampel dan dokumentasi Azure terkait. Saat ini, Blazor Web Apptidak ditangani secara eksplisit oleh dokumentasi Azure, tetapi penyiapan dan konfigurasi Blazor Web App untuk ME-ID dan hosting Azure sama dengan untuk aplikasi web ASP.NET Core apa pun.
AuthenticationStateProvider layanan
Mengelola status autentikasi dalam Blazor Web Apps
Refresh token selama permintaan http di Blazor Server Interaktif dengan OIDC (dotnet/aspnetcore #55213)
Amankan data pada Blazor Web Appdengan Penyajian Otomatis Interaktif
Cara mengakses AuthenticationStateProvider dari DelegatingHandler

Bagikan melalui

Amankan ASP.NET Core Blazor Web App dengan OpenID Connect (OIDC)

Contoh solusi

Pendaftaran aplikasi ID Microsoft Entra

Menetapkan rahasia klien

MinimalApiJwt proyek

Blazor Web App proyek server (BlazorWebAppOidc)

Blazor Web App proyek klien (BlazorWebAppOidc.Client)

Contoh solusi

Pendaftaran aplikasi ID Microsoft Entra

Menetapkan rahasia klien

MinimalApiJwt proyek

BlazorWebAppOidcServer proyek

Prasyarat

Contoh solusi

Pendaftaran aplikasi ID Microsoft Entra

Menetapkan rahasia klien

.NET Aspire Proyek

MinimalApiJwt proyek

Proyek sisi server Blazor Web App (BlazorWebAppOidc)

Proyek Blazor Web App sisi klien (BlazorWebAppOidc.Client)

Hanya melakukan serialisasi klaim nama dan klaim peran

Pasok konfigurasi dengan penyedia konfigurasi JSON (pengaturan aplikasi)

Menggunakan Otoritas "umum" untuk aplikasi penyewa tunggal

Mengalihkan ke halaman beranda saat keluar

Penyegaran token

Nonce kriptografi

Peran aplikasi untuk aplikasi yang tidak terdaftar di Microsoft Entra (ME-ID)

Peran aplikasi pada aplikasi yang terdaftar di Microsoft Entra (ME-ID)

Pecahkan masalah

Pembalakan

Kesalahan umum

Cookie dan data situs

Peningkatan aplikasi

Memulai solusi dari proyek yang benar

Memeriksa pengguna

Sumber Daya Tambahan:

Sumber Daya Tambahan:

`MinimalApiJwt` proyek

Blazor Web App proyek server (`BlazorWebAppOidc`)

Blazor Web App proyek klien (`BlazorWebAppOidc.Client`)

`MinimalApiJwt` proyek

`BlazorWebAppOidcServer` proyek

`MinimalApiJwt` proyek

Proyek sisi server Blazor Web App (`BlazorWebAppOidc`)

Proyek Blazor Web App sisi klien (`BlazorWebAppOidc.Client`)