SSO X-Guard untuk aplikasi ASP Classic
Panduan ini untuk developer aplikasi ASP Classic (VBScript di IIS) yang ingin login lewat SSO X-Guard organisasi mereka. Semua kode ada di folder sso/ (unduh ZIP, atau ambil per berkas di daftar berkas), siap disalin, dan tidak butuh DLL, komponen COM tambahan, .NET, atau paket apa pun. Yang dipakai hanya yang sudah ada di Windows: VBScript, JScript, dan MSXML.
Hasil akhirnya:
- Halaman login aplikasi punya tombol Masuk dengan X-Guard. Login password lama boleh tetap ada selama masa transisi.
- Pengguna mengisi email dan password di halaman login organisasi di X-Guard, bukan di aplikasi Anda. Aplikasi tidak pernah melihat password.
- X-Guard memberi tahu aplikasi siapa penggunanya. Hak akses (role) tetap diatur di aplikasi Anda, seperti sekarang.
- Opsional: X-Guard mengabari aplikasi lewat webhook saat pengguna dinonaktifkan, dihapus, atau aksesnya dicabut.
Urutan kerja:
| Langkah | Yang dikerjakan | Bagian |
|---|---|---|
| 1 | Pastikan server memenuhi syarat | Syarat server |
| 2 | Daftarkan aplikasi di konsol X-Guard, simpan client ID dan secret | Daftarkan aplikasi |
| 3 | Salin folder sso/ ke situs | Pasang file |
| 4 | Buka halaman uji koneksi | Uji koneksi |
| 5 | Sambungkan ke database dan halaman aplikasi | Sambungkan ke aplikasi |
| 6 | Opsional: pasang webhook | Webhook |
| 7 | Uji dari awal sampai akhir | Daftar uji |
Kalau server Anda Windows Server 2012 atau lebih lama, kerjakan Syarat server dan Uji koneksi lebih dulu. Di situlah risiko terbesarnya.
Cara kerjanya
X-Guard memakai standar OpenID Connect dengan alur Authorization Code dan PKCE. Aplikasi menitipkan pengguna ke halaman login organisasi di X-Guard, menerima kembali sebuah kode, lalu menukar kode itu (dari server ke server) dengan data pengguna.
text
Browser pengguna Aplikasi ASP X-Guard
| | |
| 1. klik Masuk | |
|-------------------------->| login.asp |
| | buat state, nonce, PKCE, |
| | simpan di Session |
| 2. dialihkan ke X-Guard | |
|<--------------------------| |
|------------------------------------------------------>|
| | 3. pengguna login
| 4. dialihkan kembali: callback.asp?code=...&state=... |
|<------------------------------------------------------|
|-------------------------->| callback.asp |
| | cocokkan state |
| | 5. tukar code + secret |
| | + code_verifier |
| |-------------------------->|
| |<--------------------------|
| | id_token (data user) |
| | 6. periksa id_token, |
| | cari user di database, |
| | isi Session |
| 7. masuk ke aplikasi | |
|<--------------------------| |Langkah 5 berjalan dari server IIS Anda ke X-Guard lewat HTTPS, bukan lewat browser. Karena itu server IIS harus bisa membuka alamat X-Guard organisasi Anda, dan inilah yang sering jadi kendala di Windows lama.
| Istilah | Artinya |
|---|---|
| Issuer | Alamat X-Guard organisasi Anda, mis. https://nama-organisasi.x-guard.online, atau domain sendiri |
client_id | Pengenal aplikasi Anda di X-Guard |
client_secret | Kata sandi aplikasi Anda ke X-Guard. Hanya boleh ada di server |
code | Kode sekali pakai dari X-Guard, dibawa browser ke callback.asp |
state | Teks acak untuk memastikan callback berasal dari proses login yang dimulai browser ini |
nonce | Teks acak yang dikembalikan X-Guard di dalam id_token, supaya token lama tidak bisa dipakai ulang |
| PKCE | Pasangan code_verifier dan code_challenge: kode yang bocor tidak bisa ditukar tanpa verifier |
id_token | Data pengguna dari X-Guard (nama, email, dll.) |
sub | ID pengguna di X-Guard. Tidak pernah berubah, walaupun email berubah |
Syarat server
Aplikasi harus bisa dibuka lewat HTTPS
Alamat callback wajib https://. Pengecualian hanya http://localhost atau http://127.0.0.1 untuk uji di mesin sendiri. Aplikasi intranet tetap bisa dipakai: X-Guard tidak pernah memanggil aplikasi Anda saat login. Yang perlu bisa membuka alamat aplikasi hanyalah browser pengguna.
Server IIS harus bisa keluar ke X-Guard
Server perlu akses keluar ke alamat X-Guard organisasi Anda di port 443. Kalau jaringan memakai proxy, atur untuk WinHTTP (lihat Masalah umum). Pengaturan proxy Internet Explorer tidak berlaku di sini.
Versi Windows
X-Guard (*.x-guard.online) hanya menerima TLS 1.2 atau 1.3, dengan sertifikat ECDSA dari Let's Encrypt (rantai ke ISRG Root X2). Pada TLS 1.2 yang diterima hanya cipher ECDHE-ECDSA. Banyak contoh kode ASP lama gagal di titik ini.
| Windows Server | Status | Yang perlu dilakukan |
|---|---|---|
| 2016 atau lebih baru | Cipher tersedia | Tidak ada, langsung ke uji koneksi |
| 2012 R2 | Cipher tersedia | Pastikan update KB2919355 terpasang |
| 2012 | Perlu patch | Pasang KB3140245, lalu tambah registry di bawah |
| 2008 R2 SP1 | Perlu patch | Pasang KB3140245, tambah registry di bawah, dan aktifkan TLS 1.2 |
| 2008 (non-R2), 2003 | Tidak tercakup | Lihat Kalau server tidak bisa diperbarui |
Tabel ini berdasarkan dokumentasi Microsoft. Hasil akhirnya ditentukan oleh halaman uji di bagian 5, bukan oleh tabel ini. Organisasi yang memakai domain sendiri bisa mendapat sertifikat yang berbeda; halaman uji juga yang menjawabnya.
Registry untuk Server 2012 dan 2008 R2 SP1 (setelah KB3140245 terpasang). Jalankan di Command Prompt sebagai Administrator:
bat
reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings\WinHttp" /v DefaultSecureProtocols /t REG_DWORD /d 0x800 /f
reg add "HKLM\SOFTWARE\Wow6432Node\Microsoft\Windows\CurrentVersion\Internet Settings\WinHttp" /v DefaultSecureProtocols /t REG_DWORD /d 0x800 /fTambahan untuk Server 2008 R2 SP1:
bat
reg add "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client" /v DisabledByDefault /t REG_DWORD /d 0 /fRestart server setelah mengubah registry.
Kalau server tidak bisa diperbarui
Yang butuh TLS modern dari server hanya penukaran code (langkah 5). Kalau server tidak bisa diperbarui, jalan keluarnya proxy kecil di mesin lain yang lebih baru, yang meneruskan panggilan itu ke X-Guard. XG_TOKEN_URL di xg_config.asp sengaja dipisah untuk keperluan ini.
Pengaturan lain
- Session ASP harus aktif. Di IIS Manager: ASP > Session Properties > Enable Session State = True.
- Jam server harus akurat. Selisih dengan X-Guard tidak boleh lebih dari 2 menit, atau login ditolak.
- Satu server, atau sticky session. Session ASP tersimpan di memori satu server.
Daftarkan aplikasi di konsol X-Guard
Admin organisasi masuk ke konsol X-Guard, buka Aplikasi, lalu Tambah aplikasi:
| Isian | Isi |
|---|---|
| Nama aplikasi | Tampil di halaman login, mis. Aplikasi Keuangan |
| Jenis | Web (aplikasi dengan server) |
| Alamat callback | https://keuangan.contoh.co.id/sso/callback.asp |
| Alamat sesudah logout | https://keuangan.contoh.co.id/sso/keluar-selesai.asp |
| Alamat back-channel logout | Kosongkan: ASP Classic tidak bisa memeriksa tanda tangannya (lihat Fitur yang sengaja tidak dipakai) |
| Autentikasi di endpoint token | Bawaan (client_secret_basic) |
Sesudah disimpan, konsol menampilkan client ID dan client secret. Secret hanya tampil sekali dan setara dengan password: salin langsung ke xg_config.asp, jangan lewat grup chat atau email biasa. Kalau hilang atau bocor, buat secret baru dari rincian aplikasi; secret lama langsung tidak berlaku.
Issuer organisasi Anda tampil di rincian aplikasi, di panel Kredensial.
Bila aplikasi hanya untuk sebagian pengguna, atur di panel Akses pengguna pada rincian aplikasi. Pengguna lain ditolak di halaman X-Guard.
Pasang file
Unduh x-guard-sdk-asp-classic.zip dan salin folder sso/ di dalamnya ke root situs.
| File | Isi | Perlu diubah? |
|---|---|---|
xg_config.asp | Client ID, secret, alamat | Ya |
xg_aplikasi.asp | Mencari pengguna di database Anda, dan menerima event webhook | Ya |
xg_lib.asp | Seluruh logika SSO | Tidak |
login.asp | Memulai login | Tidak |
callback.asp | Menerima pengguna kembali dari X-Guard | Tidak |
logout.asp | Keluar dari aplikasi dan X-Guard | Tidak |
keluar-selesai.asp | Halaman setelah logout | Boleh dipercantik |
webhook.asp | Menerima event dari X-Guard (opsional) | Tidak |
cek-koneksi.asp | Halaman uji. Hapus setelah selesai | Tidak |
Kalau aplikasi berada di virtual directory (mis. /keuangan/sso/), sesuaikan #include virtual di semua file, serta XG_LOGIN_PATH dan alamat di xg_config.asp.
Di xg_config.asp, ganti nama-organisasi di empat alamat X-Guard dengan alamat organisasi Anda (atau domain sendiri). Nilai Const di VBScript harus teks utuh, jadi keempatnya ditulis lengkap.
Uji koneksi
Isi xg_config.asp, lalu buka https://aplikasi-anda/sso/cek-koneksi.asp. Hasil yang diharapkan:
text
[INFO] Sesi ASP: 123456789
[INFO] Jam server (detik Unix): 1794200000
[OK] Pembuat kode acak (Scriptlet.TypeLib)
[OK] SHA-256 (PKCE dan tanda tangan webhook)
[OK] HTTPS ke X-Guard dan pembacaan JSON
[OK] Alamat login, token, dan logout
[OK] Jam server (selisih 1 detik)
[OK] Client ID dan secret diterima X-Guard
[INFO] Webhook tidak dipakai (XG_WEBHOOK_SECRET kosong)Jangan lanjut sebelum semua baris OK. Kalau ada yang gagal, lihat Masalah umum.
Sambungkan ke aplikasi
Tambah kolom di tabel user
sql
ALTER TABLE users ADD xguard_sub VARCHAR(64) NULL;
CREATE UNIQUE INDEX ux_users_xguard_sub ON users (xguard_sub) WHERE xguard_sub IS NOT NULL;Sesuaikan xg_aplikasi.asp
xgLoginLokal(xgSub, email, nama, emailTerverifikasi) dipanggil sesudah X-Guard memastikan identitas pengguna. Contohnya:
- Mencari pengguna lewat
xguard_sub. - Bila belum ketemu (login pertama), mencari lewat email lalu mengisi
xguard_sub, hanya bila email terverifikasi. - Bila tetap tidak ketemu, menolak dengan pesan.
- Mengisi
Session.
Ganti APP_DB_CONN, nama tabel dan kolom, serta Session("user_id") dan Session("user_nama") dengan nama Session yang sama persis dengan yang diisi halaman login lama. Dengan begitu seluruh halaman aplikasi langsung mengenali pengguna.
Tombol login dan logout
html
<a href="/sso/login.asp?next=/">Masuk dengan X-Guard</a>
<a href="/sso/logout.asp">Keluar</a>next adalah tujuan setelah login, dan hanya boleh berupa path di aplikasi ini.
Pemeriksaan login di tiap halaman
Selama masa transisi, tidak ada yang perlu diubah: xgLoginLokal mengisi Session yang sama dengan login lama.
Setelah semua pengguna lewat X-Guard, ganti isi file pemeriksaan login yang sudah ada (biasanya satu include seperti cek_login.asp) dengan:
vb
<!--#include virtual="/sso/xg_config.asp"-->
<!--#include virtual="/sso/xg_lib.asp"-->
<% xgWajibLogin False %>Untuk halaman yang dipanggil lewat AJAX, pakai xgWajibLogin True, supaya halaman itu menjawab 401 dan tidak mengalihkan permintaan AJAX ke X-Guard. Yang didapat:
- Pengguna yang belum login dialihkan ke X-Guard, lalu kembali ke halaman yang tadi dibuka.
- Bila sesi ASP habis tapi sesi X-Guard masih ada, pengguna masuk lagi otomatis tanpa mengklik apa pun.
- Tiap 15 menit aplikasi memeriksa ulang ke X-Guard tanpa terlihat. Pengguna yang sudah keluar di aplikasi lain, akunnya dinonaktifkan, atau aksesnya dicabut ikut keluar dari aplikasi ini.
Webhook (opsional)
Webhook membuat aplikasi tahu seketika saat pengguna dinonaktifkan atau dihapus, tanpa menunggu pengguna itu membuka halaman. Cocok untuk menandai akun lokal nonaktif.
- Di konsol X-Guard, buka rincian aplikasi, panel Webhook, lalu Pasang webhook: alamat
https://aplikasi-anda/sso/webhook.asp, pilih event yang dibutuhkan. - Salin secret webhook (diawali
xgwh_, hanya tampil sekali) keXG_WEBHOOK_SECRETdixg_config.asp. - Sesuaikan
xgTerimaEventdixg_aplikasi.asp. - Tekan Uji kirim di panel Webhook. Riwayat pengiriman di panel itu harus menunjukkan Terkirim.
webhook.asp memeriksa tanda tangan X-XGuard-Signature (HMAC-SHA256 atas timestamp.body), menolak kiriman yang lebih tua dari 5 menit, lalu memanggil xgTerimaEvent(idEvent, tipe, sub, email, akses):
| Event | Artinya |
|---|---|
user.created | Akun aktif pertama kali |
user.updated | Nama atau email berubah |
user.disabled | Ditangguhkan atau dinonaktifkan admin organisasi |
user.enabled | Aktif kembali |
user.deleted | Dihapus |
user.apps_changed | Pengguna ditambah ke (akses = "granted") atau dikeluarkan dari ("revoked") daftar akses aplikasi ini |
xgTerimaEvent mengembalikan "" bila event diterima. Pesan lain membuat X-Guard mencoba lagi dengan jeda bertahap sampai 24 jam, jadi event bisa datang lebih dari sekali: simpan idEvent yang sudah diproses dan abaikan pengulangan. sub yang tidak dikenal aplikasi cukup diabaikan (kembalikan "").
Sesi ASP pengguna yang dinonaktifkan tidak bisa diakhiri dari webhook (sesi ada di memori server, per browser). Sesi itu berakhir saat cek ulang berikutnya (paling lambat 15 menit), atau lebih cepat bila halaman memeriksa status akun lokal.
Daftar uji
| No | Lakukan | Yang seharusnya terjadi |
|---|---|---|
| 1 | Klik Masuk dengan X-Guard, login | Kembali ke aplikasi sebagai pengguna itu |
| 2 | Cek kolom xguard_sub di database | Terisi (diawali USR_) |
| 3 | Logout, lalu login lagi | Masuk sebagai pengguna yang sama |
| 4 | Login dengan akun yang tidak ada di tabel users | Pesan "belum terdaftar" |
| 5 | Klik Keluar | Sampai di keluar-selesai.asp |
| 6 | Setelah keluar, buka halaman dalam | Diminta login lagi |
| 7 | Buka /sso/login.asp?next=https://google.com, login | Mendarat di halaman awal aplikasi, bukan Google |
| 8 | Belum login, buka /sso/callback.asp?code=abc&state=xyz | Ditolak: "Sesi login sudah kedaluwarsa" |
| 9 | Admin menonaktifkan akun uji di konsol | Paling lambat 15 menit kemudian terlempar keluar |
| 10 | Webhook: Uji kirim di konsol | Riwayat pengiriman Terkirim |
Setelah semua lolos, hapus cek-koneksi.asp.
Data pengguna dari X-Guard
Klaim id_token | Isi | Parameter di xgLoginLokal |
|---|---|---|
sub | ID pengguna (diawali USR_). Pakai ini sebagai kunci | xgSub |
email | Email utama | email |
email_verified | Email sudah diverifikasi | emailTerverifikasi |
name | Nama lengkap | nama |
sid | Sesi X-Guard | Disimpan di Session("xg_sid") |
amr | Cara login, mis. pwd | Tidak dipakai di contoh |
X-Guard tidak mengirim role atau jabatan. Hak akses di aplikasi tetap urusan aplikasi.
Perilaku yang perlu diketahui
- Lama sesi. Sesi ASP mengikuti
Session.Timeout(bawaan IIS 20 menit tanpa aktivitas), dan pulih otomatis selama sesi X-Guard masih ada. - Logout berlaku untuk semua aplikasi organisasi.
logout.aspjuga mengakhiri sesi X-Guard. - Logout dari aplikasi lain tidak langsung terasa di sini. Aplikasi ASP baru tahu saat cek ulang berikutnya, paling lambat 15 menit. Atur lewat
XG_CEK_ULANG_MENIT. Cek ulang hanya pada permintaan GET non-AJAX, supaya isian form tidak hilang. - Akun yang dinonaktifkan tidak bisa login lagi seketika, dan sesi X-Guard-nya diakhiri. Sesi di aplikasi ini berakhir saat cek ulang.
- Akses yang dicabut di konsol: pengguna ditolak di cek ulang berikutnya dengan pesan "belum diberi akses".
Masalah umum
Kegagalan login tercatat di log IIS, di kolom cs-uri-query, dengan awalan xg_gagal_; webhook dengan awalan xg_webhook_.
Di cek-koneksi.asp
| Pesan | Penyebab | Yang dilakukan |
|---|---|---|
0x80072F7D atau 0x80072F8F | Windows tidak bisa membangun TLS dengan X-Guard | Lihat Versi Windows |
0x80072F0D | Windows tidak mempercayai penerbit sertifikat | Jalankan Windows Update, atau pasang ISRG Root X2 dari letsencrypt.org/certificates ke Local Computer > Trusted Root Certification Authorities. Jangan matikan pemeriksaan sertifikat |
0x80072EE7 | Server tidak bisa menerjemahkan nama X-Guard | Periksa DNS server |
0x80072EFD atau 0x80072EE2 | Koneksi diblokir atau habis waktu | Periksa firewall. Lewat proxy: netsh winhttp set proxy proxy.kantor:8080 |
HTTP 404 (periksa XG_ISSUER) | Alamat organisasi salah | Salin issuer dari rincian aplikasi di konsol |
Issuer X-Guard ... tidak sama | Ada garis miring di akhir, atau huruf berbeda | Tulis persis seperti di konsol |
XG_AUTH_URL ... tidak sama | Tiga alamat lain belum ikut diganti | Ganti nama-organisasi di keempat alamat |
Jam server selisih ... | Jam server tidak akurat | Perbaiki sinkronisasi waktu |
Client ID atau secret ditolak | Salah salin, atau secret sudah diganti | Periksa xg_config.asp, atau buat secret baru di konsol |
Saat login
| Gejala | Penyebab | Yang dilakukan |
|---|---|---|
| Halaman X-Guard menampilkan galat soal alamat callback | XG_REDIRECT_URI tidak sama persis dengan yang didaftarkan | Bandingkan huruf per huruf |
"Sesi login sudah kedaluwarsa" (xg_gagal_state) | Login dimulai dari alamat berbeda dengan alamat callback (mis. tanpa www lalu kembali ke www) | Pakai satu alamat yang sama |
xg_gagal_token_kedaluwarsa atau ..._dari_masa_depan | Jam server tidak akurat | Perbaiki sinkronisasi waktu |
xg_gagal_koneksi | Halaman uji lolos tapi login gagal | Buka lagi cek-koneksi.asp |
xg_gagal_token_invalid_grant | Code sudah terpakai atau kedaluwarsa | Coba login lagi |
| "Belum diberi akses ke aplikasi ini" | Akses pengguna dibatasi di konsol | Minta admin organisasi menambahkannya di panel Akses pengguna |
| "Belum terdaftar di aplikasi ini" | Email pengguna tidak ada di tabel users | Tambahkan pengguna, atau ubah xgLoginLokal |
Webhook
| Riwayat pengiriman di konsol | Penyebab |
|---|---|
HTTP 401: tanda_tangan_salah | XG_WEBHOOK_SECRET salah, atau secret webhook sudah diganti |
HTTP 401: timestamp_kedaluwarsa | Jam server tidak akurat |
HTTP 401: secret_kosong | XG_WEBHOOK_SECRET belum diisi |
HTTP 500: ... | xgTerimaEvent mengembalikan pesan galat; X-Guard mencoba lagi |
HTTP 404 | Alamat webhook salah, atau webhook.asp belum disalin |
Galat ASP
| Pesan | Penyebab | Yang dilakukan |
|---|---|---|
Name redefined | File ter-include dua kali di satu halaman | Sisakan satu |
Type mismatch: 'xgUrlEncode' | xg_lib.asp tidak ter-include | Periksa #include |
Expected literal constant | Nilai Const memakai & | Tulis teks utuh |
Keamanan
- Jangan pernah mematikan pemeriksaan sertifikat (
http.setOption 2, 13056). Aplikasi tidak memeriksa tanda tanganid_tokendan mengandalkan sertifikat X-Guard. Tanpa pemeriksaan itu, siapa pun di jaringan bisa memalsukan pengguna. - Simpan secret hanya di file
.asp, bukan.inc,.txt, atau.configdi folder web. - Jangan pakai
Rnd()untukstate,nonce, atau verifier. PakaixgAcak(). - Jangan menghapus pemeriksaan
state,nonce, atau tanda tangan webhook. - Jangan menerima
id_tokendari form atau URL.xgPeriksaIdTokenhanya aman untuk token yang diterima langsung dari X-Guard dicallback.asp. - Jangan menggabung teks ke dalam SQL. Pakai parameter seperti contoh di
xg_aplikasi.asp. - Jangan mencatat
client_secret, secret webhook,code, atauid_tokenke log atau ke layar. - Hapus
cek-koneksi.aspsetelah selesai.
Kenapa tanda tangan id_token tidak diperiksa? ASP Classic tidak punya fungsi kriptografi RSA. OpenID Connect Core 3.1.3.7 butir 6 mengizinkan hal ini bila token diterima langsung dari token endpoint lewat TLS, karena sertifikat HTTPS sudah membuktikan token itu dari X-Guard. Isi token (iss, aud, exp, nonce) tetap diperiksa.
Kenapa ada cookie XGAUTH? ASP Classic tidak bisa mengganti ASPSESSIONID setelah login. Cookie acak ini mengikat sesi ke browser yang benar-benar menyelesaikan login.
Status pengujian
Kode di folder ini dijalankan di mesin VBScript, JScript, dan MSXML Windows 11 (cscript), dengan objek Session, Request, Response, dan Server tiruan:
- 40 skenario tanpa jaringan: SHA-256, HMAC-SHA256, dan PKCE terhadap vektor resmi dan Node; pemeriksaan
id_token(iss, aud, exp, nonce, sub); state palsu;access_denied; login senyap gagal; pengalihan ke situs lain; webhook sah, body diubah, secret lain, timestamp lama, dan teks Unicode. - 15 skenario terhadap X-Guard sungguhan:
cek-koneksi.asp, login dengan PKCE dan client secret, callback dobel, cookie pengikat, cek ulang senyap, logout, danlogin_requiredsesudah logout.
Belum diuji: berjalan di IIS sungguhan. Kerjakan daftar uji di server Anda. xg_aplikasi.asp baru lolos kompilasi, karena tiap aplikasi berbeda.
Fitur yang sengaja tidak dipakai
| Fitur | Kenapa | Gantinya |
|---|---|---|
| Back-channel logout | Logout token harus diperiksa tanda tangan RSA-nya | Cek ulang berkala (XG_CEK_ULANG_MENIT) |
| Refresh token | Aplikasi hanya perlu tahu siapa penggunanya | Login senyap saat sesi habis |
Daftar berkas
Semua berkas juga bisa diambil satu per satu (teks, baris CRLF):