Menjawab masalah ReCaptcha Phone Approval secara langsung

Ketika backend authentication Anda mulai menerima 403 Forbidden atau timeout di endpoint login/registration, kemungkinan besar ReCaptcha terbaru menolak request karena approved phone tidak tersedia. Solusi yang efektif adalah mengidentifikasi titik transport token, menambahkan observability atas status approval, dan menerapkan mekanisme fallback atau retry yang memicu prompt persetujuan telepon. Artikel ini membahas gejala, reproduksi, penyebab mendasar, serta langkah perbaikan dan pengujian konkret.

Gejala dan dampak langsung bagi pengguna

Gejala yang teramati pada backend adalah:

  • 403 atau 401 tiba-tiba pada endpoint auth yang sebelumnya berfungsi tanpa perubahan kode utama.
  • Timeout ketika middleware ReCaptcha menunggu respons dari Google sebelum menolak.
  • Log error berbunyi seperti "request blocked" atau "phone approval required" di layer gateway.

Pengguna tidak diberi tahu kenapa login gagal, hanya menerima error generik atau spinner panjang. Hal ini menurunkan konversi otentikasi dan meningkatkan support ticket.

Reproduksi masalah di lingkungan pengembangan

Langkah reproduksi standar:

  1. Gunakan klien yang belum pernah menyetujui nomor telepon pada browser atau emulator.
  2. Kirim request ke API auth dengan token ReCaptcha terbaru (biasanya diperoleh lewat grecaptcha.execute).
  3. Perhatikan respons backend, serta inspect header request untuk memastikan token tersedia.

Jika backend menolak, catat nilai header recaptcha-token dan gunakan curl/HTTP client untuk membandingkan:

curl -X POST https://api.example.com/auth/login \
  -H "Content-Type: application/json" \
  -H "recaptcha-token: " \
  -d '{"username":"user","password":"pass"}'

ReCaptcha versi baru akan menolak jika header approval telepon tidak dikirim atau tidak valid.

Akar masalah: token transport dan approval state

ReCaptcha QR Code terbaru menyertakan check tambahan terhadap "approved phone". Beberapa faktor yang menyebabkan penolakan:

  • Token tidak melalui transport layer berarti middleware tidak membaca header khusus karena nama field berubah atau tidak diteruskan saat request proxy.
  • No fallback token ketika sistem hanya memproses satu nilai token, padahal Google dapat mengeluarkan token alternatif yang mengandung approval flag.
  • Header X-Approved-Phone (atau nama lain) tidak disertakan pada request internal, sehingga validasi langsung gagal.

Periksa seluruh chain request dari frontend ke backend: balancer, gateway, dan middleware harus menjaga header persetujuan ini tetap utuh.

Langkah perbaikan praktis

1. Tambahkan observability atas approval state

Masukkan logging struktural dan metric ketika token ReCaptcha diterima, termasuk flag approval. Contoh implementasi di Node.js:

const { createLogger } = require('pino');
const logger = createLogger();

app.post('/auth/login', (req, res, next) => {
  const token = req.headers['recaptcha-token'];
  const approval = req.headers['x-approved-phone'];
  logger.info({ tokenExists: Boolean(token), approval }, 'captcha headers');
  // lanjutkan validasi
});

Metric seperti recaptcha_approval_missing_total membantu deteksi regresi cepat.

2. Tambahkan retry dengan prompt approval

Jika token awal ditolak, sediakan mekanisme retry yang memicu client untuk meminta persetujuan ulang. Backend bisa mengembalikan status khusus (misal 428 Upgrade Required) agar frontend memanggil ulang ReCaptcha dengan opsi approval.

Frontend harus menangani respons khusus ini dan menyarankan user untuk mengkonfirmasi nomor telepon saat prompt QR ReCaptcha muncul.

3. Mitigasi privasi dan dokumentasi aturan perusahaan

Terkait privacy, pastikan hanya header yang diperlukan diteruskan. Pangkas data sensitif dan tambahkan dokumentasi internal mengenai aturan transport header ReCaptcha. Contoh aturan:

  • Header approval tidak boleh ditulis ke log yang tidak terenkripsi.
  • Gunakan enkripsi end-to-end pada traffic internal yang mentransfer token.

Pengujian dan regresi yang direkomendasikan

Untuk memastikan patch menjaga status approval:

  • Test unit middleware yang memeriksa keberadaan header approval tanpa memanggil Google.
  • Integration test menggunakan stub ReCaptcha service yang dapat mengembalikan