Proof-of-Possession untuk API Auth: masalah yang diselesaikan

Proof-of-Possession (PoP) relevan ketika secret atau token bisa bocor, misalnya lewat log atau credential kompromi. Alih-alih mengandalkan bearer token saja, PoP menuntut klien membuktikan bahwa mereka benar-benar memegang key yang terkait dengan credential itu, lewat signature terhadap request. Pendekatan ini mengurai threat model pencurian: meski token diamankan, penyerang juga harus memiliki akses ke secret untuk menandatangani permintaan tertentu.

Artikel ini langsung membahas implementasi PoP API: desain header, validasi signature dan nonce, rate limit berbasis credential, rotasi secret otomatis, monitoring abuse, serta strategi fallback ketika verifikasi gagal.

Threat Model dan tujuan PoP

Model ancaman utama adalah token atau secret yang dicuri melalui log, cache, atau intercept jaringan internal. Attack vector yang biasa terjadi:

  • Token yang terekspos di log aplikasi.
  • API key yang dicuri dari frontend dan dipakai berulang.
  • Replay request setelah mencuri signature yang valid.

PoP menambahkan lapisan verifikasi: server memvalidasi signature request yang terikat dengan data request (method, path, body) dan nonce/timestamp. Jika penyerang memiliki token tetapi tidak secret, signature gagal diverifikasi.

Desain header dan payload PoP

Struktur header PoP

Header PoP standar memuat Authorization: PoP ditambah metadata. Contoh header:

Authorization: PoP keyId="client-123", algorithm="hmac-sha256", signature=""

Header tambahan minimal meliputi:

  • keyId: identitas credential untuk lookup secret.
  • nonce atau timestamp: mencegah replay.
  • signature: hash signed dari canonical request.

Canonical request bisa menggunakan format sederhana: {method}\n{path}\n{timestamp}\n{bodySHA256}. Server harus menghitung kembali canonical request yang sama untuk memverifikasi signature.

Validasi signature dan nonce

Langkah validasi:

  1. Lihat keyId lalu ambil secret dari penyimpanan aman (vault, database terenkripsi).
  2. Baca timestamp atau nonce untuk memastikan tidak replay. Simpan nonce terakhir tiap keyId dan tolak jika sudah pernah dipakai.
  3. Bangun string canonical dengan data request.
  4. Hitung signature menggunakan algoritme yang ditentukan (misal HMAC-SHA256) dan bandingkan dengan value header.

Jika signature tidak cocok, tolak request dengan 401 dan log detail per reason (expired, nonce reuse, mismatch). Jangan mengungkap detail secret dalam respons.

Contoh request dan response PoP

Header dan payload:

POST /api/orders HTTP/1.1
Host: api.example.com
Authorization: PoP keyId="client-123", nonce="1689234123", signature="SOMESIGN"
Content-Type: application/json

{"productId":5,"qty":2}

Jika signature valid:

HTTP/1.1 200 OK
Content-Type: application/json

{"orderId":1023,"status":"created"}

Jika invalid:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error":"pop_signature_invalid"}

Rate Limit per Credential dan Rotasi Secret

Rate limit berbasis token bucket

Rate limit per credential mencegah misuse walau signature valid—misalnya klien terkompromi mencoba spam API. Implementasi token bucket sederhana:

bucketCapacity = 100
refillRate = 5 tokens/sec per credential

Setiap request menghabiskan 1 token. Jika token habis, tolak 429. Gunakan cache cepat seperti Redis untuk menyimpan counter dan timestamp refill. Alternatif leaky bucket memberikan kontrol yang lebih ketat terhadap burst.

Trade-off: token bucket menangani burst tinggi, tapi memerlukan sinkronisasi ketika deployment multi-instance. Pastikan strategi rate limit tidak memblokir legitimate burst (misal polling realtime) dengan memberi grace limit.

Rotasi secret otomatis

Untuk mitigasi secret bocor, rotasi harus otomatis dan tanpa downtime. Pendekatan:

  • Setiap credential punya currentSecret dan previousSecret.
  • Client diinstruksikan mengambil secret baru via provisioning endpoint.
  • Server validasi signature terhadap kedua secret tersebut selama periode grace (misal 5 menit) sebelum menghapus previousSecret.
  • Gunakan sistem job (cron atau worker) untuk membuat secret baru, mengupdate database terenkripsi, dan mengirim notifikasi pada owner credential.

Catatan: rotasi otomatis menuntut logging audit dan retry bila secret provisioning gagal. Pastikan keyId tetap sama agar client tidak perlu mengganti header.

Monitoring Abuse dan Fallback saat Verifikasi Gagal

Observasi dan alarm

Set monitoring untuk metrik berikut:

  • Rasio signature failure per keyId.
  • Frekuensi nonce reuse.
  • Rate limit hit, termasuk IP dan keyId.
  • Jumlah secret rotation failures.

Gunakan alert jika signature failure melonjak tiba-tiba—ini bisa indikasi replay atau brute force.

Gunakan log terstruktur (JSON) untuk mencatat field seperti keyId, clientIp, requestHash, dan reason (nonce reuse, mismatch). Data ini membantu debugging dan menelusuri abuse.

Fallback ketika verifikasi gagal

Pastikan client menerima respons konsisten:

  • Untuk signature mismatch atau timestamp expired, kirim 401 dengan pesan generik.
  • Untuk nonce reuse atau rate limit, kirim 429 dan sertakan Retry-After.
  • Jika secret rotation menyebabkan temporary invalid, toleransi dengan memperbolehkan previousSecret selama window tertentu.

Jangan memberikan detail yang bisa membantu attacker (misal “secret expired” atau “token valid tapi signature salah”).

Checklist Pengujian dan Observasi

  • Validasi bahwa server menolak request dengan nonce sama dua kali.
  • Uji response saat secret telah dirotasi: client lama masih diproses dalam grace period, lalu ditolak setelah itu.
  • Simulasikan token bucket exhaustion dan pastikan rate limit tercatat serta respons 429 termasuk Retry-After.
  • Periksa log untuk signature failure supaya mudah korelasi dengan IP dan credential.
  • Uji monitoring alert dengan spike signature failure: pastikan notifikasi tim keamanan.

Kesimpulan

Proof-of-Possession memperkuat API authentication terhadap token theft dan replay attack, khususnya jika digabungkan dengan rate limit per credential dan rotasi secret. Desain header PoP, validasi signature/nonce, rate limit, rotasi otomatis, monitoring abuse, dan fallback respons kerangka kerja yang lengkap. Implementasikan secara bertahap—pertama validasi signature, lalu tambahkan rate limit dan rotasi—sementara observabilitas memantau penyalahgunaan.