Apa Itu Cloudflare Turnstile? Mode, Token, dan Verifikasi

what is cloudflare turnstile - What Is Cloudflare Turnstile? Modes, Token and Verification

Apa itu Cloudflare Turnstile? Turnstile adalah alternatif CAPTCHA dari Cloudflare. Ia memeriksa pengunjung dengan tes yang berjalan di latar belakang, bukan teka-teki gambar, dan ketika pengunjung lolos, halaman menerima sebuah token yang kemudian diverifikasi oleh server situs ke Cloudflare. Panduan ini membahas tiga mode widget, token beserta batasannya, cara kerja verifikasi, dan cara membedakan widget dari challenge halaman penuh.

Yang dilihat pengunjung: tiga mode widget

Tiga mode dijelaskan dalam dokumentasi widget Cloudflare. Pemilik situs memilih salah satunya saat membuat widget.

ModeYang dilihat pengunjung
Mode managedCloudflare memilih antara pemeriksaan non-interaktif dan checkbox, sehingga checkbox hanya muncul ketika dibutuhkan pemeriksaan lanjutan
Mode non-interactiveWidget dengan indikator berputar selama pemeriksaan berjalan, dan pengunjung tidak pernah diminta melakukan apa pun
Mode invisibleSama sekali tidak ada: tanpa widget dan tanpa indikator berputar, dan pemeriksaan berjalan di latar belakang

Ketiganya tidak meminta pengunjung membaca teks yang terdistorsi atau memilih gambar. Situs tidak harus mengarahkan lalu lintasnya melalui Cloudflare untuk memakai widget ini, menurut ikhtisar Cloudflare, tetapi pemiliknya memang memerlukan akun Cloudflare untuk membuatnya.

Apa yang diberikan Cloudflare Turnstile kepada halaman? Sebuah token

Bagi developer, intinya adalah field formulir bernama cf-turnstile-response, panggilan verifikasi di server dan, ketika Anda mengotomatisasi situs yang memakainya, token yang harus Anda sediakan sendiri. Ketika widget berada di dalam formulir, Cloudflare menyatakan bahwa widget menambahkan input tersembunyi bernama cf-turnstile-response, yang ikut terkirim ke server bersama field lainnya. Widget dapat dirender secara implisit, yaitu memindai markup untuk elemen dengan class cf-turnstile, atau secara eksplisit dengan memanggil turnstile.render() dari skrip halaman. Halaman yang merender secara eksplisit juga dapat meneruskan callback, dan Dokumentasi API CapSkip menyatakan bahwa callback itu dijalankan dengan token yang dikembalikan jika halaman mendefinisikannya.

Token berumur pendek. Panduan validasi sisi server menyatakan bahwa setiap token berlaku 300 detik dan dimaksudkan untuk sekali pakai, dan bahwa Cloudflare melacak penukarannya di seluruh jaringannya dengan jeda. Jadi token yang Anda minta di bagian atas skrip yang panjang bisa sudah terpakai atau basi saat formulir dikirim.

Cara server memverifikasi token

Menerima field itu saja tidak membuktikan apa pun. Cloudflare menyebut validasi sisi server wajib: situs mengirim token dan secret key-nya ke endpoint siteverify, yaitu POST ke https://challenges.cloudflare.com/turnstile/v0/siteverify, lalu membaca jawaban JSON. Nilai yang didokumentasikan ada di bawah.

ArahNilaiArti
Dikirimsecret (wajib)Secret key milik widget
Dikirimresponse (wajib)Token dari field formulir
Dikirimremoteip (opsional)Alamat IP pengunjung
Dikirimidempotency_key (opsional)UUID yang Anda buat agar percobaan ulang untuk pemeriksaan yang sama aman dilakukan
DikembalikansuccessApakah validasi lolos
Dikembalikanchallenge_ts, hostnameKapan challenge dipecahkan dan di mana challenge itu ditampilkan
Dikembalikanerror-codesDaftar seperti missing-input-response atau timeout-or-duplicate
Dikembalikanaction, cdataNilai kustom yang ditetapkan halaman pada widget

Cloudflare mencantumkan tujuh kode error, dan dua di antaranya penting di sini. Kode missing-input-response berarti tidak ada token yang sampai ke Cloudflare, dan timeout-or-duplicate berarti token sudah kedaluwarsa atau sudah divalidasi. Jawaban yang didokumentasikan tidak membawa skor: hasilnya lolos atau gagal, dengan nilai action dan cdata yang ditetapkan halaman Anda agar server dapat memeriksanya. Ini adalah pembacaan atas field yang didokumentasikan, bukan pernyataan dari Cloudflare tentang apa yang tidak pernah dikembalikannya.

Widget atau halaman challenge: Turnstile yang mana?

Widget adalah satu hal dan challenge halaman penuh adalah hal lain. Widget adalah elemen di dalam halaman yang sudah dimuat. Halaman challenge adalah yang ditampilkan Cloudflare sebagai ganti situs, sebelum konten apa pun tiba. Dokumentasi clearance dari Cloudflare menyatakan bahwa menyelesaikan challenge semacam itu menetapkan cookie cf_clearance yang terikat pada pengunjung dan perangkat. Dokumentasi itu juga menyatakan bahwa widget dengan pre-clearance aktif dapat menerbitkan cookie tersebut, sedangkan secara default widget menerbitkan token sekali pakai. Gunakan tabel ini untuk menentukan apa yang Anda hadapi.

Apa yang Anda lihatApa ituYang dibutuhkan CapSkip dari Anda
Kotak atau indikator berputar di dalam formulir, dan input cf-turnstile-response di HTMLWidget, dalam mode managed atau non-interactiveSitekey dan alamat halaman lengkap. Token dimasukkan ke dalam field
Formulir yang gagal tanpa token, tetapi tidak ada kotak di layarWidget dalam mode invisible, atau widget yang tidak berhasil direnderKedua nilai yang sama. Temukan sitekey di markup atau di panggilan render
Halaman penuh yang bertuliskan "Just a moment" sebelum situs dimuatChallenge halaman penuhDua rute CapSkip. Request token Turnstile yang membawa action, data, dan pagedata ketika halaman meneruskannya ke turnstile.render, atau request cookie cf_clearance yang dijelaskan di bawah

Mendapatkan token Turnstile dari CapSkip

CapSkip berjalan di PC Windows Anda sendiri dan menjawab di 127.0.0.1:8080 dalam format request 2captcha, tanpa biaya per pemecahan pada salinan berlisensi. Halaman pemecah Cloudflare Turnstile menjelaskan produknya, dan Dokumentasi API memuat parameter yang dipakai di sini. Jika skrip Anda berjalan di mesin lain, alihkan CapSkip ke mode Server dan pakai alamat PC itu sebagai host, seperti dijelaskan bagian pengaturan koneksi pada panduan penyiapan. CapSkip membuka port-nya untuk semua alamat saat mode Server dimulai, jadi agar port hanya dipakai mesin yang Anda harapkan, tambahkan aturan blokir Windows Firewall untuk alamat lainnya.

Berikut request widget secara manual. Metodenya adalah turnstile, dan Dokumentasi API mencantumkan sitekey dan pageurl sebagai nilai wajib. Setiap panggilan adalah satu baris curl.exe, yang dijalankan PowerShell apa adanya. Di cmd, hilangkan baris yang diawali tanda pagar.

# 1. Submit the task. CapSkip answers with a task id.
curl.exe -s -X POST -d "key=YOUR_API_KEY&method=turnstile&sitekey=YOUR_SITEKEY&pageurl=https://example.com/contact&json=1" http://127.0.0.1:8080/in.php
# {"status":1,"request":"12345"}

# 2. Poll with that id until the token is ready.
curl.exe -s "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=12345&json=1"
# {"status":0,"request":"CAPCHA_NOT_READY"} means poll again shortly.
# {"status":1,"request":"TOKEN","userAgent":"Mozilla/5.0 ..."}

Task yang sama lewat SDK Python hanyalah satu panggilan. Ia mengirim task, melakukan polling, dan mengembalikan dictionary yang nilai code-nya adalah token untuk field cf-turnstile-response.

# python -m pip install capskip
from capskip import CapSkip

# Local mode. In Server mode, use your server's address as the host.
solver = CapSkip(host="127.0.0.1", port=8080)

result = solver.turnstile("YOUR_SITEKEY", "https://example.com/contact")

print(result["code"])  # the token for the cf-turnstile-response field
print(result.get("userAgent"))  # the User-Agent to send with it

Dokumentasi API menyatakan bahwa CapSkip memecahkan Turnstile dengan User-Agent browser tertentu dan Anda harus mengirim User-Agent yang sama saat mengirim token. Dengan balasan JSON, jawabannya membawa nilai itu sebagai userAgent, dan dalam mode teks biasa nilainya datang di header respons X-Turnstile-User-Agent. SDK meminta balasan JSON, jadi baca nilainya dari hasil dan pasang pada request yang membawa token.

Request halaman challenge

Untuk halaman challenge, Dokumentasi API meminta Anda mengirim tiga nilai tambahan, yang Anda baca dari argumen yang diberikan halaman ke turnstile.render(). Kirim yang didefinisikan halaman, dan jangan kirim yang kosong. Dokumentasi menyertakan skrip pendek yang menimpa fungsi itu dan mencetak argumennya.

Nilai requestTempat halaman menyimpannya
actionAtribut data-action, atau action di panggilan render
dataNilai cData di panggilan render, atau atribut data-cdata
pagedataNilai chlPageData di panggilan render
# python -m pip install capskip
from capskip import CapSkip

solver = CapSkip(host="127.0.0.1", port=8080)

# action, data and pagedata come from the page's turnstile.render call.
result = solver.turnstile(
    "YOUR_SITEKEY",
    "https://example.com/protected",
    action="managed",
    data="YOUR_CDATA",
    pagedata="YOUR_CHLPAGEDATA",
)
print(result["code"], result.get("userAgent"))

Nilai managed untuk action disalin dari contoh request di Dokumentasi API, jadi pakai action apa pun yang didefinisikan halaman Anda.

Rute cookie adalah request yang berbeda. Dokumentasi API mencantumkannya di bawah Cloudflare Challenge (cf_clearance), untuk halaman penuh yang bertuliskan "Just a moment". Rute ini hanya bekerja lewat API JSON createTask, nonaktif sampai Anda mengaktifkan Return cf_clearance cookies di pengaturan Cloudflare, dan setiap request harus menyebut proxy yang akan Anda pakai sesudahnya. SDK Python tidak punya panggilan untuk rute ini, jadi berikut request dalam bentuk yang ditulis Dokumentasi API, dikirim dengan PowerShell. Nilai proxy adalah placeholder dari dokumentasi.

# Submit the cookie task. A proxy is required.
$body = '{"clientKey":"YOUR_API_KEY","task":{"type":"AntiCloudflareTask","websiteURL":"https://www.example.com/","proxy":"203.0.113.10:8080:login:password"}}'
$task = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8080/createTask -ContentType "application/json" -Body $body

# Poll every few seconds while the status is processing.
$ask = @{ clientKey = "YOUR_API_KEY"; taskId = $task.taskId } | ConvertTo-Json
do {
    Start-Sleep -Seconds 5
    $result = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8080/getTaskResult -ContentType "application/json" -Body $ask
} while ($result.status -eq "processing")

$result.solution.cookies.cf_clearance
$result.solution.userAgent

Pakai request cookie ketika Anda ingin mengambil situs dengan request HTTP biasa setelah challenge. Dokumentasi API menjelaskan kasus itu untuk skrip atau alat yang tidak memiliki browser sendiri, dan menyatakan bahwa cookie harus dikirim lewat proxy yang sama dan dengan User-Agent yang sama. Request token cocok untuk halaman yang memanggil turnstile.render() dan memiliki callback atau field yang menerima token. Pasangan untuk request token itu adalah kesimpulan dari dua bagian dokumentasi, bukan pernyataan dari dokumentasi itu.

Untuk memakai ulang cookie di Python, lihat cara memakai ulang cookie cf_clearance. Untuk request token dalam kode, lihat panduan Node.js. Versi PHP ada di panduan memecahkan Turnstile di PHP, dan versi C# ada di panduan halaman challenge C#.

Yang saya jalankan, dan yang tidak ditunjukkannya

Saya menjalankan keempat blok kode terhadap sebuah mock yang berperan sebagai CapSkip, di Python 3.11.7, 3.13.7, dan 3.14.0 dengan capskip 1.7.0, dan kedua blok PowerShell di Windows PowerShell 5.1. Saya tidak mengirim task ke aplikasi asli, jadi tidak ada di sini yang menunjukkan bagaimana halaman Turnstile sungguhan merespons atau apa yang dikembalikan aplikasi asli untuk sebuah widget.

Pemeriksaan terhadap mockHasil
Panggilan widget PythonSatu task dengan metode turnstile, sitekey, dan alamat halaman, lalu token dan User-Agent kembali dalam hasilnya
Panggilan halaman challenge PythonTask yang sama juga membawa action, data, dan pagedata, persis seperti yang diteruskan
Kedua blok Python ditempel ke dalam satu fileKedua task terkirim dan terbaca kembali
Rute cookie di PowerShellMock melihat tipe AntiCloudflareTask, alamat halaman, dan proxy. Ia menjawab processing satu kali, lalu cookie dan User-Agent, yang dicetak oleh blok itu
curl.exe kirim, lalu pollingPolling pertama menyatakan task belum siap dan polling kedua mengembalikan token

FAQ

Berapa lama token Turnstile berlaku?

Cloudflare menyatakan 300 detik, dan token dimaksudkan untuk sekali pakai. Minta token dari CapSkip tepat sebelum formulir dikirim.

Apakah Turnstile sama dengan pemeriksaan Cloudflare sebelum sebuah situs dimuat?

Bukan. Widget berada di dalam halaman dan menghasilkan token. Challenge halaman penuh menggantikan halaman dan berakhir dengan cookie cf_clearance. Tabel keputusan di atas menunjukkan cara membedakannya.

Bisakah saya melihat widget Turnstile sebelum menulis kode apa pun?

Bisa. Buka halaman demo Turnstile untuk melihat widget langsung dan field yang diisinya.

Bisakah saya memanggil pemecah dari PC lain?

Bisa, lewat mode Server. Pakai alamat PC yang menjalankan CapSkip sebagai host dan tambahkan aturan blokir Windows Firewall untuk alamat mana pun yang tidak boleh menjangkaunya. Pemecah tetap berjalan di perangkat keras Windows Anda sendiri.

Versi singkatnya

Singkatnya, apa itu Cloudflare Turnstile? Sebuah token di cf-turnstile-response yang diperiksa situs bersama Cloudflare, di samping challenge halaman penuh tersendiri yang berakhir dengan cookie. Untuk menyediakan token atau cookie dari kode Anda sendiri, alat bypass captcha lokal seperti CapSkip melakukannya di PC Anda sendiri, dengan lisensi tetap dan tanpa biaya per pemecahan.