Portal Integrasi SSO Kunci

Pendahuluan & Prasyarat

Sebelum memulai pengembangan integrasi, pastikan Anda telah mendaftarkan aplikasi sekolah Anda di portal pusat dan mendapatkan kredensial berikut:

1. Desain & Tampilan Layar Otorisasi (Consent UI)

Layar otorisasi (consent screen) dirancang menggunakan layout terpisah (split-screen) bergaya modern dark mode. Bagian kiri memuat branding identitas Kunci, sementara bagian kanan menyajikan permintaan izin akses bagi aplikasi sekolah klien.

+-------------------------------------------------------------------------+
|                                                                         |
|         [ LOGO KUNCI ]                   [ SHIELD CHECK ICON ]          |
|                                            Otorisasi Aplikasi           |
|   Bersama Kunci Transformasi Digital                                    |
|   menyediakan layanan terbaik untuk   Aplikasi Demo SMK meminta izin    |
|   edukasi dan pendidikan.             akses ke akun Kunci Anda.         |
|                                                                         |
|                                       Izin yang diminta:                |
|                                       (v) Melihat profil Anda           |
|                                           (Nama, ID, Foto Profil)       |
|                                       (v) Melihat alamat email Anda     |
|                                                                         |
|                                             [ SETUJU ]                  |
|                                             [ BATAL ]                   |
|                                                                         |
+-------------------------------------------------------------------------+

2. Aliran Otentikasi (OAuth 2.0 PKCE Flow)

PKCE (Proof Key for Code Exchange) menggantikan penggunaan static secret pada perangkat klien (seperti mobile app atau single-page app) dan memperkuat pertukaran kode otorisasi pada server klien:

   [ Klien (Browser/Server) ]                [ Portal Pusat (Kunci) ]
              |                                         |
    (1) Buat code_verifier & challenge                  |
    (2) Redirect ke Authorize Page -------------------> |
              |                                         | (3) Login & Setuju Izin
              | <------------------ (4) Redirect + code |
    (5) Kirim code & code_verifier                      |
        ke Server Lokal Klien                           |
              |                                         |
    (6) Server Klien: POST /sso/exchange -------------> |
        (Membawa client_secret, code, verifier)         | (7) Validasi &
              |                                         |     Bandingkan Hash
              | <----------------- (8) User Profile JSON |
              v                                         v

3. Integrasi Klien (Developer Guide)

A. Panduan Pembuatan PKCE S256

code_verifier adalah random string (minimal 43 karakter, maksimal 128 karakter) menggunakan karakter [A-Z], [a-z], [0-9], dan tanda -, ., _, ~.

// 1. Buat code_verifier
$codeVerifier = bin2hex(random_bytes(64));

// 2. Buat code_challenge (S256)
$hash = hash('sha256', $codeVerifier, true);
$codeChallenge = rtrim(strtr(base64_encode($hash), '+/', '-_'), '=');

B. Langkah 1: Pengalihan Otorisasi (Authorize Redirect)

Arahkan browser pengguna ke halaman authorize dengan parameter-parameter URL berikut. Gunakan spasi (atau url-encoded %20) untuk memisahkan scope:

https://kunci.co.id/oauth/authorize?
  client_id=demosmk-client-id
  &redirect_uri=http://demosmk.sekolah.kunci.test/oauth/callback
  &response_type=code
  &scope=profile email
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWBuGJSstw-cM
  &code_challenge_method=S256
  &state=xyzSecretState

C. Langkah 2: Tukar Token & Profil (Token Exchange)

Setelah redirect callback selesai, server backend sekolah Anda menukar code dari browser dengan payload JSON POST ke API pusat:

{
  "client_id": "demosmk-client-id",
  "client_secret": "demosmk-client-secret",
  "code": "AUTHORIZATION_CODE_RECEIVED",
  "code_verifier": "ORIGINAL_RANDOM_CODE_VERIFIER",
  "redirect_uri": "http://demosmk.sekolah.kunci.test/oauth/callback"
}

{
  "status": "success",
  "user": {
    "id": "central-user-ulid",
    "name": "Ridwan Gunawan",
    "email": "ridwan@sekolah.sch.id",
    "display_photo_url": "https://kunci.co.id/storage/avatars/ridwan.png",
    "roles": ["staff", "teacher"]
  }
}

E. Endpoint Tambahan: Memuat Daftar Sekolah

Gunakan API ini untuk memuat daftar sekolah aktif beserta URL aplikasinya guna ditampilkan pada halaman pemilihan sekolah klien.

?search=SMK&limit=10&with_demo=false

{
  "status": "success",
  "data": [
    {
      "id": "school-uuid-1",
      "name": "SMK Negeri 1 Jakarta",
      "app_url": "https://smkn1jakarta.sekolah.kunci.test",
      "logo_url": "https://kunci.co.id/storage/logos/smk1.png"
    }
  ]
}

F. Integrasi Mudah Menggunakan SDK Resmi (Direkomendasikan)

Untuk mempercepat integrasi dan menghindari kesalahan implementasi PKCE manual, Kunci menyediakan SDK resmi untuk PHP dan Dart/Flutter.

composer require kunci/sso-sdk-php

php artisan vendor:publish --tag=kunci-sso-config

use Kunci\SSO\KunciSSOClient;
use Illuminate\Http\Request;
use Illuminate\SupportStr;

class SSOController extends Controller
{
    public function redirect(KunciSSOClient $sso)
    {
        $pkce = $sso->generatePKCE();
        session(['sso_state' => $state = Str::random(40)]);
        session(['sso_code_verifier' => $pkce['code_verifier']]);

        return redirect($sso->getAuthorizationUrl($state, $pkce['code_challenge']));
    }

    public function callback(Request $request, KunciSSOClient $sso)
    {
        if (!$sso->validateState(session('sso_state'), $request->state)) {
            abort(403, 'Invalid state');
        }

        $user = $sso->exchangeCodeForUser($request->code, session('sso_code_verifier'));
        // $user berisi: ['id' => '...', 'name' => '...', 'email' => '...', 'roles' => [...]]
    }
}

$sso = new \Kunci\SSO\KunciSSOClient([
    'client_id' => 'client-id-anda',
    'client_secret' => 'client-secret-anda',
    'redirect_uri' => 'https://sekolah.sch.id/oauth/callback',
    'central_url' => 'https://kunci.co.id',
    'portal_url' => 'https://kunci.co.id/portal'
]);

4. Endpoint Integrasi Sekolah (Local School API)

Untuk aplikasi yang bertindak sebagai sistem sekolah lokal, Anda wajib menyediakan tiga endpoint backend-to-backend berikut. Semua request dari server pusat akan menyertakan header Authorization: Bearer CLIENT_SECRET (menggunakan Client Secret aplikasi sekolah Anda yang terdaftar di portal pusat).

Endpoint ini dipicu oleh server pusat untuk memverifikasi kredensial login lokal pengguna sekolah saat memilih login langsung melalui portal pusat.

{
  "identifier": "NIP / NIPD / Username / Email Lokal",
  "password": "Password Akun Sekolah Lokal",
  "type": "staff"
}

{
  "status": "success",
  "name": "Ridwan Gunawan",
  "email": "ridwan@sekolah.sch.id",
  "photo_url": "https://sekolah.sch.id/storage/avatars/ridwan.png", // Opsional
  "type": "staff"
}

Dipanggil oleh server pusat untuk menghubungkan akun lokal sekolah pengguna dengan email SSO pusat ketika inisiasi tautan akun dilakukan dari portal.

{
  "app_id": "demosmk-client-id",
  "identifier": "NIP / NIPD / Username / Email Lokal",
  "pin": "Password Akun Sekolah Lokal",
  "type": "staff",
  "sso_email": "ridwan@sekolah.sch.id"
}

{
  "status": "success",
  "message": "Akun Staff berhasil dihubungkan ke SSO."
}

Dipanggil untuk memutuskan hubungan antara akun lokal sekolah dengan email SSO pusat.

{
  "app_id": "demosmk-client-id",
  "bind_id": "bind-id-to-remove"
}

{
  "status": "success",
  "message": "Akun berhasil diputuskan dari SSO."
}

5. Penanganan Error & Kode Respon

Berikut adalah daftar kode respon HTTP standar yang dapat terjadi selama pertukaran atau verifikasi: