Skip to content

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:

LangkahYang dikerjakanBagian
1Pastikan server memenuhi syaratSyarat server
2Daftarkan aplikasi di konsol X-Guard, simpan client ID dan secretDaftarkan aplikasi
3Salin folder sso/ ke situsPasang file
4Buka halaman uji koneksiUji koneksi
5Sambungkan ke database dan halaman aplikasiSambungkan ke aplikasi
6Opsional: pasang webhookWebhook
7Uji dari awal sampai akhirDaftar 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.

IstilahArtinya
IssuerAlamat X-Guard organisasi Anda, mis. https://nama-organisasi.x-guard.online, atau domain sendiri
client_idPengenal aplikasi Anda di X-Guard
client_secretKata sandi aplikasi Anda ke X-Guard. Hanya boleh ada di server
codeKode sekali pakai dari X-Guard, dibawa browser ke callback.asp
stateTeks acak untuk memastikan callback berasal dari proses login yang dimulai browser ini
nonceTeks acak yang dikembalikan X-Guard di dalam id_token, supaya token lama tidak bisa dipakai ulang
PKCEPasangan code_verifier dan code_challenge: kode yang bocor tidak bisa ditukar tanpa verifier
id_tokenData pengguna dari X-Guard (nama, email, dll.)
subID 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 ServerStatusYang perlu dilakukan
2016 atau lebih baruCipher tersediaTidak ada, langsung ke uji koneksi
2012 R2Cipher tersediaPastikan update KB2919355 terpasang
2012Perlu patchPasang KB3140245, lalu tambah registry di bawah
2008 R2 SP1Perlu patchPasang KB3140245, tambah registry di bawah, dan aktifkan TLS 1.2
2008 (non-R2), 2003Tidak tercakupLihat 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 /f

Tambahan 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 /f

Restart 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:

IsianIsi
Nama aplikasiTampil di halaman login, mis. Aplikasi Keuangan
JenisWeb (aplikasi dengan server)
Alamat callbackhttps://keuangan.contoh.co.id/sso/callback.asp
Alamat sesudah logouthttps://keuangan.contoh.co.id/sso/keluar-selesai.asp
Alamat back-channel logoutKosongkan: ASP Classic tidak bisa memeriksa tanda tangannya (lihat Fitur yang sengaja tidak dipakai)
Autentikasi di endpoint tokenBawaan (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.

FileIsiPerlu diubah?
xg_config.aspClient ID, secret, alamatYa
xg_aplikasi.aspMencari pengguna di database Anda, dan menerima event webhookYa
xg_lib.aspSeluruh logika SSOTidak
login.aspMemulai loginTidak
callback.aspMenerima pengguna kembali dari X-GuardTidak
logout.aspKeluar dari aplikasi dan X-GuardTidak
keluar-selesai.aspHalaman setelah logoutBoleh dipercantik
webhook.aspMenerima event dari X-Guard (opsional)Tidak
cek-koneksi.aspHalaman uji. Hapus setelah selesaiTidak

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:

  1. Mencari pengguna lewat xguard_sub.
  2. Bila belum ketemu (login pertama), mencari lewat email lalu mengisi xguard_sub, hanya bila email terverifikasi.
  3. Bila tetap tidak ketemu, menolak dengan pesan.
  4. 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.

  1. Di konsol X-Guard, buka rincian aplikasi, panel Webhook, lalu Pasang webhook: alamat https://aplikasi-anda/sso/webhook.asp, pilih event yang dibutuhkan.
  2. Salin secret webhook (diawali xgwh_, hanya tampil sekali) ke XG_WEBHOOK_SECRET di xg_config.asp.
  3. Sesuaikan xgTerimaEvent di xg_aplikasi.asp.
  4. 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):

EventArtinya
user.createdAkun aktif pertama kali
user.updatedNama atau email berubah
user.disabledDitangguhkan atau dinonaktifkan admin organisasi
user.enabledAktif kembali
user.deletedDihapus
user.apps_changedPengguna 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 ​

NoLakukanYang seharusnya terjadi
1Klik Masuk dengan X-Guard, loginKembali ke aplikasi sebagai pengguna itu
2Cek kolom xguard_sub di databaseTerisi (diawali USR_)
3Logout, lalu login lagiMasuk sebagai pengguna yang sama
4Login dengan akun yang tidak ada di tabel usersPesan "belum terdaftar"
5Klik KeluarSampai di keluar-selesai.asp
6Setelah keluar, buka halaman dalamDiminta login lagi
7Buka /sso/login.asp?next=https://google.com, loginMendarat di halaman awal aplikasi, bukan Google
8Belum login, buka /sso/callback.asp?code=abc&state=xyzDitolak: "Sesi login sudah kedaluwarsa"
9Admin menonaktifkan akun uji di konsolPaling lambat 15 menit kemudian terlempar keluar
10Webhook: Uji kirim di konsolRiwayat pengiriman Terkirim

Setelah semua lolos, hapus cek-koneksi.asp.


Data pengguna dari X-Guard ​

Klaim id_tokenIsiParameter di xgLoginLokal
subID pengguna (diawali USR_). Pakai ini sebagai kuncixgSub
emailEmail utamaemail
email_verifiedEmail sudah diverifikasiemailTerverifikasi
nameNama lengkapnama
sidSesi X-GuardDisimpan di Session("xg_sid")
amrCara login, mis. pwdTidak 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.asp juga 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 ​

PesanPenyebabYang dilakukan
0x80072F7D atau 0x80072F8FWindows tidak bisa membangun TLS dengan X-GuardLihat Versi Windows
0x80072F0DWindows tidak mempercayai penerbit sertifikatJalankan Windows Update, atau pasang ISRG Root X2 dari letsencrypt.org/certificates ke Local Computer > Trusted Root Certification Authorities. Jangan matikan pemeriksaan sertifikat
0x80072EE7Server tidak bisa menerjemahkan nama X-GuardPeriksa DNS server
0x80072EFD atau 0x80072EE2Koneksi diblokir atau habis waktuPeriksa firewall. Lewat proxy: netsh winhttp set proxy proxy.kantor:8080
HTTP 404 (periksa XG_ISSUER)Alamat organisasi salahSalin issuer dari rincian aplikasi di konsol
Issuer X-Guard ... tidak samaAda garis miring di akhir, atau huruf berbedaTulis persis seperti di konsol
XG_AUTH_URL ... tidak samaTiga alamat lain belum ikut digantiGanti nama-organisasi di keempat alamat
Jam server selisih ...Jam server tidak akuratPerbaiki sinkronisasi waktu
Client ID atau secret ditolakSalah salin, atau secret sudah digantiPeriksa xg_config.asp, atau buat secret baru di konsol

Saat login ​

GejalaPenyebabYang dilakukan
Halaman X-Guard menampilkan galat soal alamat callbackXG_REDIRECT_URI tidak sama persis dengan yang didaftarkanBandingkan 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_depanJam server tidak akuratPerbaiki sinkronisasi waktu
xg_gagal_koneksiHalaman uji lolos tapi login gagalBuka lagi cek-koneksi.asp
xg_gagal_token_invalid_grantCode sudah terpakai atau kedaluwarsaCoba login lagi
"Belum diberi akses ke aplikasi ini"Akses pengguna dibatasi di konsolMinta admin organisasi menambahkannya di panel Akses pengguna
"Belum terdaftar di aplikasi ini"Email pengguna tidak ada di tabel usersTambahkan pengguna, atau ubah xgLoginLokal

Webhook ​

Riwayat pengiriman di konsolPenyebab
HTTP 401: tanda_tangan_salahXG_WEBHOOK_SECRET salah, atau secret webhook sudah diganti
HTTP 401: timestamp_kedaluwarsaJam server tidak akurat
HTTP 401: secret_kosongXG_WEBHOOK_SECRET belum diisi
HTTP 500: ...xgTerimaEvent mengembalikan pesan galat; X-Guard mencoba lagi
HTTP 404Alamat webhook salah, atau webhook.asp belum disalin

Galat ASP ​

PesanPenyebabYang dilakukan
Name redefinedFile ter-include dua kali di satu halamanSisakan satu
Type mismatch: 'xgUrlEncode'xg_lib.asp tidak ter-includePeriksa #include
Expected literal constantNilai Const memakai &Tulis teks utuh

Keamanan ​

  1. Jangan pernah mematikan pemeriksaan sertifikat (http.setOption 2, 13056). Aplikasi tidak memeriksa tanda tangan id_token dan mengandalkan sertifikat X-Guard. Tanpa pemeriksaan itu, siapa pun di jaringan bisa memalsukan pengguna.
  2. Simpan secret hanya di file .asp, bukan .inc, .txt, atau .config di folder web.
  3. Jangan pakai Rnd() untuk state, nonce, atau verifier. Pakai xgAcak().
  4. Jangan menghapus pemeriksaan state, nonce, atau tanda tangan webhook.
  5. Jangan menerima id_token dari form atau URL. xgPeriksaIdToken hanya aman untuk token yang diterima langsung dari X-Guard di callback.asp.
  6. Jangan menggabung teks ke dalam SQL. Pakai parameter seperti contoh di xg_aplikasi.asp.
  7. Jangan mencatat client_secret, secret webhook, code, atau id_token ke log atau ke layar.
  8. Hapus cek-koneksi.asp setelah 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, dan login_required sesudah 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 ​

FiturKenapaGantinya
Back-channel logoutLogout token harus diperiksa tanda tangan RSA-nyaCek ulang berkala (XG_CEK_ULANG_MENIT)
Refresh tokenAplikasi hanya perlu tahu siapa penggunanyaLogin senyap saat sesi habis

Daftar berkas ​

Semua berkas juga bisa diambil satu per satu (teks, baris CRLF):