Setiap tim API menemui kendala yang sama. Endpoint bekerja secara terpisah, lalu seseorang mengaktifkan OAuth 2.0 dan separuh suite pengujian mulai mengembalikan kode 401. Tiba-tiba Anda harus mengelola server otorisasi, token akses berumur pendek, dan lingkup (scopes), serta menyalin token secara manual dari respons curl ke bidang header terasa melelahkan setelah percobaan ketiga.
Solusinya bukan dengan melewatkan otentikasi dalam pengujian Anda. Solusinya adalah menjadikan penanganan token sebagai bagian dari pengaturan pengujian sehingga bukan lagi pekerjaan manual. Panduan ini membahas dua alur (flows) yang akan Anda temui di hampir setiap rencana pengujian: alur kode otorisasi OAuth (dengan PKCE) untuk API yang bertindak atas nama pengguna, dan alur kredensial klien (client credentials) untuk panggilan antar-mesin (machine-to-machine). Jika Anda ingin peta lengkap jenis grant terlebih dahulu, ikhtisar alur OAuth 2.0 kami menjelaskan semuanya.
Kemudian kita akan langsung praktik: mengonfigurasi otentikasi OAuth 2.0 di Apidog, mengambil token sekali dan menggunakannya kembali di seluruh permintaan, membiarkan token yang kedaluwarsa disegarkan secara otomatis, mewarisi otentikasi di tingkat folder, dan menguji jalur kegagalan yang akan ditanyakan dalam tinjauan keamanan Anda.
Dua alur yang penting untuk pengujian API
OAuth 2.0 mendefinisikan beberapa jenis grant (pemberian otorisasi), tetapi untuk pengujian API sehari-hari, Anda akan banyak menghabiskan waktu dengan dua di antaranya. Pilih berdasarkan satu pertanyaan: apakah API bertindak atas nama pengguna, atau atas nama layanan?
Alur kode otorisasi, dengan PKCE
Alur kode otorisasi adalah cara standar untuk mendapatkan token yang terikat pada pengguna. Klien mengirim pengguna ke server otorisasi, pengguna masuk dan memberikan persetujuan, server mengarahkan kembali dengan kode satu kali, dan klien menukar kode tersebut dengan token akses di endpoint token. RFC 6749 mendefinisikan seluruh proses tersebut di bagian 4.1.
PKCE (Proof Key for Code Exchange, RFC 7636) memperkuat pertukaran. Klien menghasilkan verifier acak, mengirimkan challenge yang di-hash dengan permintaan otorisasi, lalu membuktikan bahwa ia memegang verifier asli saat menukarkan kode. Penyerang yang menyadap kode tidak dapat menggunakannya. PKCE dimulai sebagai perbaikan untuk aplikasi seluler, tetapi panduan saat ini dari oauth.net merekomendasikannya untuk setiap pertukaran kode otorisasi, termasuk klien rahasia (confidential clients).
Uji dengan alur ini kapan pun perilaku endpoint bergantung pada siapa penggunanya: GET /orders hanya mengembalikan pesanan pemanggil, endpoint admin yang dibatasi peran, batasan laju per pengguna.
Alur kredensial klien
Pemberian otorisasi kredensial klien OAuth 2.0 melewatkan pengguna sepenuhnya. Klien mengotentikasi dengan ID dan rahasianya sendiri dan menerima token yang mewakili aplikasi itu sendiri. Satu permintaan POST ke endpoint token, tanpa browser, tanpa pengalihan:
curl -X POST https://auth.example.com/oauth/token \
-d grant_type=client_credentials \
-d client_id=orders_service \
-d client_secret=s3cr3t_value \
-d scope="orders:read orders:write"
Ini adalah alur untuk API antar-mesin (machine-to-machine): layanan mikro internal, cron job, pipeline CI yang memanggil API deployment. Ini juga merupakan tulang punggung pengujian otomatis, karena tidak memerlukan campur tangan manusia. Jika lingkungan pengujian Anda memungkinkan Anda menyediakan klien pengujian, gunakan kredensial klien untuk semuanya kecuali kasus di mana identitas pengguna adalah hal yang diuji.
Mengonfigurasi otentikasi OAuth 2.0 di Apidog
Apidog memperlakukan OAuth 2.0 sebagai tipe otentikasi kelas satu. Anda mengonfigurasinya sekali, di tab Auth dari permintaan atau folder, dan platform menangani pengambilan, lampiran, dan penyegaran token. Jenis grant yang didukung meliputi Authorization Code, Authorization Code (With PKCE), Client Credentials, Password Credentials, dan Implicit.
Berikut adalah pengaturan untuk dua alur di atas, menggunakan API manajemen pesanan fiktif.
Pengaturan kredensial klien
Buka permintaan (atau lebih baik, folder; lebih lanjut tentang ini di bawah), alihkan jenis otentikasi ke OAuth 2.0, dan pilih Client Credentials sebagai jenis grant. Isi:
- URL Token Akses:
https://auth.example.com/oauth/token - ID Klien:
orders_service - Rahasia Klien: rahasia yang Anda sediakan
- Lingkup (Scope):
orders:read orders:write(diatur di bawah opsi lanjutan)
Apidog memberi Anda dua cara untuk mengirim kredensial: sebagai header Basic Auth atau di badan permintaan. Sesuaikan dengan apa yang diharapkan oleh server otorisasi Anda; Auth0 dan Okta menerima keduanya, tetapi beberapa server internal hanya menguraikan badan permintaan.
Klik Dapatkan Token. Apidog memanggil endpoint token, menyimpan hasilnya, dan menampilkan token beserta periode validitasnya. Sejak saat itu, setiap pengiriman melampirkannya ke header Authorization dengan prefiks Bearer. Tanpa salin-tempel, tanpa penyambungan variabel {{token}}.
Pengaturan kode otorisasi dengan PKCE
Untuk pengujian konteks pengguna, pilih Authorization Code (With PKCE) sebagai jenis grant. PKCE adalah opsi grant-nya sendiri di Apidog, bukan kotak centang. Anda akan membutuhkan beberapa bidang lagi:
- URL Otentikasi:
https://auth.example.com/oauth/authorize - URL Token Akses:
https://auth.example.com/oauth/token - URL Callback: URI pengalihan yang terdaftar dengan penyedia Anda
- ID Klien dan Rahasia Klien: dari pendaftaran aplikasi OAuth Anda
Klik Dapatkan Token dan Apidog akan membuka jendela browser yang mengarah ke halaman login. Masuk sebagai pengguna pengujian Anda, setujui layar persetujuan, dan token akan kembali dan mendarat di slot terkelola yang sama seperti sebelumnya. Jika penyedia Anda mengembalikan token ID OpenID Connect bersama token akses, opsi Token Type Used memungkinkan Anda beralih token mana yang akan dilampirkan; berguna saat API yang diuji memvalidasi token ID.
Satu tips praktis: sediakan pengguna pengujian khusus untuk setiap peran yang perlu Anda cakup (pembeli, admin, auditor hanya-baca). Mengambil token sebagai setiap pengguna dan menjalankan ulang skenario yang sama adalah cara tercepat untuk memverifikasi aturan akses berbasis peran.
Penggunaan kembali token dan penyegaran otomatis
Token akses kedaluwarsa, biasanya dalam waktu satu jam. Sebelum Apidog menangani ini, token yang kedaluwarsa berarti kegagalan eksekusi dan pengambilan ulang manual, yang merupakan jenis kegagalan tidak konsisten yang cenderung diabaikan oleh tim.
Kini Apidog menyegarkan token OAuth 2.0 secara otomatis ketika server otorisasi mengeluarkan token penyegaran (refresh token), sebuah kemampuan yang dirilis dalam pembaruan Juni. Ketika token akses yang tersimpan kedaluwarsa, Apidog menggunakan token penyegaran untuk mendapatkan yang baru dan menggantinya sebelum mengirim. Anda juga dapat mengarahkannya ke URL token penyegaran kustom di pengaturan lanjutan jika penyedia Anda memisahkan kedua endpoint tersebut.
Untuk kredensial klien, banyak server melewatkan token penyegaran sepenuhnya (spesifikasi mengizinkannya, karena klien dapat mengotentikasi ulang kapan saja). Dalam praktiknya ini tidak merugikan: pengambilan ulang dengan Dapatkan Token adalah satu klik, dan eksekusi terjadwal atau CI dapat meminta token baru di awal setiap eksekusi.
Mewarisi otentikasi di tingkat folder
Mengonfigurasi OAuth pada setiap permintaan adalah ketinggian yang salah (pendekatan yang tidak efisien). Apidog memungkinkan Anda mengatur otentikasi pada sebuah folder, dan permintaan di dalamnya mewarisi konfigurasi dari induknya. Atur OAuth 2.0 sekali pada folder "Orders API" Anda dan setiap permintaan di bawahnya, termasuk yang baru ditambahkan rekan tim Anda di sprint berikutnya, akan mengirimkan token yang terkelola yang sama.
Ini paling penting dalam skenario pengujian multi-langkah. Skenario checkout mungkin merangkai POST /carts, POST /carts/{id}/items, dan POST /orders. Dengan otentikasi tingkat folder, ketiga langkah tersebut berbagi satu token dan satu konfigurasi. Ketika token kedaluwarsa di tengah skenario, penyegaran otomatis akan menanganinya. Dan ketika tim keamanan Anda merotasi rahasia klien, Anda memperbarui satu folder daripada empat puluh permintaan.
Permintaan tetap memiliki opsi untuk mengesampingkan induk, yang persis seperti yang Anda inginkan untuk pengujian negatif. Lebih lanjut tentang itu sekarang.
Menguji jalur kegagalan
Pengujian OAuth jalur sukses membuktikan bahwa pipeline token Anda berfungsi. Pengujian jalur kegagalan membuktikan bahwa API Anda menerapkan otentikasi. Melewatkannya berarti Anda memercayai pengaturan bawaan framework. Berikut adalah tiga kasus yang layak diotomatisasi; untuk penyegar tentang arti setiap kode status, lihat perbandingan kunci API dan token bearer kami.
Token kedaluwarsa atau hilang: harapkan 401
Gandakan satu permintaan dalam skenario Anda dan timpa otentikasi yang diwarisi dengan tanpa otentikasi atau token bearer yang sudah kedaluwarsa dan di-hardcode, seperti Bearer expired_token_do_not_rotate. Tegaskan pada:
- Kode status sama dengan
401 - Header respons
WWW-Authenticateada (pendamping RFC 6749, RFC 6750, mengharapkannya) - Body tidak membocorkan stack trace atau nama host internal
Kode 200 di sini adalah bug kritis. Kode 403 adalah "bau desain" yang layak diberi tiket (perbaikan): server harus membedakan antara "Saya tidak tahu siapa Anda" dan "Saya tahu Anda, dan tidak."
Lingkup salah: harapkan 403
Sediakan klien pengujian kedua yang dibatasi pada orders:read, ambil tokennya, dan panggil endpoint tulis seperti POST /orders. Tegaskan bahwa statusnya adalah 403 dan, jika API Anda mengikuti RFC 6750, header WWW-Authenticate menyertakan error="insufficient_scope". Pengujian ini menangkap kesalahan konfigurasi klasik di mana lingkup diperiksa di gateway untuk beberapa rute dan terlupakan di rute lain. Jika lingkup adalah hal baru bagi tim Anda, penjelasan lingkup OAuth 2.0 membahas cara membaginya.
Klien tidak valid: harapkan kesalahan endpoint token yang bersih
Arahkan permintaan langsung ke https://auth.example.com/oauth/token dengan client_secret palsu. Berdasarkan RFC 6749 bagian 5.2, server harus mengembalikan 400 (atau 401 untuk otentikasi klien yang gagal) dengan badan JSON yang berisi "error": "invalid_client". Tegaskan keduanya. Server otorisasi juga merupakan API, dan kontrak kesalahan mereka adalah bagian dari permukaan Anda.
Menegaskan respons token dalam skenario pengujian
Endpoint token layak mendapatkan cakupan tersendiri di luar kasus klien tidak valid. Tambahkan langkah dalam skenario pengujian Anda yang memanggil endpoint token secara langsung, lalu lampirkan penegasan pada respons:
access_tokenada dan tidak kosongtoken_typesama denganbearer(tidak peka huruf besar-kecil per spesifikasi)expires_inlebih besar dari 0 dan sesuai dengan kebijakan Anda, katakanlah tidak lebih dari 3600scopesesuai dengan yang diminta, menangkap server yang secara diam-diam mempersempit grant
Skenario pengujian Apidog memungkinkan Anda menambahkannya sebagai penegasan visual pada JSON respons, tanpa perlu skrip, dan Anda dapat mengekstrak access_token ke dalam variabel untuk langkah selanjutnya ketika Anda ingin menguji handshake mentah daripada menggunakan otentikasi yang dikelola. Sambungkan skenario ke eksekusi CI Anda dan server otorisasi yang berperilaku buruk akan menggagalkan build alih-alih muncul sebagai 401 misterius di produksi.
Alur lengkapnya terlihat seperti ini: konfigurasi OAuth 2.0 tingkat folder untuk jalur sukses, penimpaan per permintaan untuk kasus 401 dan 403, dan satu skenario yang menguji kontrak endpoint token. Ini mencakup API konteks pengguna melalui kode otorisasi dengan PKCE dan API layanan-ke-layanan melalui kredensial klien, dengan penyegaran token ditangani untuk Anda. Unduh Apidog dan coba secara gratis; tipe otentikasi OAuth 2.0 berfungsi pada paket gratis, sehingga Anda dapat mengarahkannya ke endpoint token Anda sendiri dalam beberapa menit.
Pertanyaan Umum (FAQ)
Alur OAuth mana yang harus saya gunakan untuk pengujian API?
Gunakan kredensial klien untuk apa pun yang antar-mesin dan untuk sebagian besar suite otomatis, karena tidak memerlukan interaksi browser. Gunakan alur kode otorisasi dengan PKCE ketika pengujian bergantung pada identitas pengguna: isolasi data per pengguna, pemeriksaan peran, atau perilaku persetujuan. Hindari grant implisit dan kata sandi dalam rencana pengujian baru; keduanya tidak disarankan dalam panduan OAuth saat ini.
Bagaimana cara menyegarkan token yang kedaluwarsa secara otomatis di Apidog?
Konfigurasikan OAuth 2.0 di tab Auth dan ambil token dengan Dapatkan Token. Ketika server otorisasi mengembalikan token penyegaran, Apidog menyegarkan token akses saat kedaluwarsa tanpa Anda harus mengotentikasi ulang, dan Anda dapat mengatur URL token penyegaran terpisah di pengaturan lanjutan jika penyedia Anda menggunakannya. Untuk pengaturan kredensial klien tanpa token penyegaran, menjalankan ulang Dapatkan Token akan mengeluarkan token baru.
Bisakah setiap permintaan dalam skenario berbagi satu token OAuth?
Ya. Atur konfigurasi OAuth 2.0 pada folder induk dan permintaan di dalamnya akan mewarisinya, sehingga skenario multi-langkah berjalan di bawah satu token yang dikelola. Permintaan individual masih dapat mengesampingkan konfigurasi folder, inilah cara Anda menyisipkan pengujian negatif (token kedaluwarsa, lingkup salah) ke dalam skenario yang sama.
Apa arti 401 versus 403 dalam API yang dilindungi OAuth?
Kembalikan 401 ketika otentikasi gagal: token hilang, kedaluwarsa, atau salah format. Kembalikan 403 ketika token valid tetapi tidak memiliki izin, seperti lingkup yang hilang. Mencampuradukkannya merusak logika coba ulang klien, karena 401 memberi tahu klien untuk mengotentikasi ulang sementara 403 memberi tahu untuk berhenti. Panduan kami tentang pengujian otentikasi JWT menggali lebih dalam tentang memvalidasi token itu sendiri.