Setup Lokal untuk Developer

Panduan ini untuk developer yang bergabung ke project yang sudah menggunakan sauth — bukan untuk migrasi atau instalasi baru. Tujuannya agar aplikasi di local anda bisa berjalan.

Ada dua jenis project:

• Gateway — GWA atau GWC (keduanya setup-nya sama)
• Resource Server — SRF, PNR, PEL, dan lainnya

---

Gateway (GWA / GWC)

GWA dan GWC setup-nya identik dari sisi developer lokal. Keduanya adalah penerbit token — bukan validator token dari luar. Jadi tidak perlu bypass mode.

1. Jalankan bpm:sauth:init

php artisan bpm:sauth:init

Perintah ini idempotent — aman dijalankan meski sudah jalankan oleh yang lain di mesinnya. Akan membuat tabel Passport yang belum ada dan generate key jika belum tersedia.

2. Generate key pair lokal

Key lokal anda sendiri — jangan copy key dari production atau staging.

php artisan bpm:sauth:keygen RS256

Menghasilkan storage/oauth-private.key dan storage/oauth-public.key. Kedua file ini sudah ada di .gitignore — tidak akan ter-commit.

Pakai algoritma lain?

Tanya ke tech lead algoritma apa yang dipakai di staging (SAUTH_SIGN_ALGO), lalu jalankan bpm:sauth:keygen <algo> sesuai itu. Misalnya bpm:sauth:keygen ES256.

3. Tambahkan ke .env

# sauth-server
SAUTH_ISSUER_CODE=gwa                           # Atau 'gwc' sesuai dengan project
SAUTH_DEFAULT_AUDIENCE=internal-services
SAUTH_ALGO=RS256                                # Anda bisa menggunakan algoritma lain
SAUTH_ACCESS_TOKEN_TTL=900
SAUTH_REFRESH_TOKEN_TTL=604800
SAUTH_TOKEN_EXCHANGE_ENABLED=false
SAUTH_PRIVATE_KEY_FILE=oauth-private.key        # Pastikan sesuai dengan nama private key sesungguhnya. Relatif dari folder /storage

# sauth-client
SAUTH_AUDIENCE=gwa                              # Atau 'gwc' sesuai dengan project
GWA_PUBLIC_KEY_FILE=keys/gwapub.key             # Pastikan sesuai dengan nama private key sesungguhnya. Relatif dari folder /storage
GWA_APP_URL=http://127.0.0.1:10100
GWC_PUBLIC_KEY_FILE=keys/gwcpub.key             # Pastikan sesuai dengan nama private key sesungguhnya. Relatif dari folder /storage
GWC_APP_URL=http://127.0.0.1:10200
SAUTH_BYPASS=false                              # Nyalakan apabila ingin menggunakan mocking token
SAUTH_JTI_BYPASS=false
SAUTH_FAKE_CLAIMS_FILE=sauth-fake-claims.json   # Gunakan command publish untuk mengatur ini. Relatif dari folder /storage

Khusus GWA

Jika project menggunakan token exchange, tambahkan:

SAUTH_TOKEN_EXCHANGE_ENABLED=true

4. Daftarkan OAuth client lokal (jika perlu)

Sejatinya hanya akan butuh ini

# 1p resource server client (agar ticketbooth bisa issue token ke service tertentu)
php artisan bpm:sauth:client --first
# Ketika ditanya service code, isi dengan SAUTH_AUDIENCE dari resource server tsb (misal: srf)

Namun apabila anda perlu test ticketbooth atau PKCE flow secara lokal:

# 1p user client (PKCE — untuk frontend)
php artisan bpm:sauth:client --first --user

# 1p M2M client (client_credentials — untuk service worker)
php artisan bpm:sauth:client --first

Salin client_id dan client_secret yang muncul ke .env atau config frontend anda.

5. Bagikan public key ke resource server

Resource server yang jalan di lokal dan perlu validasi token dari gateway anda menggunakan storage/oauth-public.key. Copy file tersebut ke folder storage/keys/ di project resource server.

---

Resource Server (SRF, PNR, PEL, …)

Resource server hanya memvalidasi token, tidak menerbitkan. Untuk development lokal, anda memiliki dua pilihan: pakai token asli dari gateway lokal, atau pakai bypass mode.

Untuk hampir semua pekerjaan development sehari-hari, bypass mode adalah pilihan yang tepat.

1. Tambahkan ke .env

# Identitas service ini
SAUTH_AUDIENCE=srf           # kode service

# Algoritma per-issuer — sesuaikan dengan SAUTH_SIGN_ALGO di masing-masing gateway
SAUTH_GWA_ALGO=RS256
SAUTH_GWC_ALGO=RS256

# Path ke public key masing-masing gateway
GWA_PUBLIC_KEY_FILE=keys/gwa_public.key
GWC_PUBLIC_KEY_FILE=keys/gwc_public.key

2. Ambil public key dari gateway

Dari project gateway copy storage/oauth-public.key, lalu letakkan di:

storage/keys/gwa_public.key

Buat foldernya dulu jika belum ada:

mkdir storage/keys

Anda dapat skip langkah ini

Apabila anda ingin menggunakan bypass mode (langkah 3), public key tidak diperlukan untuk development lokal. Bypass mode melewati verifikasi signature sepenuhnya.

3. Setup bypass mode lokal

Bypass mode memungkinkan anda bekerja tanpa JWT sungguhan. Tidak aktif di production.

Tambahkan ke .env:

SAUTH_BYPASS=perm   # skip signature, fet, dan scope — structural check tetap jalan

Pilih salah satu cara inject user palsu:

Option A — JSON file (disarankan)

php artisan bpm:sauth:fake publish
# Menulis storage/sauth-fake-claims.json — edit bebas, sudah di .gitignore

Option A — .env tambahan

SAUTH_FAKE_CLAIMS_FILE=sauth-fake-claims.json

Option B — Flat env vars

SAUTH_FAKE_SID=your-user-id
SAUTH_FAKE_SNM=Nama anda
SAUTH_FAKE_FET=wm           # 'wm' lolos semua permission check; atau pakai 'psn', 'user.read', dll

Middleware mana pakai profile mana? (Option A)

Middleware	Kunci JSON
sauth.gate / sauth.dual	1p_user
sauth.m2m	1p_m2m
sauth.scope	3p_m2m

Edit file storage/sauth-fake-claims.json untuk mengubah sid, snm, fet, dll.

4. Tidak perlu artisan command tambahan

Resource server tidak punya tabel Passport dan tidak perlu generate key. Jalankan dev server, lalu semua route yang dilindungi middleware sauth otomatis menggunakan fake claims yang sudah anda atur.

Kalau project menerima API key JWT, ada langkah tambahan — lihat langkah 5. Kalau tidak yakin, tanya tech lead. Kebanyakan resource server tidak perlu ini.

5. Dukungan API key JWT (opsional)

Lewati langkah ini kalau project tidak menerima API key JWT.

Publikasi dan jalankan migrasi blacklist:

php artisan bpm:sauth:jti publish-migration
php artisan migrate

Tambahkan ke .env jika GWA menandatangani API key JWT dengan key terpisah (tanya tech lead):

APIKEY_PUBLIC_KEY_FILE=keys/gwa_apikey_public.key   # path relatif dari storage/
SAUTH_APIKEY_ALGO=RS256                              # algo yang dipakai untuk API key JWT

Jika tidak di-set, guard akan fallback ke public key dan algoritma GWA yang biasa — cukup untuk sebagian besar setup di mana GWA memakai key yang sama untuk semua token.

Bypass lokal untuk blacklist (kalau tidak mau jalankan migrasi di lokal):

SAUTH_JTI_BLACKLIST_BYPASS=true

Melewati lookup ke tabel sauth_blacklisted_jti_tokens saat app()->isLocal() bernilai true. Tidak aktif di production.

6. Baca data user via auth()

Setelah middleware sauth berjalan, user yang sudah terautentikasi langsung terdaftar di guard. Gunakan auth('api')->user() di controller — tidak perlu decode JWT secara manual:

$user = auth('api')->user(); // MicroserviceUser

$user->getSid();        // user ID (atau client_id untuk M2M, nama app untuk API key JWT)
$user->getSnm();        // nama tampilan — null untuk M2M token
$user->getFet();        // permission — null untuk M2M token
$user->isM2M();         // true jika token tidak punya snm (machine-to-machine)
$user->isFirstParty();  // true jika fp === '1p'

Bypass mode juga pakai auth()

Di bypass mode (SAUTH_BYPASS), guard sudah diisi dari fake claims file atau flat env var. auth('api')->user() tetap bekerja sama persis — tidak ada penanganan khusus.

---

Referensi cepat — env var yang anda butuhkan

Env Var	Gateway	Resource Server	Keterangan
SAUTH_ISSUER_CODE	Wajib	—	gwa atau gwc
SAUTH_SIGN_ALGO	Wajib	—	Algoritma signing gateway
SAUTH_PRIVATE_KEY_FILE	Wajib	—	Path private key, relatif dari storage/
SAUTH_AUDIENCE	—	Wajib	Kode service ini, misal srf
SAUTH_GWA_ALGO	—	Wajib	Algoritma token dari GWA (v0.3.3+)
GWA_PUBLIC_KEY_FILE	—	Wajib	Path public key GWA, relatif dari storage/
SAUTH_GWC_ALGO	—	Jika terima token GWC	v0.3.3+
GWC_PUBLIC_KEY_FILE	—	Jika terima token GWC
SAUTH_ALGO	Fallback	Fallback	Dipakai jika flag spesifik tidak di-set
APIKEY_PUBLIC_KEY_FILE	—	Jika terima API key JWT	Public key terpisah untuk API key JWT; fallback ke GWA_PUBLIC_KEY_FILE
SAUTH_APIKEY_ALGO	—	Jika terima API key JWT	Algo untuk API key JWT; fallback ke SAUTH_GWA_ALGO
SAUTH_JTI_BLACKLIST_BYPASS	—	Dev lokal	Skip lookup tabel blacklist saat app()->isLocal()
SAUTH_BYPASS	—	Dev lokal	perm untuk sebagian besar kasus
SAUTH_FAKE_CLAIMS_FILE	—	Dev lokal	Path ke file JSON fake claims
SAUTH_FAKE_SID / SNM / FET	—	Dev lokal	Fallback flat env var