Persiapan Integrasi

Sebelum menulis kode, Anda perlu mendaftarkan aplikasi Anda ke Tim Teknis Dinas Kominfo untuk mendapatkan akses ke lingkungan pengembangan (Development) maupun Produksi.

1. Permintaan Akses

Silakan ajukan permohonan pendaftaran klien baru dengan data sebagai berikut:

• Nama Aplikasi: (Contoh: Sistem Informasi Kepegawaian / SIMPEG)
• Platform: (Web / Android / iOS)
• Deskripsi Singkat: Penjelasan fungsi aplikasi.
• Redirect URI (Callback URL): Alamat URL di aplikasi Anda yang akan menerima token setelah login berhasil. Pastikan protokol (http vs https) tepat.
  • Dev: http://localhost:3000/callback (atau port lain sesuai framework)
  • Prod: https://aplikasi-anda.denpasarkota.go.id/auth/callback

Formulir Permohonan

Untuk mempercepat proses, silakan unduh dan lengkapi template formulir permohonan melalui tautan berikut: Download Template Form Permohonan Integrasi SSO

Mohon kirimkan formulir yang telah diisi ke Tim Teknis Dinas Kominfo melalui saluran komunikasi resmi.

2. Mendapatkan Kredensial

Setelah permohonan disetujui, Anda akan mendapatkan parameter berikut. Harap simpan baik-baik.

Parameter	Deskripsi	Tingkat Kerahasiaan
App ID (Client ID)	Identitas publik aplikasi Anda di sistem SSO.	🟢 Publik (Boleh terlihat di url/frontend)
App Secret	Kunci rahasia untuk validasi pertukaran token.	🔴 SANGAT RAHASIA (Wajib di sisi Server/Backend)
Endpoint URL	Alamat server Issuer SSO.	https://dev-sso.denpasarkota.go.id (Dev)

3. Konfigurasi Environment

Terlepas dari bahasa pemrograman yang Anda gunakan (PHP, Node.js, Go, dll), kami sangat menyarankan untuk menyimpan kredensial dalam Environment Variable (.env), bukan di-hardcode dalam kodingan.

Contoh standarisasi variabel dalam file .env aplikasi:

.env

# Contoh konfigurasi
SSO_ISSUER_URL=https://dev-sso.denpasarkota.go.id
SSO_APP_ID=masukkan_app_id_anda_disini
SSO_APP_SECRET=masukkan_app_secret_panjang_anda_disini
SSO_REDIRECT_URI=http://localhost:3000/callback
SSO_SCOPES=openid profile email custom_data

info

Scopes (Cakupan Data) Agar aplikasi Anda mendapatkan data pengguna yang lengkap, pastikan Anda me-request scope berikut saat inisialisasi:

• openid: Wajib untuk standar OIDC. Tapi sudah default dipanggil dalam Logto
• profile: Untuk mendapatkan Nama Lengkap, Username, Avatar.
• email: Untuk mendapatkan alamat email (jika tersedia).
• custom_data: Untuk mendapatkan data spesifik instansi (NIP, Unit Kerja, dsb) dan data spesifik masyarakat.

4. Struktur Respon Data (User Info)

Berikut adalah contoh struktur JSON (UserInfo) yang akan diterima aplikasi Anda setelah berhasil menukarkan token. Gunakan ini sebagai acuan merancang tabel Users di database lokal Anda.

{
  "sub": "u_1234567890", 
  "name": "I Wayan Developer",
  "username": "u19900xxxxxxxxx",
  "picture": "https://simpeg.denpasarkota.go.id/avatar/u_123456.png)",
  "email": "email@denpasarkota.go.id",
  "email_verified": true,
  "phone_number": "+6281234567890",
  "phone_number_verified": true,
  "custom_data": {
    "user_type": "asn", // atau masyarakat
    "alamat": "xxxx", 
    // pegawai
    "nip": "199001xxxxxxxx",
    "unit_kerja": "012921",
    "jabatan": "Pranata Komputer",
    "peg_id": "PEG2011xx",
    // masyarakat
    "nik": "5171xxxx",
    
  },
  "created_at": 1655799453171
}

Catatan Kolom

sub: Subject ID. Ini adalah ID unik pengguna di sistem SSO. Gunakan nilai ini sebagai Foreign Key atau referensi utama di database aplikasi Anda, karena username (NIP/Email) bisa saja berubah, tetapi sub akan tetap.

custom_data: Field ini berisi data spesifik kepegawaian atau kependudukan yang berbeda antar tipe pengguna (Masyarakat vs ASN).

PENTING

Jangan pernah membagikan App Secret melalui pesan instan (WhatsApp/Telegram) atau menaruhnya di kode JavaScript sisi klien (Browser). Kebocoran App Secret memungkinkan pihak tidak bertanggung jawab menyamar sebagai aplikasi Anda.