Pengantar Masalah: Mengapa CLI Auth Gagal?

Di lingkungan backend dengan CLI yang berinteraksi langsung ke API internal, kegagalan autentikasi sering kali muncul sebagai permission denied atau 401 Unauthorized pada tiap percobaan. Untuk menjawab "apa penyebab" dan "bagaimana memperbaikinya" secara langsung: akar masalah ada pada pengelolaan token, konfigurasi cache lokal, dan ketidaksesuaian flow autentikasi CLI dengan layanan target. Artikel ini membahas gejala nyata, observability yang penting, serta tindakan perbaikan praktikal.

Mengamati Gejala Nyata dan Observability

Langkah pertama dalam debugging adalah mengumpulkan bukti konkret. Fokus pada tiga sumber: log CLI, log server API, dan tracing request (jika tersedia). Berikut gejala umum yang muncul:

  • Log CLI: Authentication failed: token expired disusul retry otomatis yang langsung gagal lagi.
  • Log API: request diterima dengan X-User-Id kosong atau header yang tidak valid, menyebabkan flow di middleware gagal.
  • Observability: trace menunjukkan request CLI tidak mencapai service otentikasi karena langkah pembaruan token tidak dipanggil.

Perhatikan juga pola retry: jika CLI langsung mengulang dengan header lama tanpa menunggu respons autentikasi, maka akan terus gagal karena token sudah tidak berlaku.

Menemukan Root Cause

1. Token Lifecycle Tidak Sinkron

CLI biasanya menyimpan token di file lokal atau keystore. Jika backend memperbarui policy token (misalnya waktu hidup dipersingkat) tetapi CLI tidak secara otomatis refresh, maka token kadaluwarsa dan gagal di setiap percobaan. Hal ini diperkuat oleh log WWW-Authenticate: Bearer error="invalid_token".

Solusi: implementasikan flow refresh di CLI. Periksa timestamp expires_at setiap pemanggilan, lalu lakukan refresh melalui endpoint otentikasi-nya. Jangan hanya mengandalkan retry; tambahkan kondisi seperti:

if token.is_near_expiry():
    token = auth_client.refresh(token.refresh_token)
    store_token(token)

Pastikan refresh token juga disimpan aman dan diberi batas percobaan agar tidak memicu throttling.

2. Penyimpanan Token Tidak Aman atau Tidak Konsisten

Token yang tersimpan di cache tidak terenkripsi atau tumpang tindih antar environment (misalnya CLI dev dan prod menggunakan file yang sama) menyebabkan token lama terbaca saat environment seharusnya berbeda.

Solusi: kelola lokasi penyimpanan berdasarkan scope env. Gunakan direktori $HOME/.config/mycli/prod. Terapkan enkripsi ringan (misalnya AES-GCM) jika CLI berjalan di mesin yang rentan. Jangan memaksa token disimpan dalam plain text.

3. Flow Retry Tidak Memahami Error 401

Banyak CLI menganggap 401 setara dengan kegagalan sementara dan langsung retry. Tanpa mekanisme refresh token, retry hanya mengulangi token kadaluarsa. Log akan memperlihatkan pola: Authentication failed (401) diikuti Retrying... sebanyak 3 kali dengan output sama.

Solusi: modifikasi handler error sehingga 401 yang berasal dari WWW-Authenticate: Bearer memicu token refresh terlebih dahulu, baru kemudian retry. Pseudocode:

resp := client.Do(req)
if resp.StatusCode == http.StatusUnauthorized && isBearerError(resp.Body) {
    token = refreshToken()
    req.Header.Set("Authorization", "Bearer "+token.AccessToken)
    resp = client.Do(req)
}

Dengan memisahkan logik ini, kebijakan retry tidak lagi terlalu agresif dan menghindari flood ke server otentikasi.

Implementasi Perbaikan dan Hardening

1. Observability dan Tracing untuk CLI Auth Flow

Tambahkan trace id pada header CLI agar setiap permintaan bisa dihubungkan dengan log server. Misalnya:

Authorization: Bearer eyJ...
X-Trace-Id: cli-20241012-abc123

Jika backend menggunakan solusi tracing seperti OpenTelemetry, log tersebut memudahkan melihat apakah request melewati middleware otentikasi atau ditolak di gateway.

2. Menetapkan Retry dan Circuit Breaker

Gunakan strategi exponential backoff dengan batas maksimum. Pastikan retry hanya terjadi setelah token diperbarui. Jika API mencatat 401 berulang, aktifkan circuit breaker agar CLI berhenti sementara dan memberi notifikasi agar pengguna memeriksa konfigurasi token.

3. Penyesuaian Konfigurasi Token

Periksa policy token di backend: waktu hidup, scope, dan requirement proof-of-possession. Jika CLI tidak mendukung PoP, minta backend menyediakan scope alternatif sebagai fallback. Konsistenkan claim aud dan issuer.

Efek Perbaikan terhadap Reliability

Setelah menyesuaikan refresh token, penanganan 401, dan observability, kita bisa mengukur dampaknya melalui indikator seperti penurunan jumlah failure berantai, Waktu Recovery (MTTR) yang lebih cepat, serta pengurangan log "retry tanpa perubahan". Misalnya, log 401 sekarang dilengkapi tag action=token-refresh dan perintah CLI hanya sekali keluar kesalahan jika refresh benar-benar gagal.

Kesimpulannya, memahami diagnosis CLI Auth Gagal bermula dari pengamatan log, memvalidasi lifecycle token, lalu memperkuat flow retry dan penyimpanan. Dengan pendekatan ini, reliability CLI dan backend meningkat, troubleshooting jadi lebih cepat, dan risiko akses yang tidak sah pun kita kendalikan.