Receiver Anda mungkin melakukan deploy pada waktu berbeda. Masa tumpang tindih memungkinkan receiver yang menggunakan kunci rahasia lama dan receiver yang menggunakan kunci rahasia baru mengautentikasi pengiriman yang sama.
Terus verifikasi pengiriman sepanjang proses deployment agar permintaan dari penyerang tidak dapat memicu pemrosesan.
Apa yang terjadi saat saya merotasi?
Bird memberi Anda kunci rahasia penandatanganan baru. Deploy dalam 24 jam, selagi Bird masih menandatangani dengan kunci rahasia lama.
Panggil rotateWebhookSecret untuk endpoint Anda. Simpan secret-nya, string non-kosong yang diawali dengan whsec_, karena nilai ini hanya dikembalikan dalam respons tersebut.
Bird menandatangani setiap pengiriman dengan kedua kunci rahasia selama masa tumpang tindih. Header webhook-signature berisi signature yang dipisahkan spasi, masing-masing diawali dengan v1,.
Receiver dapat memverifikasi salah satu signature menggunakan kunci rahasia yang sesuai. Selesaikan deployment dalam 24 jam karena kunci rahasia lama berhenti menandatangani setelah jendela waktu tersebut.
Apa yang harus dilakukan handler saya?
Handler Anda harus menerima pengiriman jika ada signature yang cocok dengan kunci rahasia yang dipercayainya.
Receiver yang hanya memeriksa signature pertama dapat menolak pengiriman valid setelah berpindah kunci rahasia.
Spesifikasi Standard Webhooks mendefinisikan daftar signature agar receiver dapat mencoba masing-masing selama rotasi. Uji verifier Anda dengan beberapa signature sebelum merotasi endpoint live.
Pertahankan pemeriksaan timestamp dan duplikat selama proses perubahan. Verifikasi signature membahas pemeriksaan tersebut.
Apa urutan yang aman?
Simpan dan deploy kunci rahasia baru. Konfirmasi verifikasi sebelum masa tumpang tindih kunci rahasia lama berakhir.
- Rotasi kunci rahasia endpoint dan simpan nilai yang dikembalikan segera.
- Deploy nilai baru ke setiap instance receiver dalam masa tumpang tindih 24 jam.
- Konfirmasi bahwa receiver memverifikasi pengiriman menggunakan kunci rahasia baru, melalui log receiver dan percobaan pengiriman Bird.
- Biarkan kunci rahasia sebelumnya kedaluwarsa secara otomatis setelah masa tumpang tindih.
Tidak ada langkah penghapusan terpisah dalam operasi rotasi. Jika kunci rahasia lama terekspos, hentikan kepercayaan terhadapnya di receiver Anda setelah mereka memiliki kunci baru. Rotasi saja tetap membuat receiver yang mempercayai kunci rahasia lama rentan selama masa tumpang tindih.
Bagaimana jika saya langsung merotasi lagi?
Rotasi berikutnya dapat berhasil sampai endpoint mencapai lima kunci rahasia yang berlaku bersamaan.
Dimulai dengan satu kunci rahasia, empat rotasi dapat mengisi kelima slot sebelum kunci rahasia yang lebih lama kedaluwarsa. Rotasi berikutnya gagal dengan WebhookTooManySecrets. Perulangan rotasi dapat mencegah kunci rahasia baru diterbitkan saat Anda membutuhkannya.
Tunggu kunci rahasia yang lebih lama kedaluwarsa sebelum merotasi lagi. Rotasi berulang tidak menghilangkan kebutuhan untuk mendeploy kunci rahasia baru ke receiver Anda.
Apa yang terjadi pada pengiriman yang gagal selama perubahan?
Bird mencoba ulang pengiriman yang gagal, sehingga memperbaiki verifikasi dapat memulihkannya selama jendela coba lagi.
Jadwalnya mencakup sekitar 27,5 jam sebelum penyesuaian waktu. Pengiriman yang gagal juga dapat dipulihkan melalui replay setelah percobaan ulang selesai; percobaan ulang webhook yang gagal menjelaskan jendela replay.
Kembalikan error untuk permintaan yang tidak dapat Anda verifikasi. Mengembalikan 2xx menandai pengiriman berhasil, yang mengecualikannya dari replay event yang terlewat.
Singkatnya
Deploy selama masa tumpang tindih.
Bird menandatangani dengan kunci rahasia lama dan baru selama 24 jam, memberi waktu bagi receiver untuk mengadopsi nilai baru.
Terima signature mana pun yang cocok.
Receiver yang hanya memeriksa signature pertama dapat menolak pengiriman valid selama rotasi.
Simpan kunci rahasia baru segera.
Respons rotasi adalah satu-satunya tempat kunci rahasia baru dikembalikan.
Rotasi memiliki batas lima kunci rahasia.
Dimulai dengan satu kunci rahasia valid, empat rotasi mengisi slot yang tersedia sampai kunci rahasia yang lebih lama kedaluwarsa.