Mengonfigurasi Autentikasi Windows di ASP.NET Core

Oleh Rick Anderson dan Kirk Larkin

Autentikasi Windows (juga dikenal sebagai Autentikasi Negosiasi, Kerberos, atau NTLM) dapat dikonfigurasi untuk aplikasi ASP.NET Core yang dihosting dengan IIS, Kestrel, atau HTTP.sys.

Autentikasi Windows bergantung pada sistem operasi untuk mengautentikasi pengguna aplikasi ASP.NET Core. Autentikasi Windows digunakan untuk server yang berjalan di jaringan perusahaan menggunakan identitas domain Direktori Aktif atau akun Windows untuk mengidentifikasi pengguna. Autentikasi Windows paling cocok untuk lingkungan intranet di mana pengguna, aplikasi klien, dan server web termasuk dalam domain Windows yang sama.

Catatan

Autentikasi Windows tidak didukung dengan HTTP/2. Tantangan autentikasi dapat dikirim pada respons HTTP/2, tetapi klien harus menurunkan ke HTTP/1.1 sebelum mengautentikasi.

Skenario proksi dan load balancer

Autentikasi Windows adalah skenario stateful yang terutama digunakan dalam intranet, di mana proksi atau load balancer biasanya tidak menangani lalu lintas antara klien dan server. Jika proksi atau load balancer digunakan, Autentikasi Windows hanya berfungsi jika proksi atau load balancer:

• Menangani autentikasi.
• Meneruskan informasi autentikasi pengguna ke aplikasi (misalnya, di header permintaan), yang bertindak berdasarkan informasi autentikasi.

Alternatif untuk Autentikasi Windows di lingkungan tempat proksi dan load balancer digunakan adalah Layanan Federasi Direktori Aktif (ADFS) dengan OpenID Koneksi (OIDC).

IIS/IIS Express

Tambahkan paket NuGet Microsoft.AspNetCore.Authentication.Negosiasi dan layanan autentikasi dengan memanggil AddAuthentication di Program.cs:

using Microsoft.AspNetCore.Authentication.Negotiate;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
   .AddNegotiate();

builder.Services.AddAuthorization(options =>
{
    options.FallbackPolicy = options.DefaultPolicy;
});
builder.Services.AddRazorPages();

var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseRouting();

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

app.MapRazorPages();

app.Run();

Kode sebelumnya dihasilkan oleh templat ASP.NET Core Razor Pages dengan Autentikasi Windows yang ditentukan.

Luncurkan pengaturan (debugger)

Konfigurasi untuk pengaturan peluncuran Properties/launchSettings.json hanya memengaruhi file untuk IIS Express dan tidak mengonfigurasi IIS untuk Autentikasi Windows. Konfigurasi server dijelaskan di bagian IIS .

Templat Aplikasi Web yang tersedia melalui Visual Studio atau .NET Core CLI dapat dikonfigurasi untuk mendukung Autentikasi Windows, yang memperbarui Properties/launchSettings.json file secara otomatis.

Visual Studio

Proyek baru

Buat Halaman atau aplikasi MVC baru Razor . Dalam dialog Informasi tambahan, atur jenis Autentikasi ke Windows.

Jalankan aplikasi. Nama pengguna muncul di antarmuka pengguna aplikasi yang dirender.

Proyek yang sudah ada

Properti proyek mengaktifkan Autentikasi Windows dan menonaktifkan Autentikasi Anonim. Buka dialog luncurkan profil:

1. Di Penjelajah Solusi, klik kanan proyek dan pilih Properti.
2. Pilih tab Debug > Umum dan pilih Buka antarmuka pengguna profil peluncuran debug.
3. Kosongkan kotak centang untuk Aktifkan Autentikasi Anonim.
4. Pilih kotak centang untuk Aktifkan Autentikasi Windows.

Atau, properti dapat dikonfigurasi dalam simpul iisSettingslaunchSettings.json file:

"iisSettings": {
    "windowsAuthentication": true,
    "anonymousAuthentication": false,
    "iisExpress": {
        "applicationUrl": "http://localhost:52171/",
        "sslPort": 44308
    }
}

.NET Core CLI

Proyek baru

Jalankan perintah baru dotnet dengan webapp argumen (ASP.NET Core Web App) dan --auth Windows beralih:

dotnet new webapp --auth Windows

Proyek yang sudah ada

Perbarui simpul iisSettingslaunchSettings.json file:

"iisSettings": {
    "windowsAuthentication": true,
    "anonymousAuthentication": false,
    "iisExpress": {
        "applicationUrl": "http://localhost:52171/",
        "sslPort": 44308
    }
}

IIS

IIS menggunakan Modul Inti ASP.NET untuk menghosting aplikasi ASP.NET Core. Autentikasi Windows dikonfigurasi untuk IIS melalui file web.config . Bagian berikut menunjukkan cara:

• Berikan file web.config lokal yang mengaktifkan Autentikasi Windows di server saat aplikasi disebarkan.
• Gunakan Manajer IIS untuk mengonfigurasi file web.config dari aplikasi ASP.NET Core yang telah disebarkan ke server.

Jika Anda belum melakukannya, aktifkan IIS untuk menghosting aplikasi ASP.NET Core. Untuk informasi selengkapnya, lihat Host ASP.NET Core di Windows dengan IIS.

Aktifkan Layanan Peran IIS untuk Autentikasi Windows. Untuk informasi selengkapnya, lihat Mengaktifkan Autentikasi Windows di IIS Role Services (lihat Langkah 2).

IIS Integration Middleware dikonfigurasi untuk mengautentikasi permintaan secara otomatis secara default. Untuk informasi selengkapnya, lihat Host ASP.NET Core di Windows dengan IIS: Opsi IIS (AutomaticAuthentication).

Modul ASP.NET Core dikonfigurasi untuk meneruskan token Autentikasi Windows ke aplikasi secara default. Untuk informasi selengkapnya, lihat referensi konfigurasi Modul ASP.NET Core: Atribut elemen aspNetCore.

Gunakan salah satu pendekatan berikut:

• Sebelum menerbitkan dan menyebarkan proyek, tambahkan file web.config berikut ke akar proyek:

  <?xml version="1.0" encoding="utf-8"?>
  <configuration>
    <location path="." inheritInChildApplications="false">
      <system.webServer>
        <security>
          <authentication>
            <anonymousAuthentication enabled="false" />
            <windowsAuthentication enabled="true" />
          </authentication>
        </security>
      </system.webServer>
    </location>
  </configuration>
  

  Ketika proyek diterbitkan oleh .NET Core SDK (tanpa properti yang <IsTransformWebConfigDisabled> diatur ke true dalam file proyek), file web.config yang diterbitkan menyertakan bagian .<location><system.webServer><security><authentication> Untuk informasi selengkapnya tentang <IsTransformWebConfigDisabled> properti, lihat Host ASP.NET Core di Windows dengan IIS.

• Setelah menerbitkan dan menyebarkan proyek, lakukan konfigurasi sisi server dengan Manajer IIS:

  1. Di Manajer IIS, pilih situs IIS di bawah simpul Situs bilah samping Koneksi ion.
  2. Klik ganda Autentikasi di area IIS.
  3. Pilih Autentikasi Anonim. Pilih Nonaktifkan di bar samping Tindakan .
  4. Pilih Autentikasi Windows. Pilih Aktifkan di bar samping Tindakan .

  Ketika tindakan ini diambil, Manajer IIS memodifikasi file web.config aplikasi. Simpul <system.webServer><security><authentication> ditambahkan dengan pengaturan yang diperbarui untuk anonymousAuthentication dan windowsAuthentication:

  <system.webServer>
    <security>
      <authentication>
        <anonymousAuthentication enabled="false" />
        <windowsAuthentication enabled="true" />
      </authentication>
    </security>
  </system.webServer>
  

  Bagian <system.webServer> yang ditambahkan ke file web.config oleh IIS Manager berada di luar bagian aplikasi <location> yang ditambahkan oleh .NET Core SDK saat aplikasi diterbitkan. Karena bagian ditambahkan di luar simpul<location>, pengaturan diwariskan oleh sub-aplikasi apa pun ke aplikasi saat ini. Untuk mencegah pewarisan, pindahkan bagian yang ditambahkan <security> di dalam <location><system.webServer> bagian yang disediakan .NET Core SDK.

  Ketika Manajer IIS digunakan untuk menambahkan konfigurasi IIS, IIS hanya memengaruhi file web.config aplikasi di server. Penyebaran aplikasi berikutnya dapat menimpa pengaturan di server jika salinan server web.config digantikan oleh file web.config proyek. Gunakan salah satu pendekatan berikut untuk mengelola pengaturan:

  • Gunakan Manajer IIS untuk mengatur ulang pengaturan dalam file web.config setelah file ditimpa saat penyebaran.
  • Tambahkan file web.config ke aplikasi secara lokal dengan pengaturan.

Kestrel

Paket NuGet Microsoft.AspNetCore.Authentication.Negotiate dapat digunakan untuk Kestrel mendukung Autentikasi Windows menggunakan Negosiasi dan Kerberos di Windows, Linux, dan macOS.

Peringatan

Kredensial dapat dipertahankan di seluruh permintaan pada koneksi. Autentikasi negosiasi tidak boleh digunakan dengan proksi kecuali proksi mempertahankan afinitas koneksi 1:1 (koneksi persisten) dengan Kestrel.

Catatan

Handler Negosiasi mendeteksi apakah server yang mendasar mendukung Autentikasi Windows secara asli dan jika diaktifkan. Jika server mendukung Autentikasi Windows tetapi dinonaktifkan, kesalahan akan muncul yang meminta Anda untuk mengaktifkan implementasi server. Ketika Autentikasi Windows diaktifkan di server, handler Negosiasi secara transparan meneruskan permintaan autentikasi ke server tersebut.

Autentikasi diaktifkan oleh kode yang disorot berikut ke Program.cs:

using Microsoft.AspNetCore.Authentication.Negotiate;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
   .AddNegotiate();

builder.Services.AddAuthorization(options =>
{
    options.FallbackPolicy = options.DefaultPolicy;
});
builder.Services.AddRazorPages();

var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseRouting();

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

app.MapRazorPages();

app.Run();

Kode sebelumnya dihasilkan oleh templat ASP.NET Core Razor Pages dengan Autentikasi Windows yang ditentukan. API berikut digunakan dalam kode sebelumnya:

• AddAuthentication
• AddNegotiate
• UseAuthentication

Autentikasi Kerberos dan kontrol akses berbasis peran (RBAC)

Autentikasi Kerberos di Linux atau macOS tidak memberikan informasi peran apa pun untuk pengguna yang diautentikasi. Untuk menambahkan informasi peran dan grup ke pengguna Kerberos, handler autentikasi harus dikonfigurasi untuk mengambil peran dari domain LDAP. Konfigurasi paling dasar hanya menentukan domain LDAP untuk dikueri dan menggunakan konteks pengguna yang diautentikasi untuk mengkueri domain LDAP:

using Microsoft.AspNetCore.Authentication.Negotiate;
using System.Runtime.InteropServices;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
    .AddNegotiate(options =>
    {
        if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
        {
            options.EnableLdap("contoso.com");
        }
    });

Beberapa konfigurasi mungkin memerlukan kredensial tertentu untuk mengkueri domain LDAP. Kredensial dapat ditentukan dalam opsi yang disorot berikut ini:

using Microsoft.AspNetCore.Authentication.Negotiate;
using System.Runtime.InteropServices;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
        .AddNegotiate(options =>
        {
            if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
            {
                options.EnableLdap(settings =>
                {
                    settings.Domain = "contoso.com";
                    settings.MachineAccountName = "machineName";
                    settings.MachineAccountPassword =
                                      builder.Configuration["Password"];
                });
            }
        });

builder.Services.AddRazorPages();

Secara default, handler autentikasi negosiasi menyelesaikan domain berlapis. Dalam lingkungan LDAP yang besar atau rumit, mengatasi domain berlapis dapat mengakibatkan pencarian lambat atau banyak memori yang digunakan untuk setiap pengguna. Resolusi domain berlapis dapat dinonaktifkan menggunakan IgnoreNestedGroups opsi .

Permintaan anonim diizinkan. Gunakan Otorisasi Inti ASP.NET untuk menantang permintaan anonim untuk autentikasi.

Konfigurasi lingkungan Windows

Komponen Microsoft.AspNetCore.Authentication.Negotiate melakukan autentikasi Mode Pengguna. Nama Perwakilan Layanan (SPN) harus ditambahkan ke akun pengguna yang menjalankan layanan, bukan akun komputer. Jalankan setspn -S HTTP/myservername.mydomain.com myuser dalam shell perintah administratif.

Kerberos vs NTLM

Paket Negosiasi untuk Kestrel ASP.NET Core mencoba menggunakan Kerberos, yang merupakan skema autentikasi yang lebih aman dan peforman daripada NTLM:

using Microsoft.AspNetCore.Authentication.Negotiate;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
   .AddNegotiate();

builder.Services.AddAuthorization(options =>
{
    options.FallbackPolicy = options.DefaultPolicy;
});
builder.Services.AddRazorPages();

var app = builder.Build();

NegotiateDefaults.AuthenticationScheme menentukan Kerberos karena merupakan default.

IIS, IISExpress, dan Kestrel mendukung Kerberos dan NTLM.

Memeriksa header WWW-Authenticate: menggunakan IIS atau IISExpress dengan alat seperti Fiddler menunjukkan baik Negotiate atau NTLM.

Kestrel hanya memperlihatkan WWW-Authenticate: Negotiate

Header WWW-Authenticate: Negotiate berarti bahwa server dapat menggunakan NTLM atau Kerberos. Kestrelmemerlukan awalan Negotiateheader, tidak mendukung penentuan NTLM secara langsung dalam header autentikasi permintaan atau respons. NTLM didukung dalam Kestrel, tetapi harus dikirim sebagai Negotiate.

Pada Kestrel, untuk melihat apakah NTLM atau Kerberos digunakan, Base64 mendekode header dan menunjukkan atau NTLMHTTP. HTTP menunjukkan Kerberos digunakan.

Konfigurasi lingkungan Linux dan macOS

Petunjuk untuk menggabungkan komputer Linux atau macOS ke domain Windows tersedia di artikel Koneksi Azure Data Studio ke SQL Server Anda menggunakan autentikasi Windows - Kerberos. Instruksi membuat akun komputer untuk komputer Linux di domain. SPN harus ditambahkan ke akun komputer tersebut.

Catatan

Saat mengikuti panduan di artikel Koneksi Azure Data Studio ke SQL Server Anda menggunakan autentikasi Windows - Kerberos, ganti python-software-properties dengan python3-software-properties jika diperlukan.

Setelah komputer Linux atau macOS bergabung ke domain, langkah-langkah tambahan diperlukan untuk menyediakan file keytab dengan SPN:

• Pada pengendali domain, tambahkan SPN layanan web baru ke akun komputer:
  • setspn -S HTTP/mywebservice.mydomain.com mymachine
  • setspn -S HTTP/mywebservice@MYDOMAIN.COM mymachine
• Gunakan ktpass untuk menghasilkan file keytab:
  • ktpass -princ HTTP/mywebservice.mydomain.com@MYDOMAIN.COM -pass myKeyTabFilePassword -mapuser MYDOMAIN\mymachine$ -pType KRB5_NT_PRINCIPAL -out c:\temp\mymachine.HTTP.keytab -crypto AES256-SHA1
  • Beberapa bidang harus ditentukan dalam huruf besar seperti yang ditunjukkan.
• Salin file keytab ke komputer Linux atau macOS.
• Pilih file keytab melalui variabel lingkungan: export KRB5_KTNAME=/tmp/mymachine.HTTP.keytab
• Panggil klist untuk menampilkan SPN yang saat ini tersedia untuk digunakan.

Catatan

File keytab berisi kredensial akses domain dan harus dilindungi.

HTTP.sys

HTTP.sysmendukung Autentikasi Windows Mode Kernel menggunakan Negosiasi, NTLM, atau Autentikasi Dasar.

Kode berikut menambahkan autentikasi dan mengonfigurasi host web aplikasi untuk menggunakan HTTP.sys dengan Autentikasi Windows:

using Microsoft.AspNetCore.Server.HttpSys;
using System.Runtime.InteropServices;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(HttpSysDefaults.AuthenticationScheme);

if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
{
    builder.WebHost.UseHttpSys(options =>
        {
            options.Authentication.Schemes =
                AuthenticationSchemes.NTLM |
                AuthenticationSchemes.Negotiate;
            options.Authentication.AllowAnonymous = false;
        });
}

Catatan

HTTP.sys mendelegasikan ke autentikasi Mode Kernel dengan protokol autentikasi Kerberos. Autentikasi Mode Pengguna tidak didukung dengan Kerberos dan HTTP.sys. Akun komputer harus digunakan untuk mendekripsi token/tiket Kerberos yang diperoleh dari Direktori Aktif dan diteruskan oleh klien ke server untuk mengautentikasi pengguna. Daftarkan Nama Perwakilan Layanan (SPN) untuk host, bukan pengguna aplikasi.

Catatan

HTTP.sys tidak didukung di Nano Server versi 1709 atau yang lebih baru. Untuk menggunakan Autentikasi Windows dan HTTP.sys dengan Nano Server, gunakan kontainer Server Core (microsoft/windowsservercore). Untuk informasi selengkapnya tentang Server Core, lihat Apa itu opsi penginstalan Server Core di Windows Server?.

Mengotorisasi pengguna

Status konfigurasi akses anonim menentukan cara [Authorize] atribut dan [AllowAnonymous] digunakan dalam aplikasi. Dua bagian berikut menjelaskan cara menangani status konfigurasi akses anonim yang tidak diizinkan dan diizinkan.

Melarang akses anonim

Ketika Autentikasi Windows diaktifkan dan akses anonim dinonaktifkan, atribut dan [AllowAnonymous] [[Authorize]](xref:Microsoft.AspNetCore.Authorization.AuthorizeAttribute) tidak berpengaruh. Jika situs IIS dikonfigurasi untuk melarang akses anonim, permintaan tidak pernah mencapai aplikasi. Untuk alasan ini, [AllowAnonymous] atribut tidak berlaku.

Perbolehkan akses anonim

Ketika Autentikasi Windows dan akses anonim diaktifkan, gunakan atribut dan [AllowAnonymous] [[Authorize]](xref:Microsoft.AspNetCore.Authorization.AuthorizeAttribute). Atribut [[Authorize]](xref:Microsoft.AspNetCore.Authorization.AuthorizeAttribute) memungkinkan Anda mengamankan titik akhir aplikasi yang memerlukan autentikasi. Atribut [AllowAnonymous] mengambil alih [Authorize] atribut di aplikasi yang memungkinkan akses anonim. Untuk detail penggunaan atribut, lihat Otorisasi sederhana di ASP.NET Core.

Catatan

Secara default, pengguna yang tidak memiliki otorisasi untuk mengakses halaman disajikan dengan respons HTTP 403 kosong. Middleware StatusCodePages dapat dikonfigurasi untuk memberi pengguna pengalaman "Akses Ditolak" yang lebih baik.

Peniruan

ASP.NET Core tidak menerapkan peniruan identitas. Aplikasi berjalan dengan identitas aplikasi untuk semua permintaan, menggunakan kumpulan aplikasi atau identitas proses. Jika aplikasi harus melakukan tindakan atas nama pengguna, gunakan WindowsIdentity. RunImpersonated atau RunImpersonatedAsync di middleware sebaris terminal di Program.cs. Jalankan satu tindakan dalam konteks ini lalu tutup konteks.

app.Run(async (context) =>
{
    try
    {
        var user = (WindowsIdentity)context.User.Identity!;

        await context.Response
            .WriteAsync($"User: {user.Name}\tState: {user.ImpersonationLevel}\n");

        await WindowsIdentity.RunImpersonatedAsync(user.AccessToken, async () =>
        {
            var impersonatedUser = WindowsIdentity.GetCurrent();
            var message =
                $"User: {impersonatedUser.Name}\t" +
                $"State: {impersonatedUser.ImpersonationLevel}";

            var bytes = Encoding.UTF8.GetBytes(message);
            await context.Response.Body.WriteAsync(bytes, 0, bytes.Length);
        });
    }
    catch (Exception e)
    {
        await context.Response.WriteAsync(e.ToString());
    }
});

Meskipun paket Microsoft.AspNetCore.Authentication.Negotiate memungkinkan autentikasi di Windows, Linux, dan macOS, peniruan hanya didukung di Windows.

Transformasi klaim

Saat menghosting dengan IIS, AuthenticateAsync tidak dipanggil secara internal untuk menginisialisasi pengguna. Oleh karena itu, implementasi yang IClaimsTransformation digunakan untuk mengubah klaim setelah setiap autentikasi tidak diaktifkan secara default. Untuk informasi selengkapnya dan contoh kode yang mengaktifkan transformasi klaim, lihat Perbedaan antara hosting dalam proses dan di luar proses.

Sumber daya tambahan

• dotnet publish
• Host ASP.NET Core di Windows dengan IIS
• ASP.NET Core Module (ANCM) untuk IIS
• Profil penerbitan Visual Studio (.pubxml) untuk penyebaran aplikasi ASP.NET Core