Memperjelas masalah utama

Endpoint refresh token sering menjadi target serangan karena mempertahankan sesi jangka panjang. Hardening OAuth Refresh Flow menuntut validasi payload secara ketat, pembatasan rate sesuai risiko, rotasi secret, proteksi terhadap reuse, serta audit yang mendeteksi abuse seperti geolokasi anomali. Artikel ini memberi langkah praktis agar sesi tetap aman tanpa memperburuk pengalaman pengguna.

1. Memodelkan flow refresh token yang aman

Flow refresh token harus dimulai dengan validasi input dari client: pastikan request membawa refresh_token yang valid, client_id konsisten, dan header TLS yang sesuai. Jangan langsung mengembalikan token baru tanpa cross-check.

Flow sederhana

  1. Client mengirim payload {refresh_token, client_id, grant_type=refresh_token}.
  2. Server memverifikasi signature/format dan mencocokkan client_id dengan record konsumen.
  3. Server mengecek status refresh_token (aktif, belum digunakan ulang) dan metadata risiko (lokasi, device).
  4. Jika valid, issue access token baru, rotasi refresh token, dan audit entry.

Setiap langkah harus di-instrumentasi untuk memudahkan debugging dan audit.

2. Validasi payload dan kondisi token

Validasi harus lebih dari sekadar memeriksa format JSON. Contoh praktik:

  • Gunakan schema validator untuk grant_type, client_id, refresh_token. Tolak parameter ekstra yang tidak terpakai.
  • Periksa konsistensi client_id dengan refresh_token yang tersimpan (tidak hanya cek signature, tapi juga mapping ke owner).
  • Periksa metadata tambahan seperti IP terakhir, user agent, dan timestamp penerbitan untuk mendeteksi mismatch yang jelas.
  • Gunakan short-lived nonce di payload untuk mencegah replay pada transport level.

Contoh validasi payload (Node.js/Express)

app.post('/oauth/refresh', async (req, res) => {
  const schema = z.object({
    grant_type: z.literal('refresh_token'),
    refresh_token: z.string().min(20),
    client_id: z.string().uuid()
  });

  const payload = schema.safeParse(req.body);
  if (!payload.success) return res.status(400).json({error: 'invalid_request'});

  const tokenRecord = await store.getRefreshToken(payload.data.refresh_token);
  if (!tokenRecord || tokenRecord.client_id !== payload.data.client_id) {
    return res.status(401).json({error: 'invalid_grant'});
  }
  // lanjutkan ke langkah rate limit dan rotasi
});

Pentinya: jangan lemahkan validasi hanya karena refresh token berada dalam cookie yang tampak aman.

3. Adaptive rate limit untuk endpoint refresh

Rate limit statis dapat mengganggu UX, tetapi tidak ada limit membuat endpoint rentan brute force. Terapkan rate limit adaptif:

  • Baseline: limit per client_id/per IP untuk traffic normal (misal 10 request/menit).
  • Elevated: jika ada error invalid_grant berulang atau mismatch geolokasi, turunkan limit per detik secara dinamis.
  • Cooldown individual: batasi refresh token yang sama agar hanya bisa dipakai sekali per interval pendek.

Gunakan algorithm seperti token bucket dengan weight tambahan untuk error. Sistem rate limit harus mengembalikan header respons yang menjelaskan sisa limit agar client bisa menyesuaikan.

4. Rotasi secret dan proteksi reuse

Setiap kali refresh token digunakan, buat token baru dan tandai token lama sebagai revoked. Ini mencegah replay jika token dicuri.

  • Simpan refresh token dan metadata dalam database dengan status {active, revoked, used}. Setelah issuance token baru, update status token lama menjadi used.
  • Pastikan operasi ini atomik (misalnya menggunakan transaksi atau locking) agar token yang sama tidak dapat dipakai dua kali karena race condition.
  • Jika refresh token gagal validasi karena leak (status revoked), trigger workflow notifikasi keamanan dan pendinginan rate limit bahkan tanpa respon 200.

5. Logging, audit, dan deteksi abuse

Catat setiap permintaan refresh token dengan informasi minimal: client_id, refresh_token_hash, IP, user agent, grant_type, outcome. Gunakan hashing untuk menyimpan bagian sensitif.

Deteksi geolokasi anomali

Bandingkan IP target dengan pola sebelumnya. Jika token biasanya dipakai dari Jakarta dan tiba-tiba muncul dari São Paulo, tingkatkan pengawasan:

  • Jangan langsung blok; kembalikan error consent_required atau invalid_grant sambil mencatat kejadian.
  • Gabungkan data geolokasi dengan device fingerprint untuk menghindari false positive.

Audit trail

Audit log harus dapat dipakai untuk menjelaskan insiden. Buat channel terpisah untuk penyimpanan log (misalnya stack logging ke SIEM), jangan hanya rely di database produksi.

6. Strategi penanganan kesalahan

Respons refresh token harus konsisten:

  • Gunakan 400 untuk payload invalid, 401 untuk token tidak valid, dan 429 untuk rate limit.
  • Berikan pesan minimalis agar informasi sensitif tidak bocor.
  • Log error secara detail di server untuk keperluan debugging.

7. Checklist keamanan sebelum deploy

  • Validasi schema lengkap dan schema testing request-tool (Postman/Automation).
  • Rate limit adaptif diuji dengan traffic tinggi + pola abuse.
  • Rotasi refresh token dan proteksi reuse diverifikasi lewat uji integrasi (token lama tidak bisa dipakai lagi).
  • Logging audit di-stream ke SIEM, retention ditentukan sesuai kebijakan.
  • Deteksi abuse diaktifkan (misalnya geolokasi, device fingerprint, suspicious spike) dan alert diuji.
  • Penanganan kesalahan sudah konsisten dan tidak menampilkan informasi sensitif di respons.

Hardening OAuth Refresh Flow bukan hanya menambahkan lapisan keamanan, tapi menjaga keseimbangan antara perlindungan dan kenyamanan pengguna. Terapkan proteksi secara terukur dan monitoring berkelanjutan.