X-Guard Docs

SSO X-Guard untuk aplikasi Laravel ​

Berkas di folder ini dipasang ke aplikasi Laravel (10, 11, atau 12) supaya pengguna login lewat SSO X-Guard organisasi: OpenID Connect authorization code dengan PKCE, verifikasi ID token dengan kunci publik X-Guard, logout, back-channel logout, pemeriksaan sesi diam-diam, dan webhook. Satu dependensi: firebase/php-jwt.

Unduh x-guard-sdk-laravel.zip, atau ambil per berkas di daftar berkas. Kode yang sama dipakai aplikasi contoh tim X-Guard (dua aplikasi untuk menguji sesi SSO), yang lolos 13 uji PHPUnit dan uji browser terhadap X-Guard sungguhan.

Berkas ​

BerkasIsi
config/xguard.phpIssuer, client ID, secret, alamat callback dan sesudah logout, secret webhook
app/Services/XGuardSso.phpInti OIDC: discovery, URL login + PKCE, penukaran kode, verifikasi token, URL logout, logout token, webhook
app/Services/SsoException.php, SsoDenied.phpGalat login
app/Http/Controllers/SsoController.phpRute /auth/*: login, callback, keluar, cek sesi, back-channel logout, webhook
app/Http/Middleware/CekSesiXGuard.phpMenyelaraskan sesi lokal dengan sesi X-Guard
database/migrations/..._add_xguard_sub_to_users.phpKolom xguard_sub di tabel users

Memasang ​

  1. Di konsol X-Guard, buka Aplikasi → Tambah aplikasi, jenis Web:

    • Alamat callback: https://aplikasi-anda/auth/callback (http://localhost:… boleh untuk pengembangan).
    • Alamat sesudah logout: https://aplikasi-anda/.
    • Alamat back-channel logout: https://aplikasi-anda/auth/backchannel-logout.

    Simpan client ID dan client secret. Secret hanya tampil sekali.

  2. composer require firebase/php-jwt

  3. Salin berkas di atas ke aplikasi. Daftarkan XGuardSso sebagai singleton di AppServiceProvider::register:

    php
    $this->app->singleton(\App\Services\XGuardSso::class, fn () => new \App\Services\XGuardSso(config('xguard')));

  4. Rute dan middleware:

    php
    // routes/web.php
Route::controller(SsoController::class)->prefix('auth')->name('sso.')->group(function () {
    Route::get('login', 'login')->name('login');
    Route::get('callback', 'callback')->name('callback');
    Route::get('cek-sesi', 'cekSesi')->middleware('auth')->name('cek-sesi');
    Route::post('logout', 'logout')->middleware('auth')->name('logout');
    Route::post('backchannel-logout', 'backchannel')->name('backchannel');
    Route::post('webhook', 'webhook')->name('webhook');
});

// bootstrap/app.php, di withMiddleware
$middleware->redirectGuestsTo('/');
$middleware->alias(['xguard.sesi' => \App\Http\Middleware\CekSesiXGuard::class]);
$middleware->validateCsrfTokens(except: ['auth/backchannel-logout', 'auth/webhook']);

  5. .env:

    dotenv
    XGUARD_ISSUER=https://nama-organisasi.x-guard.online
XGUARD_CLIENT_ID=...
XGUARD_CLIENT_SECRET=...
XGUARD_REDIRECT_URI=https://aplikasi-anda/auth/callback
XGUARD_POST_LOGOUT_URI=https://aplikasi-anda/
XGUARD_WEBHOOK_SECRET=        # opsional, dari panel Webhook

    CekSesiXGuard membaca config('contoh.cek_sesi_detik') (bawaan 60 detik); ganti dengan konfigurasi aplikasi Anda.

  6. php artisan migrate, lalu pasang middleware auth dan xguard.sesi di halaman yang wajib login.

Perilaku ​

  • Login: tombol menuju /auth/login. Akun lokal dikenali dari sub X-Guard; akun lama ditautkan lewat email hanya bila X-Guard menyatakan email itu terverifikasi.
  • Logout: POST /auth/logout mengakhiri sesi lokal dan sesi X-Guard (semua aplikasi organisasi ikut keluar).
  • Logout dari aplikasi lain: back-channel logout (aplikasi dengan alamat publik), atau pemeriksaan diam-diam (prompt=none) berkala saat halaman dibuka.
  • Webhook: user.disabled, user.deleted, dan user.apps_changed dengan access revoked mengakhiri semua sesi lokal pengguna itu; user.updated memperbarui email. Tanda tangan dan umur kiriman diperiksa, pengulangan event diabaikan berdasarkan id.

Daftar berkas ​