Proksi internal perusahaan dan aplikasi Windows — merapikan resolusi proksi WinINET, WinHTTP, dan .NET

“Peramban bisa membuka situs eksternal, tetapi hanya aplikasi bisnis yang tidak mencapai API eksternal.” “Berjalan di mesin pengembangan, tetapi kehabisan waktu di jaringan pelanggan.” “Komunikasi berhasil jika dijalankan secara manual, lalu gagal begitu dijadikan layanan Windows.” — Ketika aplikasi bisnis dijalankan di lingkungan yang punya proksi internal, konsultasi semacam ini termasuk yang paling rutin.

Dalam kebanyakan kasus penyebabnya bukan gangguan di server proksi, dan bukan bug aplikasi. Di Windows, apa yang disebut “pengaturan proksi” terpecah ke beberapa jalur, dan pengaturan mana yang dibaca siapa berbeda menurut aplikasi (menurut tumpukan HTTP yang dipakai) dan menurut akun yang menjalankan proses — ketidaksesuaian itulah intinya. Pengaturan yang dibaca peramban, yang dibaca layanan, dan yang dibaca HttpClient .NET masing-masing bisa menjadi hal yang berbeda. Begitu struktur itu dipahami, isolasi masalah “berjalan di peramban, tetapi…” menjadi jauh lebih cepat.

Artikel ini ditujukan untuk staf TI perusahaan kecil dan menengah serta pengembang aplikasi Windows. Isinya merangkai, dalam satu gambar, tiga jalur pengaturan proksi — WinINET, WinHTTP, dan variabel lingkungan — konfigurasi otomatis PAC dan WPAD, perbedaan resolusi proksi antara .NET Framework dan .NET (Core dan sesudahnya), proksi berautentikasi (407), inspeksi TLS, hingga prosedur isolasi praktis. Pola pembuatan HttpClient dan desain batas waktu sendiri dibahas di “Jangan bungkus HttpClient dengan using”, jadi artikel ini berfokus pada resolusi proksi.

1. Kesimpulan dulu

• Pengaturan proksi Windows bukan satu hal; ada setidaknya tiga jalur. (1) Pengaturan WinINET per pengguna (halaman “Proksi” di aplikasi Pengaturan = Opsi Internet lama), (2) pengaturan mesin WinHTTP (netsh winhttp), dan (3) variabel lingkungan HTTP_PROXY/HTTPS_PROXY. Mana yang dibaca diputuskan di sisi aplikasi.¹²
• “Proksi” yang terlihat di aplikasi Pengaturan adalah pengaturan per pengguna WinINET. Peramban dan aplikasi interaktif membacanya; layanan Windows tidak. WinINET tidak didukung untuk dipakai di layanan; pemakaian layanan adalah tugas WinHTTP.¹³
• Penyebab paling sering untuk “berjalan secara manual, tetapi gagal sebagai layanan” adalah perbedaan akun yang menjalankan proses. LocalSystem dan akun layanan tidak melihat proksi per pengguna yang diatur administrator di layarnya sendiri.³⁴
• netsh winhttp set proxy adalah pengaturan statis; tidak menangani PAC, deteksi otomatis, atau autentikasi proksi. Jika PAC atau WPAD ingin dikonfigurasi per mesin, yang diperlukan adalah sisi netsh winhttp set advproxy.⁴²
• Hasil PAC berubah per URL. Fungsi FindProxyForURL di berkas PAC menerima URL dan host, lalu mengembalikan daftar proksi atau koneksi langsung (DIRECT). “Situs itu tembus, tetapi hanya API ini yang gagal” kadang disebabkan cabang di PAC.⁵⁶
• HttpClient pada .NET (Core dan sesudahnya) menginisialisasi proksi bawaan dalam urutan variabel lingkungan → pengaturan proksi pengguna Windows. Jika salah satu dari HTTP_PROXY, HTTPS_PROXY, atau ALL_PROXY didefinisikan, itu diutamakan atas pengaturan OS, sehingga kecelakaan “seseorang meninggalkan variabel lingkungan” bisa terjadi.⁷
• Bawaan .NET Framework adalah Opsi Internet akun yang sedang menjalankan proses, dan dapat ditimpa dengan defaultProxy di app.config. Pengaturan berkas konfigurasi diutamakan atas pengaturan sistem.⁸⁹
• 407 adalah kesalahan autentikasi proksi; itu berbeda dari 401 (autentikasi server). Skemanya mencakup Negotiate, NTLM, Basic, dan di .NET kredensial dikirim dengan DefaultProxyCredentials atau WebProxy.UseDefaultCredentials. Perhatikan bahwa di bawah akun layanan, isi “kredensial bawaan” berubah.¹⁰¹¹¹²
• Proksi inspeksi TLS baru berdiri sebagai satu paket bersama distribusi sertifikat CA internal. Mesin dan runtime yang belum menerimanya mendapat kesalahan validasi sertifikat. Selesaikan dengan distribusi ke penyimpanan sertifikat, bukan dengan menonaktifkan validasi di aplikasi.¹³⁴

Dalam satu kalimat: setiap kali dikatakan “pengaturan proksi sudah diperiksa”, selalu bisa disebutkan jalur mana dari tiga itu yang diperiksa, dan dari akun mana — itulah pokok artikel ini.

Pada diagram, garis utuh menunjukkan relasi yang selalu berlaku dan garis putus-putus menunjukkan relasi bersyarat (syaratnya ada pada penjelasan masing-masing relasi di halaman rincian). Daftar lengkap relasi (total 19, beserta bukti dan tingkat kepastian) serta definisi konsep utama dikumpulkan di halaman rincian peta pengetahuan (dalam bahasa Jepang). Data: JSON-LD / Turtle

2. Di Windows ada tiga jalur “pengaturan proksi”

Mulai dari peta keseluruhan. Jalur yang dipakai aplikasi di Windows untuk menemukan proksi internal terpecah ke tiga kelompok berikut.

(1) adalah apa yang umumnya dikenali sebagai “pengaturan proksi Windows”; substansinya adalah konfigurasi WinINET. Secara historis itu Opsi Internet Internet Explorer, dan secara bawaan disimpan per pengguna.⁴

(2) adalah bawaan per mesin untuk konteks seperti layanan, di mana “tidak ada pengguna yang masuk”. (3) terutama adalah konvensi alat yang berasal dari dunia lintas platform; di Windows, .NET (Core dan sesudahnya) serta curl dan sejenisnya juga membacanya.⁷

Yang penting: jalur mana yang dibaca diputuskan di sisi aplikasi, bukan di sisi pengaturan. Jika aplikasi memakai WinINET secara internal, yang dibaca adalah (1); jika WinHTTP, (2) (atau penetapan khusus aplikasi); jika .NET (Core dan sesudahnya), urutannya (3) lalu (1). Jadi biasanya bukan “pengaturan proksi sudah benar tetapi tetap tidak tersambung”; kenyataannya “jalur yang dibaca aplikasi berbeda dari jalur yang baru saja diperiksa”.

Selain itu, jika kebijakan grup “Atur pengaturan proksi per komputer, bukan per pengguna” diaktifkan, (1) dapat dialihkan ke cakupan mesin dan diterapkan sama ke semua pengguna. Dengan MDM (Intune dan sejenisnya), konfigurasi per perangkat dapat dilakukan lewat NetworkProxy CSP.⁴

3. WinINET dan WinHTTP — untuk aplikasi interaktif versus untuk layanan

3.1. Perbedaan peran

WinINET dan WinHTTP sama-sama tumpukan klien HTTP bawaan Windows, tetapi skenario pemakaian yang diasumsikan berbeda.

• WinINET: untuk aplikasi desktop interaktif. Secara otomatis mewarisi Opsi Internet pengguna (proksi, cookie, cache kredensial), dan jika perlu dapat menampilkan UI input kredensial. Namun pemakaian di layanan atau proses yang bersifat layanan tidak didukung.¹
• WinHTTP: untuk layanan dan sisi server. Mendukung eksekusi di bawah akun layanan, impersonation utas, dan pemisahan sesi; sebagai gantinya tidak berbagi pengaturan peramban, cookie, atau kredensial pengguna. UI juga tidak ditampilkan.³

Pedoman Microsoft sendiri jelas: “pakai WinINET kecuali proses dijalankan di dalam layanan, atau di proses yang bersifat layanan yang membutuhkan pemisahan sesi dan impersonation” — sebaliknya, jika layanan, pakai WinHTTP.¹

3.2. Operasi dasar netsh winhttp

Proksi bawaan mesin WinHTTP dioperasikan dengan netsh.²

:: Tampilkan pengaturan proksi WinHTTP saat ini
netsh winhttp show proxy

:: Atur proksi statis (dengan daftar bypass)
netsh winhttp set proxy proxy-server="proxy.example.co.jp:8080" bypass-list="*.example.co.jp;<local>"

:: Impor pengaturan Opsi Internet (WinINET)
netsh winhttp import proxy source=ie

:: Kembalikan ke bawaan (DIRECT)
netsh winhttp reset proxy

Ada dua batasan yang perlu dipegang di sini.

1. netsh winhttp set proxy adalah pengaturan statis. Deteksi otomatis proksi, penetapan URL PAC, dan autentikasi proksi tidak ditangani.⁴
2. import proxy source=ie hanya menyalin pengaturan statis pada saat dijalankan; perubahan Opsi Internet setelah itu tidak diikuti. Jika konfigurasi per mesin yang mencakup PAC atau deteksi otomatis diperlukan, konfigurasikan pengaturan rinci berformat JSON (Proxy, ProxyBypass, AutoconfigUrl, AutoDetect) dengan netsh winhttp set advproxy.²

3.3. Jebakan paling sering: layanan tidak membaca pengaturan IE pengguna

Pola yang paling banyak muncul di lapangan, jika diurutkan waktunya, seperti ini.

1. Pengembang menjalankan alat di PC-nya sendiri → pengaturan proksi per pengguna miliknya (1) berlaku dan berjalan
2. Di produksi, aplikasi dijalankan sebagai layanan Windows (Cara membuat dan mengoperasikan layanan Windows) yang menetap sebagai LocalSystem
3. Pengaturan yang terlihat dari LocalSystem adalah hal lain (pengaturan per pengguna tidak terlihat, pengaturan mesin WinHTTP belum dikonfigurasi = DIRECT) → mencoba menyambung langsung ke API eksternal lalu kehabisan waktu

Bukan “mesinnya sama tetapi tidak berjalan”; meskipun mesinnya sama, jika akun yang menjalankan berbeda, pengaturan proksi yang terlihat juga berbeda. Untuk proses yang berkomunikasi meski pengguna tidak masuk, cara yang benar adalah menyiapkan pengaturan per mesin dalam bentuk yang benar-benar dibaca tumpukan HTTP proses itu. Untuk aplikasi native dan komponen Windows yang memakai WinHTTP, pengaturan WinHTTP lewat netsh berlaku.⁴ Sebaliknya, HttpClient pada .NET (Core dan sesudahnya) tidak membaca pengaturan mesin WinHTTP (lihat bab 5), jadi untuk layanan buatan .NET atur variabel lingkungan sistem (HTTPS_PROXY dan sejenisnya), atau tetapkan secara eksplisit dari pengaturan aplikasi lewat HttpClientHandler.Proxy.

Ada juga kecelakaan arah sebaliknya. Jika proksi statis ditetapkan secara tetap ke perangkat yang bolak-balik antara jaringan internal dan eksternal — seperti laptop — dengan netsh winhttp set proxy, di luar kantor proksi itu tidak terjangkau dan komunikasi pun lumpuh total. Anggap pengaturan statis per mesin sebagai cara yang cocok untuk server yang konfigurasi jaringannya tidak berubah.⁴

4. PAC dan WPAD — isi “konfigurasi otomatis”

4.1. Berkas PAC dan FindProxyForURL

Berkas PAC (Proxy Auto-Configuration) adalah JavaScript (ECMAScript) yang menghitung “proksi mana yang dipakai untuk URL ini”, dan wajib memuat fungsi FindProxyForURL(url, host). Fungsi ini mengembalikan daftar proksi yang harus dipakai, atau menunjukkan dengan nilai kembali khusus (DIRECT) bahwa koneksi langsung tanpa proksi diperbolehkan.⁵

function FindProxyForURL(url, host) {
    // Domain internal dan alamat privat: koneksi langsung
    if (dnsDomainIs(host, ".example.co.jp") ||
        isInNet(host, "10.0.0.0", "255.0.0.0")) {
        return "DIRECT";
    }
    // Selain itu lewat proksi. Jika yang di depan tidak bisa dipakai, jatuh ke berikutnya
    return "PROXY proxy1.example.co.jp:8080; PROXY proxy2.example.co.jp:8080; DIRECT";
}

Dari sini muncul dua konsekuensi praktis.

• Resolusi proksi perlu dilakukan per URL. PAC dapat mengembalikan proksi lain atau koneksi langsung tergantung URL (host), jadi fitur proksi otomatis WinHTTP pun dirancang untuk meneruskan URL tujuan permintaan dan menanyakan ulang setiap kali.⁶ Fakta bahwa “situs lain terlihat di peramban” bukan bukti bahwa API yang bermasalah memakai jalur yang sama.
• DIRECT adalah instruksi “pergi tanpa proksi”. Jika komunikasi yang seharusnya ke tujuan internal tidak muncul di log proksi, curigai dulu bahwa PAC mengembalikan DIRECT (atau cocok dengan daftar bypass).

4.2. Deteksi otomatis lewat WPAD

Jika “Deteksi pengaturan secara otomatis” diaktifkan, lokasi berkas PAC dicari dengan protokol WPAD (Web Proxy Auto-Discovery). Dalam konfigurasi umum, URL PAC didistribusikan dari DHCP, atau host bernama wpad di-resolve lewat DNS, lalu PAC diunduh dari URL seperti http://wpad/wpad.dat.¹⁴

Jadi “deteksi otomatis” bukan sihir; itu mekanisme yang hanya berfungsi di jaringan yang sudah menyiapkan perangkat WPAD di DHCP/DNS. Hanya mengaktifkan deteksi otomatis di jaringan tanpa perangkat itu hanya menambah waktu tunggu kegagalan deteksi.

4.3. Perilaku klien yang tidak bisa membaca PAC

Tidak semua klien dapat mengevaluasi PAC.

• Pengaturan statis netsh winhttp set proxy tidak mengevaluasi PAC.⁴
• Alat bergaya variabel lingkungan HTTP_PROXY pada prinsipnya hanya dapat menuliskan URL proksi tetap (tidak ada tempat untuk menuliskan URL PAC).⁷
• Untuk aplikasi native yang memakai WinHTTP secara langsung, perilakunya bergantung pada cara sesi dibuka. Aplikasi yang membuka sesi dengan WinHttpOpen pada Windows 8.1 atau sesudahnya sambil menetapkan WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY membuat WinHTTP meresolusi secara otomatis, per permintaan, pengaturan proksi sistem/pengguna (termasuk WPAD/PAC).¹⁵ Sebaliknya, jika dibuka dengan WINHTTP_ACCESS_TYPE_DEFAULT_PROXY lama (tidak disarankan sejak 8.1) dan sejenisnya, proksi otomatis tidak terintegrasi ke tumpukan HTTP, dan aplikasi harus sendiri memanggil WinHttpGetProxyForUrl lalu menetapkan hasilnya ke permintaan. Artinya pada aplikasi implementasi lama, PAC bisa ada tetapi tidak terpakai.⁵

“Peramban menuju proksi yang benar lewat PAC, tetapi aplikasi bisnis tidak membaca PAC lalu mencoba koneksi langsung dan gagal” — ini juga ketidaksesuaian yang rutin. Di jaringan yang memakai PAC, perlu diputuskan sarana cadangan berupa pengaturan statis atau variabel lingkungan untuk klien yang tidak bisa membaca PAC.

5. Resolusi proksi .NET — Framework dan Core serta sesudahnya adalah hal berbeda

“Pengaturan proksi mana yang dibaca” aplikasi .NET berbeda bawaannya antara .NET Framework dan .NET (Core dan sesudahnya). Jika keduanya dicampur, investigasi aplikasi .NET 8 dengan pengetahuan era Framework akan meleset.

5.1. .NET Framework — bawaan Opsi Internet, ditimpa dengan defaultProxy

Di .NET Framework, HttpWebRequest dan HttpClient (yang menumpang di atasnya) memakai proksi bawaan selama Proxy tidak ditetapkan secara eksplisit. Proksi bawaan ditentukan oleh kombinasi pengaturan internet sistem (pengaturan WinINET akun yang sedang menjalankan) dan berkas konfigurasi, dan pengaturan berkas konfigurasi yang diutamakan.⁸

Bawaan ini dapat dikendalikan dengan elemen system.net/defaultProxy di app.config (atau machine.config).⁹

<configuration>
  <system.net>
    <!-- useDefaultCredentials: apakah kredensial bawaan dikirim ke proksi berautentikasi -->
    <defaultProxy enabled="true" useDefaultCredentials="true">
      <proxy usesystemdefault="true"
             proxyaddress="http://proxy.example.co.jp:8080"
             bypassonlocal="true" />
      <bypasslist>
        <add address="[a-z]+\.example\.co\.jp$" />
      </bypasslist>
    </defaultProxy>
  </system.net>
</configuration>

Jika elemen defaultProxy dibiarkan kosong, pengaturan sistem (Opsi Internet) yang dipakai; jika proxyaddress dan sejenisnya ditulis, itulah yang diutamakan. Dari program, bawaan yang sama dapat diganti lewat WebRequest.DefaultWebProxy.⁹⁸

Jebakan di bagian 3.3 berlaku di sini juga. Karena bawaannya adalah “Opsi Internet akun yang sedang menjalankan”, aplikasi .NET Framework yang berjalan di bawah akun layanan membaca pengaturan yang berbeda (sering kali kosong) dari yang terlihat di desktop administrator.

5.2. .NET (Core dan sesudahnya) — variabel lingkungan dulu, lalu pengaturan pengguna OS

HttpClient pada .NET (Core dan sesudahnya) punya properti statis HttpClient.DefaultProxy. Selama proksi tidak ditetapkan secara eksplisit di handler, semua instans HttpClient memakainya. Aturan inisialisasi di Windows adalah “baca variabel lingkungan; jika tidak didefinisikan, baca pengaturan proksi pengguna”.⁷

Variabel lingkungan yang dipakai adalah sebagai berikut.⁷

Ada tiga poin yang perlu diperhatikan.

• Jika salah satu dari HTTP_PROXY, HTTPS_PROXY, atau ALL_PROXY didefinisikan, itu diutamakan atas pengaturan proksi sisi OS. Hanya mendefinisikan NO_PROXY tidak mengonfigurasi proksi lewat variabel lingkungan; di Windows, pengaturan proksi pengguna OS tetap dipakai. “Pengaturan yang tidak terlihat” — misalnya HTTPS_PROXY tertinggal sebagai variabel lingkungan sistem setelah pengujian, atau templat CI/CD yang menyuntikkannya — menjadi sarang kecelakaan.
• NO_PROXY tidak mendukung wildcard (*). Untuk mencocokkan subdomain, awali dengan titik (.example.com cocok dengan www.example.com, tetapi tidak dengan example.com itu sendiri).⁷
• Di luar Windows (kontainer Linux dan sejenisnya), jika variabel lingkungan tidak didefinisikan, inisialisasi dilakukan tanpa proksi. Bahwa aplikasi yang sama punya perilaku bawaan berbeda di Windows dan Linux perlu diperiksa saat migrasi ke kontainer.⁷

5.3. Penetapan eksplisit — HttpClientHandler.Proxy dan UseProxy

Pada kedua runtime, prioritas tertinggi adalah penetapan eksplisit ke handler. Menetapkan HttpClientHandler.Proxy mengalahkan pengaturan OS maupun berkas konfigurasi, dan UseProxy = false membuat proksi sama sekali tidak dipakai.¹⁴

using System.Net;

// Pakai secara eksplisit proksi yang dibaca dari pengaturan aplikasi
var handler = new HttpClientHandler
{
    Proxy = new WebProxy("http://proxy.example.co.jp:8080")
    {
        BypassProxyOnLocal = true,
        BypassList = new[] { @"^intra\.example\.co\.jp$" },
        UseDefaultCredentials = true // Jika proksi berautentikasi, jawab dengan kredensial akun yang menjalankan
    },
    UseProxy = true
};
var client = new HttpClient(handler);

// Klien yang sama sekali tidak memakai proksi (untuk API internal, koneksi langsung)
var directHandler = new HttpClientHandler { UseProxy = false };
var directClient = new HttpClient(directHandler);

Selain itu, jika tidak ada penetapan eksplisit dan pengaturan OS yang diikuti, bypass otomatis untuk tujuan lokal punya aturan. Nama datar tanpa titik, alamat loopback, dan tujuan yang cocok dengan sufiks domain mesin sendiri dapat dianggap “lokal”.¹⁴ Gejala seperti “perilaku berubah jika IP ditetapkan langsung” atau “begitu dijadikan FQDN, tiba-tiba lewat proksi” kadang disebabkan penilaian ini.

Urutan prioritas, jika dirapikan, sebagai berikut.

6. Proksi berautentikasi — 407 adalah kesalahan autentikasi “proksi”

6.1. Jangan campur 407 dan 401

Ketika mencoba melewati proksi yang menuntut autentikasi, proksi mengembalikan kode status 407 (Proxy Authentication Required) beserta header Proxy-Authenticate yang mencantumkan skema yang tersedia. Itu berbeda dari permintaan autentikasi server tujuan (401 dan WWW-Authenticate); pihak yang menerima kredensial pun berbeda, dan tempat mengaturnya pun berbeda.¹⁰

Skema autentikasi mencakup Basic, yang mengirim nama pengguna dan kata sandi apa adanya, serta skema challenge/response seperti Negotiate (Kerberos/NTLM). Pada skema challenge/response, kata sandi itu sendiri tidak mengalir di jaringan; autentikasi selesai lewat beberapa kali tukar pesan.¹⁰ Mekanisme “jatuh” ke skema mana dibahas lebih rinci di “NTLM dan Kerberos dalam gambar”.

6.2. Cara mengirim kredensial di .NET

Jika yang dipakai adalah proksi bawaan dari pengaturan OS dan hanya autentikasi yang ingin diloloskan, gunakan HttpClientHandler.DefaultProxyCredentials. Ini adalah kredensial yang dikirim ke proksi bawaan itu ketika UseProxy = true dan Proxy = null (= proksi bawaan sistem).¹¹

using System.Net;

var handler = new HttpClientHandler
{
    UseProxy = true,   // Nilai bawaan. Digabung dengan Proxy null, memakai proksi bawaan sistem
    Proxy = null,
    // Jawab 407 dengan kredensial akun yang menjalankan (pengguna yang masuk atau akun layanan)
    DefaultProxyCredentials = CredentialCache.DefaultCredentials
};
var client = new HttpClient(handler);

Jika proksi ditetapkan secara eksplisit, kredensial diletakkan di sisi WebProxy. Pada banyak skenario klien, yang disarankan bukan nama pengguna dan kata sandi individual, melainkan kredensial bawaan pengguna yang sedang masuk; itulah WebProxy.UseDefaultCredentials = true.¹²

6.3. Masalah 407 pada akun layanan

Akun yang menjalankan proses berlaku di sini juga. “Kredensial bawaan” adalah kredensial akun yang menjalankan proses itu. Jika dijalankan sebagai pengguna interaktif, autentikasi ke proksi dilakukan sebagai pengguna itu; jika dijalankan sebagai layanan LocalSystem, sebagai akun komputer.

• Jika proksi mengautentikasi pengguna lewat Active Directory, akun komputer atau akun lokal tidak dapat diautentikasi, sehingga 407 berlanjut begitu dijadikan layanan
• Sebaliknya, ada juga lingkungan yang menyiapkan pengecualian autentikasi untuk layanan di sisi proksi (per IP sumber atau per akun)

Jadi investigasi 407 tidak tertutup pada “pengaturan aplikasi” saja; itu satu paket dengan konfirmasi desain infrastruktur: apakah proksi dapat mengautentikasi akun yang menjalankan. Untuk aplikasi yang akan dijadikan layanan, salah satu dari berikut perlu diputuskan sejak tahap desain: jalankan dengan akun layanan domain (gMSA dan sejenisnya), sediakan pengecualian autentikasi di sisi proksi, atau dirikan proksi relay internal yang tidak menuntut autentikasi.

Selain itu, ada cara menyematkan kredensial ke variabel lingkungan seperti HTTP_PROXY=http://user:pass@proxy:8080⁷, tetapi kata sandi plaintext terekspos di variabel lingkungan (= informasi proses), jadi tidak disarankan untuk operasi jangka panjang.

7. HTTPS dan proksi — terowongan CONNECT dan inspeksi TLS

7.1. HTTPS melewati proksi lewat “terowongan”

Jika proksi dipakai untuk komunikasi HTTPS, klien pertama-tama mengirim permintaan CONNECT host-tujuan:443 ke proksi, lalu proksi membuka terowongan TCP. Jika berhasil, proksi mengembalikan 200, dan setelah itu klien serta server tujuan melakukan handshake TLS di dalam terowongan itu. Jika terowongan tidak terbuka, proksi mengembalikan 407 (permintaan autentikasi), 502, dan sejenisnya.¹⁶

Dalam model ini, proksi tidak dapat membaca isi terowongan (HTTPS terenkripsi). Yang tertinggal di log proksi hanya nama host tujuan dan keberhasilan koneksi; jalur URL tidak terlihat — itulah perilaku proksi “passthrough”.

7.2. Proksi inspeksi TLS dan kesalahan sertifikat

Di sisi lain, di kalangan proksi produk keamanan ada tipe inspeksi TLS (dekripsi SSL, break and inspect) yang mengakhiri TLS di tengah jalan, memeriksa isi, lalu mengenkripsi ulang dan meneruskan. Pada cara ini, sertifikat server yang disajikan ke klien bukan yang asli, melainkan diganti dengan sertifikat yang ditandatangani ulang oleh CA proksi itu sendiri.¹³

Karena itu, prasyarat agar konfigurasi ini berdiri adalah “sertifikat CA proksi didistribusikan ke akar terpercaya semua klien”. Di mesin yang belum menerimanya, atau di runtime yang tidak melihat penyimpanan sertifikat Windows (alat dengan toko kepercayaan sendiri), terjadi kesalahan validasi sertifikat. Di .NET, gejalanya tipikal muncul sebagai HttpRequestException dan AuthenticationException di dalamnya (pesan semacam sertifikat jarak jauh tidak valid).

Prinsip penanganan sebagai berikut.

• Distribusikan sertifikat CA internal ke penyimpanan “Otoritas Sertifikasi Akar Terpercaya” komputer lokal. Pembagian pemakaian antara penyimpanan pengguna dan penyimpanan komputer ada di “Panduan praktis penyimpanan sertifikat Windows”.
• Jangan menonaktifkan validasi sertifikat di kode. Penghindaran seperti selalu mengembalikan true di ServerCertificateCustomValidationCallback membuat aplikasi rentan: begitu keluar ke jaringan luar, serangan man-in-the-middle tidak terdeteksi.
• Komunikasi yang memakai certificate pinning pada dasarnya tidak dapat diinspeksi. Koneksi yang di-pin, seperti komponen Windows yang memverifikasi sertifikat Microsoft tertentu, gagal pada saat proksi mengganti sertifikat; tidak ada jalan pintas, dan pengaturan pengecualian diperlukan.⁴ Untuk lalu lintas ke SaaS seperti Microsoft 365, Microsoft sendiri merekomendasikan pengecualian dari dekripsi dan inspeksi di lapisan jaringan.¹³

Gejala “semua situs internal terlihat, tetapi hanya layanan cloud tertentu yang membuat aplikasi mengeluarkan kesalahan sertifikat” — curigai dulu kombinasi daftar pengecualian inspeksi TLS dan pinning.

8. Prosedur isolasi — identifikasi penyebab dalam 5 langkah

Investigasi “tidak tersambung” dilanjutkan secara mekanis dalam urutan berikut.

Pengambilan pada (2) dapat dilakukan sekaligus dengan PowerShell.

# (1) Pengaturan per pengguna (WinINET) — perhatikan bahwa yang dibaca adalah HKCU akun yang menjalankan
Get-ItemProperty 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings' |
    Select-Object ProxyEnable, ProxyServer, ProxyOverride, AutoConfigURL

# (2) Pengaturan mesin (WinHTTP)
netsh winhttp show proxy

# (3) Variabel lingkungan
Get-ChildItem env: | Where-Object Name -match 'proxy'

Ada beberapa kiat praktis.

• Pada uji reproduksi (1), sadari jalur pengaturan yang dibaca alat. curl.exe yang disertakan Windows dapat menetapkan proksi secara eksplisit dengan -x http://proxy:8080, dan untuk validasi TLS biasanya memakai penyimpanan sertifikat OS (Schannel). Invoke-WebRequest di Windows PowerShell 5.1 mengikuti resolusi sisi .NET Framework (bawaan Opsi Internet); di PowerShell 7 mengikuti sisi .NET (variabel lingkungan diutamakan). Fakta bahwa “curl tembus tetapi aplikasi tidak” itu sendiri adalah petunjuk ketidaksesuaian jalur pengaturan.
• Jika target pada (3) adalah layanan, periksa ulang (1) dan (2) dengan akun yang sama dengan layanan. Pemeriksaan di sesi administrator sendiri bukan bukti tampilan yang dilihat LocalSystem.
• Pada klasifikasi kesalahan (4), jika 407 jadikan bab 6 (autentikasi) kandidat pertama, jika kesalahan sertifikat bab 7 (inspeksi TLS), jika kehabisan waktu “proksi tidak terjangkau” (jalur, resolusi nama, firewall). Pola di mana penyebabnya bukan proksi melainkan aturan inbound Windows Firewall dibahas di “Windows Firewall dan aplikasi bisnis”.
• Jika sampai (5) tidak ada jejak di log proksi, komunikasi tidak sampai ke proksi. Curigai penilaian DIRECT di PAC, daftar bypass, atau variabel lingkungan yang lupa dihapus, dan jika perlu konfirmasi tujuan aktual dengan packet capture (“Praktik packet capture di Windows — pembagian pakai pktmon, netsh trace, dan Wireshark”).

9. Rekomendasi desain — jadikan aplikasi yang “bisa diatur” proksinya

Jika prosedur investigasi dibalik, itu menjadi pedoman desain di sisi aplikasi. Untuk aplikasi Windows yang dikirim ke lingkungan dengan proksi internal, berikut yang disarankan.

1. Buat proksi dapat ditetapkan secara eksplisit di pengaturan aplikasi. Bawaannya “ikuti pengaturan OS”. Di banyak lingkungan bawaan sudah cukup; hanya di lingkungan pengecualian — PAC tidak bisa dibaca, berjalan sebagai layanan, atau konfigurasi proksi khusus — sediakan cara menetapkan URL proksi, daftar bypass, dan “jangan pakai proksi” lewat berkas pengaturan. HttpClientHandler.Proxy/UseProxy di bagian 5.3 adalah titik implementasinya.¹⁴
2. Untuk komunikasi ke tujuan internal (API, DB, server lisensi, dan sejenisnya), tuliskan secara eksplisit perlakuan sebagai pengecualian proksi. Jadikan bentuk yang bisa ditulis di prosedur instalasi: dikecualikan lewat DIRECT di PAC, daftar bypass, atau NO_PROXY. Aturan pencocokan NO_PROXY (wildcard tidak didukung, arti titik di depan) sering disalahpahami, jadi sertakan contoh.⁷
3. Rancang batas waktu dan retry dengan asumsi lewat proksi. Jika proksi mati atau berhenti di autentikasi, implementasi yang menunggu batas waktu bawaan yang panjang membuat UI dan operasi ikut macet. Pisahkan batas waktu koneksi agar lebih pendek, dan batasi retry pada permintaan yang idempoten (rincian desain di “Jangan bungkus HttpClient dengan using”).
4. Keluarkan ke log “proksi mana yang dipakai”. Agar pertanyaan pertama investigasi gangguan bisa dijawab oleh aplikasi itu sendiri.

Log pada poin 4 sudah efektif hanya dengan mencatat hasil resolusi seperti berikut. Poinnya adalah menurunkan jalur dari pengaturan (handler) yang benar-benar dipakai untuk mengonfigurasi klien. Jika HttpClient.DefaultProxy langsung dicatat ke log, ketika Proxy ditetapkan secara eksplisit di handler atau UseProxy = false, nilai yang tercatat bisa menyimpang dari jalur aktual.

using System.Net.Http;

// handler adalah instans yang sama yang dipakai untuk membuat HttpClient
// Jika UseProxy=false, selalu koneksi langsung. Jika ada penetapan eksplisit, itulah yang dipakai; jika tidak, DefaultProxy
var effectiveProxy = handler.UseProxy
    ? handler.Proxy ?? HttpClient.DefaultProxy
    : null;
var target = new Uri("https://api.example.com/v1/orders");
var route = effectiveProxy is null || effectiveProxy.IsBypassed(target)
    ? "DIRECT"
    : effectiveProxy.GetProxy(target)?.ToString() ?? "DIRECT";
logger.LogInformation("Pengiriman HTTP {Target} jalur {Route} akun yang menjalankan {User}",
    target, route, Environment.UserName);

Jika sekali saat mulai dijalankan dicatat “jalur” dan “akun yang menjalankan” untuk tujuan utama, isolasi (1)–(3) di bab 8 selesai hanya dengan melihat log. Ketika dikatakan “berjalan di peramban, tetapi…”, sisi aplikasi bisa menjawab “saya memakai pengaturan ini, jalur ini” — itulah syarat aplikasi yang kuat terhadap gangguan proksi.

10. Ringkasan

• Pengaturan proksi Windows terpecah ke tiga jalur — pengaturan WinINET per pengguna, pengaturan mesin WinHTTP, dan variabel lingkungan — dan mana yang dibaca ditentukan oleh aplikasi (tumpukan HTTP-nya) serta akun yang menjalankan.
• WinINET untuk aplikasi interaktif dan tidak didukung di layanan; pemakaian layanan diemban WinHTTP (netsh winhttp). Untuk “berjalan secara manual, tetapi gagal sebagai layanan”, curigai dulu perbedaan akun yang menjalankan.
• netsh winhttp set proxy adalah pengaturan statis; tidak menangani PAC, deteksi otomatis, atau autentikasi. Di jaringan yang memakai PAC, perlu diputuskan perlakuan klien yang tidak bisa membaca PAC.
• FindProxyForURL di PAC mengembalikan proksi atau DIRECT per URL. WPAD hanya berfungsi di jaringan yang punya perangkat DHCP/DNS.
• Bawaan .NET Framework adalah Opsi Internet akun yang menjalankan (ditimpa dengan defaultProxy); .NET (Core dan sesudahnya) berurutan variabel lingkungan → pengaturan proksi pengguna. Penetapan eksplisit (HttpClientHandler.Proxy) selalu prioritas tertinggi.
• 407 adalah kesalahan autentikasi proksi; pada aplikasi yang berjalan di bawah akun layanan, “kredensial bawaan” menjadi milik orang lain — itu penyebab tipikal.
• Proksi inspeksi TLS mensyaratkan distribusi sertifikat CA internal; jawaban yang benar untuk kesalahan sertifikat bukan menonaktifkan validasi, melainkan distribusi ke penyimpanan sertifikat. Komunikasi yang di-pin perlu dikecualikan.
• Isolasi dilakukan secara mekanis: “reproduksi → pengambilan tiga jalur pengaturan → identifikasi akun yang menjalankan → klasifikasi kesalahan → log proksi”. Di sisi aplikasi, desain terbaik untuk pencegahan adalah “proksi dapat diatur, dan jalur yang dipakai dicatat di log”.

Lain kali, jika ada konsultasi “hanya aplikasi bisnis yang tidak tersambung”, tanyakan balik dulu seperti ini.

Aplikasi itu berjalan di bawah akun siapa, dan dari tiga jalur pengaturan proksi, mana yang dibacanya?

Satu pertanyaan itu saja sudah mengubah pintu masuk investigasi secara besar.

Artikel terkait

• Jangan bungkus HttpClient dengan using — praktik komunikasi HTTP aplikasi bisnis C# (pola pembuatan, batas waktu, retry)
• Praktik packet capture di Windows — pembagian pakai pktmon, netsh trace, dan Wireshark
• Windows Firewall dan aplikasi bisnis — daftarkan aturan inbound lewat installer
• Cara membuat dan mengoperasikan layanan Windows — dari pembagian pakai dengan Penjadwal Tugas hingga menjadikan BackgroundService sebagai layanan
• NTLM dan Kerberos dalam gambar — mengapa autentikasi “jatuh” ke NTLM
• Panduan praktis penyimpanan sertifikat Windows — masukkan ke pengguna atau ke komputer

Area konsultasi terkait

Di 合同会社小村ソフト, kami menangani investigasi gangguan komunikasi aplikasi Windows di lingkungan proksi internal, proksi berautentikasi, dan inspeksi TLS — misalnya “berjalan di mesin pengembangan, tetapi tidak berkomunikasi di jaringan pelanggan” atau “setelah dijadikan layanan, API eksternal tidak terjangkau” — serta konsultasi desain komunikasi aplikasi bisnis yang mengasumsikan lingkungan proksi (item pengaturan, batas waktu, desain log). Memulai dari merapikan prosedur reproduksi gejala dan cara pengambilan log pun tidak masalah.

• Pengembangan aplikasi Windows
• Investigasi gangguan dan analisis penyebab
• Konsultasi teknis dan tinjauan desain
• Hubungi kami

Tautan referensi

Artikel terkait

Artikel terbaru dengan tag yang sama untuk mendalami topik-topik terdekat.

Topik terkait

Halaman-halaman ini menempatkan topik dalam konteks layanan dan keputusan yang lebih luas.

Layanan yang terkait dengan topik ini

Artikel ini berkaitan langsung dengan layanan berikut.

Pertanyaan yang sering diajukan

Pertanyaan yang sering muncul dalam konsultasi tentang topik artikel ini.

Peramban tersambung, tetapi hanya aplikasi bisnis yang tidak melewati proksi internal. Mengapa?

Peramban membaca pengaturan proksi per pengguna WinINET, tetapi aplikasi bisnis tidak selalu membaca pengaturan yang sama. Aplikasi yang berjalan sebagai layanan Windows, atau di bawah akun lain, merujuk pengaturan yang terlihat dari akun itu, pengaturan mesin WinHTTP, atau variabel lingkungan. Identifikasi dulu akun yang menjalankan proses, lalu periksa pengaturan proksi yang terlihat dari akun itu — baik dengan netsh winhttp show proxy maupun di pengaturan pengguna. Jika gejala bisa direproduksi dengan curl.exe atau alat serupa pada akun yang sama di mesin yang sama, itu menandakan ketidaksesuaian antar jalur konfigurasi, bukan masalah khusus aplikasi.

netsh winhttp set proxy sudah diatur, tetapi komunikasi aplikasi tidak berubah. Mengapa?

Yang diatur netsh winhttp adalah bawaan mesin WinHTTP. Itu tidak memengaruhi peramban atau aplikasi interaktif yang membaca WinINET, maupun HttpClient .NET (Core dan sesudahnya) yang lebih mengutamakan variabel lingkungan. netsh winhttp set proxy juga pengaturan statis; tidak menangani konfigurasi otomatis PAC, deteksi otomatis, atau autentikasi proksi. Pastikan dulu tumpukan HTTP mana yang dipakai aplikasi target, dan dari jalur konfigurasi mana ia meresolusi proksi.

Pengaturan proksi mana yang dibaca aplikasi .NET?

.NET Framework secara bawaan memakai Opsi Internet (setara WinINET) akun yang sedang menjalankan proses, dan dapat ditimpa dengan elemen system.net/defaultProxy di app.config. HttpClient pada .NET (Core dan sesudahnya) membaca variabel lingkungan seperti HTTP_PROXY, HTTPS_PROXY, dan NO_PROXY lebih dulu, lalu jika tidak didefinisikan jatuh ke pengaturan proksi pengguna Windows. Pada kedua kasus, penetapan eksplisit HttpClientHandler.Proxy menjadi prioritas tertinggi. Urutan resolusi bawaan berbeda antara Framework dan Core serta sesudahnya, jadi perilaku proksi perlu diperiksa ulang saat migrasi.

Apa yang harus diperiksa ketika 407 Proxy Authentication Required dikembalikan?

407 adalah tanda bahwa proksi itu sendiri menuntut autentikasi; itu berbeda dari kesalahan autentikasi server tujuan (401). Pastikan dulu skema yang diminta proksi (Negotiate, NTLM, Basic) dari header Proxy-Authenticate, lalu di .NET kirim kredensial dengan HttpClientHandler.DefaultProxyCredentials atau WebProxy.UseDefaultCredentials. Pada aplikasi yang berjalan di bawah akun layanan, "kredensial bawaan" menjadi milik akun layanan itu, sehingga pola tipikalnya berhasil untuk pengguna interaktif lalu 407 begitu dijadikan layanan. Periksa juga di log sisi proksi sebagai siapa proses itu terautentikasi.

Proksi inspeksi TLS menimbulkan kesalahan sertifikat. Bolehkah validasi sertifikat dinonaktifkan?

Menonaktifkannya tidak disarankan. Proksi inspeksi TLS mendekripsi komunikasi lalu menyajikan ke klien sertifikat yang ditandatangani ulang oleh CA-nya sendiri, sehingga validasi gagal jika sertifikat CA itu tidak ada di akar terpercaya. Perbaikan yang benar adalah mendistribusikan sertifikat CA internal ke penyimpanan sertifikat Windows (biasanya Otoritas Sertifikasi Akar Terpercaya komputer lokal). Menonaktifkan validasi di kode berarti serangan man-in-the-middle tidak terdeteksi ketika aplikasi dipakai di jaringan luar, dan kerentanan tetap ada.

Profil penulis

Halaman perkenalan penulis artikel.

Go Komura

Direktur KomuraSoft LLC

Berspesialisasi dalam pengembangan perangkat lunak Windows, konsultasi teknis, dan investigasi bug, terutama pada proyek dengan sistem yang sudah ada dan bug yang sulit direproduksi.