README

SDK untuk mengintegrasikan aplikasi berbasis Laravel dengan layanan Single Sign-On (SSO) Smartkampung Kabupaten Banyuwangi.

SDK ini menyediakan mekanisme redirect login, dekripsi tiket, validasi autentikasi pengguna, serta komunikasi logout dengan server SSO Smartkampung.

Dengan SDK ini, aplikasi yang terintegrasi dapat menggunakan satu akun Smartkampung untuk mengakses berbagai layanan aplikasi yang telah terdaftar.

1. Persyaratan

Sebelum menggunakan SDK, pastikan aplikasi memenuhi persyaratan berikut:

Komponen	Persyaratan
PHP	>= 7.4
Composer	Terinstal
Laravel	Mendukung versi PHP yang digunakan
OpenSSL	Aktif
cURL	Aktif
Guzzle	^7.8 (dependensi SDK)

Pastikan ekstensi PHP openssl dan curl sudah aktif pada server.

Untuk memeriksa ekstensi PHP, jalankan:

php -m

2. Instalasi SDK

Buka terminal atau command prompt, kemudian masuk ke direktori utama project Laravel.

Jalankan perintah berikut:

composer require sksso/sdkssocryptor

Composer akan mengunduh SDK beserta dependensi yang diperlukan.

Setelah instalasi berhasil, SDK dapat dipanggil menggunakan namespace:

use sksso\SDKSSOcryptor;

3. Konfigurasi SDK

A. Mendapatkan Kredensial SSO

Sebelum melakukan konfigurasi, hubungi administrator SSO Smartkampung untuk mendapatkan tiga parameter berikut:

Parameter	Keterangan
`ALIAS_ID`	Identitas aplikasi yang terdaftar di SSO Smartkampung
`SECRET_KEY_BODY`	Secret key untuk proses enkripsi dan dekripsi data body
`SECRET_KEY_URL`	Secret key untuk proses dekripsi parameter URL

Ketiga parameter tersebut bersifat rahasia dan tidak boleh dibagikan kepada pihak yang tidak berkepentingan.

B. Menambahkan Konfigurasi Environment

Buka file .env pada project Laravel, kemudian tambahkan konfigurasi berikut:

SSO_ALIAS_ID=ISI_ALIAS_ID
SSO_SECRET_KEY_BODY=ISI_SECRET_KEY_BODY
SSO_SECRET_KEY_URL=ISI_SECRET_KEY_URL

Ganti nilai tersebut sesuai kredensial yang diberikan oleh administrator SSO.

C. Membuat File Konfigurasi

Buat file baru:

config/smartkampung_sso.php

Isi dengan konfigurasi berikut:

<?php

return [
    'alias_id' => env('SSO_ALIAS_ID'),

    'secret_key_body' => env('SSO_SECRET_KEY_BODY'),

    'secret_key_url' => env('SSO_SECRET_KEY_URL'),
];

File konfigurasi ini digunakan untuk mempermudah pengelolaan kredensial SDK.

4. Inisialisasi SDK pada Laravel

Agar SDK dapat digunakan di berbagai controller tanpa harus melakukan inisialisasi berulang kali, gunakan Service Provider Laravel.

A. Membuat Service Provider

Jalankan perintah:

php artisan make:provider SmartkampungSsoServiceProvider

Buka file:

app/Providers/SmartkampungSsoServiceProvider.php

Sesuaikan isinya menjadi:

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use sksso\SDKSSOcryptor;

class SmartkampungSsoServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(SDKSSOcryptor::class, function () {

            $sdk = new SDKSSOcryptor();

            $sdk->setEnv(
                config('smartkampung_sso.alias_id'),
                config('smartkampung_sso.secret_key_body'),
                config('smartkampung_sso.secret_key_url')
            );

            return $sdk;
        });
    }
}

B. Mendaftarkan Service Provider

Untuk Laravel 11 dan Laravel 12, buka:

bootstrap/providers.php

Tambahkan provider yang telah dibuat:

<?php

return [
    App\Providers\AppServiceProvider::class,
    App\Providers\SmartkampungSsoServiceProvider::class,
];

Untuk Laravel 10 atau versi sebelumnya, daftarkan pada bagian providers di:

config/app.php

'providers' => [
    // Provider lainnya

    App\Providers\SmartkampungSsoServiceProvider::class,
],

Setelah selesai, SDK dapat dipanggil melalui dependency injection pada controller.

5. Implementasi Login SSO

Proses login menggunakan SSO Smartkampung terdiri dari dua tahapan utama:

Mengarahkan pengguna ke halaman login SSO Smartkampung.
Menerima dan memvalidasi tiket login yang dikirimkan kembali oleh server SSO.

A. Membuat Controller

Buat controller baru:

php artisan make:controller SsoController

Buka file:

app/Http/Controllers/SsoController.php

Gunakan implementasi berikut:

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use sksso\SDKSSOcryptor;

class SsoController extends Controller
{
    private $sso;

    public function __construct(SDKSSOcryptor $sso)
    {
        $this->sso = $sso;
    }

    /**
     * Redirect pengguna ke halaman login SSO Smartkampung.
     */
    public function redirectToSso()
    {
        $this->sso->loginPage();
    }

    /**
     * Menerima dan memvalidasi tiket dari SSO Smartkampung.
     */
    public function callback($param)
    {
        $dataUsers = $this->sso->cekTiket($param);

        if (!$dataUsers) {
            return redirect()
                ->route('login')
                ->with('error', 'Autentikasi SSO gagal.');
        }

        // Contoh pencocokan pengguna berdasarkan NIK.
        // Sesuaikan atribut dengan respons aktual dari SSO.
        $user = User::where('nik', $dataUsers['nik'])->first();

        if (!$user) {
            return redirect()
                ->route('login')
                ->with('error', 'Pengguna belum terdaftar pada aplikasi.');
        }

        // Login menggunakan autentikasi Laravel.
        Auth::login($user);

        // Regenerasi session untuk keamanan.
        request()->session()->regenerate();

        return redirect()->intended('/dashboard');
    }
}

B. Redirect ke Halaman Login SSO

Method:

$this->sso->loginPage();

Digunakan untuk mengarahkan pengguna ke halaman login SSO Smartkampung.

URL login akan dibentuk secara otomatis berdasarkan ALIAS_ID yang telah dikonfigurasi.

Tidak perlu membuat URL login secara manual.

C. Menerima dan Memvalidasi Tiket SSO

Setelah pengguna berhasil melakukan autentikasi di SSO Smartkampung, server SSO akan mengarahkan pengguna kembali ke aplikasi dengan membawa parameter tiket terenkripsi.

Method:

$dataUsers = $this->sso->cekTiket($param);

Method cekTiket() melakukan proses berikut secara otomatis:

Menerima parameter tiket terenkripsi dari server SSO.
Mendekripsi parameter URL menggunakan SECRET_KEY_URL.
Mengambil tiket dan token JWT.
Mengenkripsi tiket menggunakan SECRET_KEY_BODY.
Mengirim permintaan validasi ke server SSO Smartkampung.
Memeriksa kode respons validasi.
Mengembalikan data pengguna apabila tiket berhasil divalidasi.

SDK menggunakan endpoint internal SSO:

POST /api/protected/quickverifytiket

Apabila tiket berhasil divalidasi, method cekTiket() mengembalikan data pengguna dalam bentuk array.

Apabila tiket tidak valid, SDK mengembalikan false dan mengarahkan pengguna kembali ke halaman login SSO.

Catatan: Contoh pencocokan pengguna menggunakan atribut nik. Sesuaikan nama atribut dengan struktur data pengguna yang dikembalikan oleh server SSO dan struktur tabel pengguna pada aplikasi masing-masing.

6. Konfigurasi Route

Buka file:

routes/web.php

Tambahkan route berikut:

use App\Http\Controllers\SsoController;

Route::get('/sso/redirect', [
    SsoController::class,
    'redirectToSso'
])->name('sso.redirect');

Route::get('/sso/callback/{param}', [
    SsoController::class,
    'callback'
])
->where('param', '.*')
->name('sso.callback');

Keterangan:

Route	Fungsi
`/sso/redirect`	Mengarahkan pengguna ke halaman login SSO
`/sso/callback/{param}`	Menerima tiket dan melakukan validasi login

Route callback harus dapat diakses tanpa middleware autentikasi aplikasi karena pengguna belum login ketika kembali dari SSO.

URL callback yang digunakan harus sesuai dengan URL yang didaftarkan pada administrator SSO Smartkampung.

7. Implementasi Tombol Login

Untuk mengarahkan pengguna ke SSO Smartkampung, tambahkan tombol berikut pada halaman login aplikasi:

<a href="{{ route('sso.redirect') }}" class="btn btn-primary">
    Login dengan SSO Smartkampung
</a>

Ketika tombol diklik, pengguna akan diarahkan ke halaman login SSO Smartkampung.

Setelah autentikasi berhasil, pengguna akan dikembalikan ke aplikasi melalui route callback.

8. Implementasi Logout

SDK menyediakan method:

logout($tokenJWT, $sesisso, $sesiapp)

Method ini digunakan untuk mengirim permintaan logout ke server SSO Smartkampung.

Parameter yang diperlukan:

Parameter	Keterangan
`$tokenJWT`	Token JWT autentikasi SSO
`$sesisso`	Identitas session pengguna pada SSO
`$sesiapp`	Identitas session aplikasi pada SSO

Nilai ketiga parameter tersebut harus diperoleh dari data autentikasi SSO yang dikembalikan oleh cekTiket(), sesuai struktur respons aktual.

Contoh pemanggilan method SDK:

$this->sso->logout(
    $tokenJWT,
    $sesisso,
    $sesiapp
);

Setelah proses logout SSO, aplikasi juga harus mengakhiri session Laravel:

Auth::logout();

request()->session()->invalidate();

request()->session()->regenerateToken();

return redirect()->route('login');

9. Alur Integrasi SSO

Secara keseluruhan, proses integrasi aplikasi dengan SSO Smartkampung adalah sebagai berikut:

+----------------------+
| Pengguna membuka     |
| aplikasi             |
+----------------------+
          |
          v
+----------------------+
| Klik Login SSO       |
+----------------------+
          |
          v
+----------------------+
| Redirect ke halaman  |
| SSO Smartkampung     |
+----------------------+
          |
          v
+----------------------+
| Pengguna melakukan   |
| autentikasi          |
+----------------------+
          |
          v
+----------------------+
| SSO mengirim tiket   |
| ke aplikasi          |
+----------------------+
          |
          v
+----------------------+
| SDK melakukan        |
| cekTiket()           |
+----------------------+
          |
          v
+----------------------+
| Validasi tiket       |
| ke server SSO        |
+----------------------+
          |
          v
+----------------------+
| Tiket valid?         |
+----------------------+
       /       \
     Ya         Tidak
      |            |
      v            v
+-----------+  +-------------+
| Cocokkan  |  | Kembali ke  |
| pengguna  |  | halaman SSO |
+-----------+  +-------------+
      |
      v
+----------------------+
| Laravel Auth::login  |
+----------------------+
      |
      v
+----------------------+
| Masuk ke aplikasi    |
+----------------------+

10. Troubleshooting

Permasalahan	Pemeriksaan
Class SDK tidak ditemukan	Jalankan `composer dump-autoload`
Kredensial tidak valid	Periksa `ALIAS_ID` dan kedua secret key
Gagal melakukan dekripsi	Pastikan secret key sesuai dengan aplikasi terdaftar
cURL error	Pastikan ekstensi PHP cURL aktif dan server dapat mengakses SSO
Tiket tidak valid	Pastikan parameter callback berasal dari proses login SSO yang benar
Data pengguna tidak ditemukan	Periksa atribut identitas pengguna dan pencocokan pada tabel users
Konfigurasi tidak berubah	Jalankan `php artisan config:clear`

11. Catatan Keamanan

Setiap aplikasi wajib memiliki ALIAS_ID dan secret key yang terdaftar pada administrator SSO Smartkampung.
Jangan menyimpan secret key secara langsung di source code aplikasi.
Jangan mengirimkan secret key melalui URL atau parameter request.
Gunakan HTTPS untuk seluruh komunikasi aplikasi.
Jangan mempercayai data pengguna sebelum tiket berhasil divalidasi melalui cekTiket().
Proses autentikasi pengguna tetap menggunakan mekanisme Laravel Auth.
SDK tidak melakukan sinkronisasi tabel pengguna. Pengelolaan dan pencocokan data pengguna menjadi tanggung jawab masing-masing aplikasi.
Jangan menyimpan atau menggunakan tiket login sebagai pengganti session autentikasi aplikasi.

12. Informasi Repository

Repository: SK-SSO-DECRYPTOR

Package Composer: sksso/sdkssocryptor

Instalasi:

composer require sksso/sdkssocryptor

Layanan SSO: SSO Smartkampung Kabupaten Banyuwangi

Untuk informasi kredensial aplikasi dan pendaftaran integrasi, silakan menghubungi administrator SSO Smartkampung.

SSO Smartkampung Kabupaten Banyuwangi

Satu Akun untuk Semua Layanan.

sksso / sdkssocryptor

Package info

Security

Statistics

README

Daftar Isi

1. Persyaratan

2. Instalasi SDK

3. Konfigurasi SDK

A. Mendapatkan Kredensial SSO

B. Menambahkan Konfigurasi Environment

C. Membuat File Konfigurasi

4. Inisialisasi SDK pada Laravel

A. Membuat Service Provider

B. Mendaftarkan Service Provider

5. Implementasi Login SSO

A. Membuat Controller

B. Redirect ke Halaman Login SSO

C. Menerima dan Memvalidasi Tiket SSO

6. Konfigurasi Route

7. Implementasi Tombol Login

8. Implementasi Logout

9. Alur Integrasi SSO

10. Troubleshooting

11. Catatan Keamanan

12. Informasi Repository