Twoje odbiorniki mogą być wdrażane w różnym czasie. Nakładanie się sekretów pozwala odbiornikowi używającemu starego sekretu i odbiornikowi używającemu nowego sekretu uwierzytelnić to samo dostarczenie.
Weryfikuj dostarczenia przez cały czas wdrożenia, aby żądanie od atakującego nie mogło wywołać przetwarzania.
Co się dzieje, gdy rotuję?
Bird daje ci nowy sekret podpisywania. Wdróż go w ciągu 24 godzin, gdy Bird nadal podpisuje starym sekretem.
Wywołaj rotateWebhookSecret dla swojego endpointu. Zapisz jego secret, niepusty ciąg znaków zaczynający się od whsec_, ponieważ jest zwracany tylko w tej odpowiedzi.
Bird podpisuje każde dostarczenie oboma sekretami w czasie nakładania. Nagłówek webhook-signature zawiera podpisy oddzielone spacjami, każdy zaczynający się od v1,.
Odbiornik może zweryfikować dowolny podpis, używając odpowiedniego sekretu. Zakończ wdrożenie w ciągu 24 godzin, ponieważ po tym oknie stary sekret przestaje podpisywać.
Co musi robić mój handler?
Twój handler musi zaakceptować dostarczenie, gdy dowolny dostarczony podpis pasuje do sekretu, któremu ufa.
Odbiornik sprawdzający tylko pierwszy podpis może odrzucać prawidłowe dostarczenia po przełączeniu sekretów.
Specyfikacja Standard Webhooks definiuje listę podpisów, aby odbiorniki mogły sprawdzać każdy z nich podczas rotacji. Przetestuj swój weryfikator z wieloma podpisami, zanim zrotujesz produkcyjny endpoint.
Utrzymuj kontrolę znacznika czasu i wykrywanie duplikatów przez cały czas trwania zmiany. Weryfikacja podpisu opisuje te kontrole.
Jaka jest bezpieczna kolejność?
Zapisz i wdróż nowy sekret. Potwierdź weryfikację, zanim skończy się okno nakładania starego sekretu.
- Zrotuj sekret endpointu i natychmiast zapisz zwróconą wartość.
- Wdróż nową wartość na wszystkie instancje odbiorników w ciągu 24-godzinnego okna nakładania.
- Potwierdź, że odbiorniki weryfikują dostarczenia przy użyciu nowego sekretu, korzystając z logów odbiorników i prób dostarczenia Bird.
- Pozwól poprzedniemu sekretowi wygasnąć automatycznie po zakończeniu okna nakładania.
W operacji rotacji nie ma osobnego kroku usuwania. Jeśli stary sekret został ujawniony, przestań mu ufać w swoich odbiornikach po wdrożeniu nowego. Sama rotacja pozostawia odbiorniki ufające staremu sekretowi narażone w czasie nakładania.
Co jeśli od razu zrotuję ponownie?
Kolejna rotacja może się powieść, dopóki endpoint nie osiągnie pięciu jednocześnie ważnych sekretów.
Zaczynając od jednego sekretu, cztery rotacje mogą zapełnić te pięć slotów, zanim starsze sekrety wygasną. Następna rotacja kończy się błędem WebhookTooManySecrets. Pętla rotacji może więc uniemożliwić wydanie kolejnego sekretu, gdy go potrzebujesz.
Poczekaj, aż starszy sekret wygaśnie, zanim zrotujesz ponownie. Powtarzana rotacja nie eliminuje konieczności wdrożenia nowego sekretu na odbiornikach.
Co się dzieje z dostarczeniami, które nie powiodły się podczas zmiany?
Bird ponawia nieudane dostarczenia, więc naprawienie weryfikacji pozwala je odzyskać w oknie ponawiania.
Harmonogram obejmuje około 27,5 godziny przed korektami czasowymi. Nieudane dostarczenie można też odzyskać przez ponowne odtworzenie po zakończeniu ponawiania; nieudane ponawiania webhooków opisuje okno ponownego odtwarzania.
Zwróć błąd dla żądania, którego nie możesz zweryfikować. Zwrócenie 2xx oznacza dostarczenie jako udane, co wyklucza je z ponownego odtwarzania pominiętych zdarzeń.
W skrócie
Wdrażaj w czasie nakładania się sekretów.
Bird podpisuje starym i nowym sekretem przez 24 godziny, dając odbiornikom czas na przyjęcie nowej wartości.
Akceptuj każdy pasujący podpis.
Odbiornik sprawdzający tylko pierwszy podpis może odrzucić prawidłowe dostarczenie podczas rotacji.
Zapisz nowy sekret natychmiast.
Odpowiedź na żądanie rotacji to jedyne miejsce, w którym nowy sekret jest zwracany.
Rotacja ma limit pięciu sekretów.
Zaczynając od jednego ważnego sekretu, cztery rotacje zapełniają dostępne sloty, zanim starszy sekret wygaśnie.