Panduan Integrasi SSO SIMPANG KUDUS

Selamat datang di dokumentasi resmi integrasi Single Sign-On (SSO) Pemerintah Kabupaten Kudus.

Dokumen ini ditujukan untuk pengembang aplikasi (Developer) di lingkungan Pemkab Kudus yang ingin mengintegrasikan sistem login mereka dengan standar keamanan SIMPANG KUDUS.

Daftar Isi

1. Pengantar & Konsep Dasar
2. Persiapan Awal
3. Spesifikasi API (Reference)
4. Panduan Implementasi (Step-by-Step)
5. Keamanan & Best Practices
6. Troubleshooting & FAQ
7. Bantuan & Kontak

1. Pengantar & Konsep Dasar

Kami menggunakan protokol OAuth 2.0 standar industri. Jika Anda pernah menggunakan "Login with Google" atau "Login with Facebook", konsepnya sama persis.

Istilah Penting

2. Persiapan Awal

Sebelum menulis kode, pastikan Anda telah menghubungi Tim Teknis IT Bagian PBJ untuk mendaftarkan aplikasi Anda.

Data yang Anda butuhkan dari kami:

• Client ID (Format: UUID, contoh: 9xyz...)
• Client Secret (String acak panjang)

Data yang harus Anda setor ke kami:

• Redirect URI (Contoh: https://aplikasi-anda.kuduskab.go.id/callback)

⚠️ Penting: Redirect URI di kode Anda harus sama persis karakter-per-karakter dengan yang didaftarkan.

3. Spesifikasi API (Reference)

Berikut detail teknis endpoint yang tersedia di Server SSO.

A. Authorization Endpoint

Endpoint untuk memulai alur login (User Interface).

Parameter Query:

B. Token Endpoint

Endpoint untuk menukar Code menjadi Token (Back-channel).

Request Body:

Success Response (JSON):

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0a...",
    "refresh_token": "def50200d72023cb3f..."
}

C. User Info Endpoint

Endpoint untuk melihat profil user.

Success Response (JSON):

{
    "id": 15,
    "name": "Budi Santoso, S.Kom",
    "email": "budi@kuduskab.go.id",
    "nip": "198501152010011005",
    "phone": "081234567890",
    "user_type": "ASN",
    "status": "ACTIVE",
    "roles": [
        "ADMIN_OPD",
        "VERIFIKATOR"
    ],
    "active_satker": {
        "kd_satker": "123456",
        "nama_satker": "DINAS KOMUNIKASI DAN INFORMATIKA"
    }
}

4. Panduan Implementasi (Step-by-Step)

Berikut adalah contoh implementasi menggunakan PHP Native. Logika ini bisa diaplikasikan ke framework apapun (Laravel, CI, Node.js, dll).

Tahap 1: Buat Link Login

Di halaman login aplikasi Anda, buat tombol yang mengarah ke URL Authorize.

<?php
// login.php
$query = http_build_query([
    'client_id' => 'CLIENT_ID_DARI_KAMI',
    'redirect_uri' => 'https://aplikasi-anda.com/callback',
    'response_type' => 'code',
    'scope' => '',
    'state' => bin2hex(random_bytes(16)) // Security Token
]);

$sso_link = "https://simpangkudus.kuduskab.go.id/sso/oauth/authorize?" . $query;
?>
<a href="<?= $sso_link ?>">Login dengan SIMPANG KUDUS</a>

Tahap 2: Tangani Callback

Buat file callback.php untuk menerima user yang kembali dari SSO.

<?php
// callback.php

// 1. Validasi Code
if (!isset($_GET['code'])) {
    die("Error: User menolak akses atau terjadi kesalahan.");
}

// 2. Siapkan Data Pertukaran
$params = [
    'grant_type' => 'authorization_code',
    'client_id' => 'CLIENT_ID_DARI_KAMI',
    'client_secret' => 'CLIENT_SECRET_RAHASIA',
    'redirect_uri' => 'https://aplikasi-anda.com/callback',
    'code' => $_GET['code'],
];

// 3. Kirim Request ke Server SSO
$ch = curl_init("https://simpangkudus.kuduskab.go.id/sso/oauth/token");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response_raw = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$token_data = json_decode($response_raw, true);

// 4. Cek Error
if ($http_code !== 200 || !isset($token_data['access_token'])) {
    die("Gagal mendapatkan token: " . ($token_data['message'] ?? 'Unknown error'));
}

// 5. Simpan Token (Opsional, jika butuh akses API jangka panjang)
$access_token = $token_data['access_token'];

// 6. Ambil Data User
$ch_user = curl_init("https://simpangkudus.kuduskab.go.id/sso/api/user");
curl_setopt($ch_user, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . $access_token,
    "Accept: application/json"
]);
curl_setopt($ch_user, CURLOPT_RETURNTRANSFER, true);
$user_json = curl_exec($ch_user);
curl_close($ch_user);

$user_data = json_decode($user_json, true);

// 7. Login ke Sesi Aplikasi Lokal
session_start();
$_SESSION['user_sso'] = $user_data;
$_SESSION['fullname'] = $user_data['name'];

header("Location: /dashboard.php");
exit;

5. Keamanan & Best Practices

1. Validasi State: Selalu gunakan parameter state (string acak) saat redirect login, dan cek kembali saat callback untuk mencegah serangan CSRF.
2. HTTPS Wajib: Jangan pernah mengirim client_secret atau access_token melalui koneksi HTTP biasa.
3. Simpan Secret di Server: Jangan pernah menaruh client_secret di kode Javascript Frontend (React/Vue) yang bisa dibaca user. OAuth Code Flow harus dilakukan di Backend.
4. Error Handling: Selalu cek HTTP Status Code. Jangan asumsikan request selalu 200 OK.

6. Troubleshooting & FAQ

7. Bantuan & Kontak

Jika mengalami kendala teknis yang tidak terpecahkan, tim kami siap membantu.

Tim Teknis IT Bagian PBJ Kudus

• Email: pbj.kabkudus@gmail.com
• Jam Kerja: Senin - Jumat, 07:30 - 15:30 WIB

© 2026 Pemerintah Kabupaten Kudus. All rights reserved.