X-Guard Docs

Brief untuk agen AI ​

Halaman ini untuk agen AI (atau developer) yang ditugasi menyambungkan sebuah aplikasi ke SSO X-Guard. Isinya cukup untuk merancang, mengerjakan, dan menguji integrasi tanpa bertanya ulang. Versi Markdown halaman ini: https://docs.x-guard.online/agen.md; semua halaman sekaligus: https://docs.x-guard.online/llms-full.txt.

1. Tentang X-Guard ​

  • OpenID Provider per organisasi. Issuer: https://<organisasi>.x-guard.online, atau domain sendiri organisasi. Discovery: <issuer>/.well-known/openid-configuration.
  • Alur: authorization code + PKCE S256, state, nonce. ID token dan access token JWT RS256 (JWKS di <issuer>/keys).
  • Scope: openid profile email (tambah offline_access untuk refresh token).
  • Klaim ID token: sub (ID tetap, diawali USR_), name, email, email_verified, sid, auth_time, amr. Access token (5 menit) menambah client_id, scp, org.
  • Tidak ada klaim role. Hak akses tetap diatur aplikasi.

2. Keputusan bawaan ​

Ikuti kecuali pengguna memutuskan lain.

  1. Tombol Masuk dengan X-Guard. Login lama tetap ada selama masa transisi; jangan dihapus tanpa persetujuan.
  2. Penautan akun: tambah kolom xguard_sub (teks 64, unik, boleh kosong). Cari lewat xguard_sub; login pertama cari lewat email hanya bila email_verified lalu isi xguard_sub; tetap tidak ketemu → tolak, atau buat akun dengan hak paling rendah bila pengguna memintanya.
  3. Sesudah identitas lolos, tetap lewat gerbang aplikasi sendiri (status akun, role, maintenance).
  4. Aplikasi menerbitkan sesinya sendiri. Simpan sid dan id_token di sesi (untuk back-channel dan logout). Ganti ID sesi sesudah login.
  5. Logout: hapus sesi lokal, lalu alihkan ke end_session dengan id_token_hint dan post_logout_redirect_uri.
  6. Aplikasi dengan alamat publik: pasang back-channel logout. Tanpa alamat publik (intranet, localhost): pasang pemeriksaan sesi senyap (prompt=none) tiap 1 sampai 15 menit pada GET halaman.
  7. Pasang webhook bila aplikasi menyimpan akun lokal: user.disabled, user.deleted, dan user.apps_changed dengan access revoked mencabut semua sesi pengguna itu.
  8. Pakai SDK X-Guard bila stack-nya tersedia; selain itu pustaka OIDC tersertifikasi. Jangan menulis kriptografi sendiri.

3. Data yang diminta ke pengguna ​

DataContoh
Issuer organisasihttps://acme.x-guard.online (tampil di rincian aplikasi di konsol)
Alamat dasar aplikasi per lingkunganhttps://hr.acme.co.id, http://localhost:8000
Path callback, sesudah logout, back-channel, webhook/auth/callback, /, /auth/backchannel-logout, /auth/webhook
Nama variabel env yang dipakai aplikasiXGUARD_ISSUER, XGUARD_CLIENT_ID, ...

Pengguna (admin organisasi) mendaftarkan aplikasi di konsol X-Guard → Aplikasi → Tambah aplikasi, dengan alamat di atas, lalu menaruh client ID, client secret, dan (bila webhook dipakai) secret webhook langsung di env server. Jangan pernah meminta secret dikirim lewat chat, dan jangan menulisnya ke repositori atau log. Cukup minta pengguna mengisi env, lalu kode membaca dari sana.

4. Langkah per stack ​

Laravel 10 sampai 12 ​

Ambil berkas dari SDK Laravel (/berkas/laravel/...), composer require firebase/php-jwt, daftarkan XGuardSso sebagai singleton, pasang rute /auth/*, kecualikan auth/backchannel-logout dan auth/webhook dari CSRF, jalankan migrasi xguard_sub, pasang middleware auth + xguard.sesi.

Go ​

Ambil /berkas/go/xguard/ ke internal/xguard. xguard.New, StartLogin, HandleCallback, BackchannelLogoutHandler, WebhookHandler, RequireAccessToken.

ASP Classic ​

Ambil folder /berkas/asp-classic/sso/ ke root situs. Yang disesuaikan hanya xg_config.asp (nilai dari konsol) dan xg_aplikasi.asp (database dan nama Session aplikasi). Buka cek-koneksi.asp dulu; semua baris harus OK. Jangan mengubah xg_lib.asp.

Node.js ​

openid-client 6, contoh lengkap di Node.js.

Next.js dengan Auth.js ​

Provider OIDC generik:

ts
{ id: "xguard", name: "X-Guard", type: "oidc", issuer: process.env.XGUARD_ISSUER,
  clientId: process.env.XGUARD_CLIENT_ID, clientSecret: process.env.XGUARD_CLIENT_SECRET,
  checks: ["pkce", "state", "nonce"], authorization: { params: { scope: "openid profile email" } } }

Alamat callback-nya https://<aplikasi>/api/auth/callback/xguard. Kirim access_token ke API backend; backend Go memakai RequireAccessToken.

Lainnya (Java, .NET, Python, Ruby) ​

Pustaka OIDC yang membaca discovery: Spring Security OAuth2 Client, ASP.NET Core AddOpenIdConnect, Authlib, OmniAuth OpenID Connect. Pastikan PKCE aktif, ResponseType = code, dan scope openid profile email.

5. Kontrak yang harus dipatuhi ​

  • Alamat callback dicocokkan persis. https wajib, kecuali localhost. Satu karakter beda = ditolak.
  • Galat callback: access_denied (tidak diberi akses: tampilkan pesan, jangan ulang), login_required (login senyap tanpa sesi: akhiri sesi lokal, lalu login biasa). Percayai galat hanya bila state cocok.
  • Back-channel logout: POST form logout_token (JWT RS256: iss, aud = client ID, sid, events berisi http://schemas.openid.net/event/backchannel-logout, tanpa nonce). Cabut sesi ber-sid sama, jawab 200.
  • Webhook: POST JSON {"id","type","sub","email","occurred_at"} (+ access untuk user.apps_changed), header X-XGuard-Timestamp dan X-XGuard-Signature: sha256=<hex HMAC-SHA256(secret, timestamp + "." + body)>. Tolak selisih waktu lebih dari 5 menit. Jawab 2xx untuk event yang sudah diproses, id ganda, atau sub yang tidak dikenal. Selain 2xx dicoba ulang sampai 24 jam dengan id dan body yang sama; urutan dijaga per pengguna.
  • Refresh token dirotasi: simpan yang baru setiap kali. Pemakaian ulang mencabut seluruh rangkaian.

6. Jebakan yang pernah terjadi ​

  • Cookie state login hilang di BFF atau proxy. Bila Next.js meneruskan /api ke backend, cookie sementara login (state, nonce, verifier) harus diteruskan dua arah untuk rute /auth/*. Gejalanya: login di X-Guard berhasil, tetapi callback selalu "state tidak cocok".
  • Login dimulai dari host berbeda dengan callback (tanpa www lalu kembali ke www, atau localhost lalu 127.0.0.1): cookie sesi tidak terbawa, callback ditolak. Pakai satu alamat.
  • Body webhook di-parse lalu diserialisasi ulang sebelum HMAC: tanda tangan tidak pernah cocok. Pakai body mentah, dan teruskan header X-XGuard-* apa adanya di proxy.
  • Dua aplikasi di localhost beda port berbagi cookie (cookie tidak dibedakan per port): beri nama cookie sesi berbeda.
  • Jam server melenceng: ID token ditolak sebagai kedaluwarsa atau dari masa depan.
  • Pemeriksaan sertifikat dimatikan untuk mengatasi galat HTTPS (terutama di ASP Classic dan Windows lama). Jangan: perbaiki TLS-nya.
  • Back-channel logout ke localhost tidak pernah sampai. Pakai pemeriksaan sesi senyap untuk pengembangan.

7. Uji ​

  1. Login: Masuk dengan X-Guard → login → kembali ke aplikasi. Kolom xguard_sub terisi; sid tersimpan di sesi.
  2. SSO: buka aplikasi organisasi lain → masuk tanpa password, sid sama.
  3. Logout dari aplikasi: sesi lokal dan sesi X-Guard berakhir; kembali ke alamat sesudah logout.
  4. Logout dari aplikasi lain: sesi di aplikasi ini berakhir (back-channel seketika, atau pada pemeriksaan senyap).
  5. Akses dicabut di konsol (Akses pengguna → hanya pengguna terpilih, tanpa akun uji): login ditolak dengan pesan akses.
  6. Webhook: Uji kirim di konsol → riwayat Terkirim. Nonaktifkan akun uji → sesinya berakhir.
  7. Keamanan: /auth/callback?code=x&state=palsu ditolak; next=https://situs-lain berakhir di halaman aplikasi sendiri.

Sebelum produksi: daftar periksa.