סוד חתימה של webhook הוא פרט התחברות לכל דבר, לא עוד פרט בהגדרות. שלחו אותו כמו ששולחים סיסמה: ודאו מי מקבל אותו, מסרו אותו בערוץ שלא שומר עותקים, ובדקו שהוא נשמר בסוף במאגר סודות ולא בכרטיס תמיכה. בקצרה: קישור סודי חד-פעמי לאיש קשר מאומת, והוראות ההגדרה בהודעה נפרדת.
המשך המדריך עוסק בבחירת הערוץ, בבדיקות לפני השליחה ובמה שהלקוח צריך לעשות עם הערך. הוא מסביר גם איך מטפלים בהחלפת הסוד ובתקלות בלי להדביק אותו שוב אף פעם.
באיזה ערוץ לשלוח את הסוד?
בחרו ערוץ לפי שני מבחנים: האם אפשר לוודא מי יכול לפתוח אותו, וכמה עותקים הוא משאיר אחריו? אימייל וצ'אט נכשלים במבחן השני, כי כל הודעה נשמרת, מסונכרנת ומיוצאת הרבה אחרי שהמסירה הסתיימה.
| שיטה | מה היא נותנת | מה בודקים לפני השליחה |
|---|---|---|
| פורטל לקוחות עם התחברות | גישה לפי משתמש בשמו, שאפשר לבטל אותה | שהחשבון שייך לאיש הקשר הנכון |
| קישור סודי חד-פעמי | מושמד אחרי פתיחה אחת, ושום דבר לא נשאר בהודעה | הכתובת שאליה שולחים, בבדיקה נפרדת |
| הודעות מוצפנות | הגנה בזמן ההעברה | מי עוד יכול לפתוח את השיחה |
פורטל לקוחות עם התחברות אישית לכל משתמש הוא בחירה ראשונה טובה כשיש כזה. תנו גישה לאדם מסוים בשמו, לא לשרשור משותף של הפרויקט, והסירו אותה כשהמסירה הסתיימה.
קישור חד-פעמי משאיר את פרטי ההתחברות מחוץ להודעת האימייל או הצ'אט שבה אתם מתאמים. ב-LinkPilot הסוד מוצפן בדפדפן שלכם לפני שהוא נשמר, העותק השמור מושמד אחרי פתיחה אחת, ואפשר לקבוע שתוקף הקישור יפוג אחרי שעה, יום או שבוע. בתוכניות Pro אפשר להוסיף ביטוי סיסמה, שמעבירים בערוץ נפרד. הבקרות האלה מגבילות את המסירה. הן לא פוטרות אתכם מלבדוק שהאדם הנכון נמצא בצד השני.
הודעות מוצפנות הן האפשרות האחרונה, כששתי הקודמות לא מעשיות. הצפנה בזמן ההעברה לא מתקנת הודעה שנשלחה לכתובת שגויה או לקבוצה גדולה מדי, ולכן הבדיקה של הנמען חשובה כאן עוד יותר.
בכל מקרה, השתמשו באימייל ובצ'אט בטקסט גלוי לתיאום בלבד. גם בשירותים שמצפינים בזמן ההעברה, מדיניות השמירה, הגיבויים והגישה לחשבונות אינם בשליטתכם.
אימות הלקוח והנמען
ערוץ מאובטח לא עוזר בכלום אם הסוד מגיע לתיבת הדואר הלא נכונה. לפני השליחה ודאו שמי שמבקש אחראי על האינטגרציה, ושהערוץ שבו אתם מתכננים להשתמש באמת שייך לו.
- אמתו זהות מול רשומה מוכרת. היעזרו ברשומת איש קשר מהימנה, בקשר עסקי קיים או בתהליך הקבוע של הלקוח. מבקש חדש, החלפה פתאומית של איש הקשר או דחיפות חריגה מצדיקים בדיקה עצמאית.
- קראו את הכתובת תו אחר תו, במיוחד כשאתם מעתיקים אותה מכרטיס או מהודעה אחרונה. שמות דומים ותיבות דואר משותפות הם המקום שבו קורות טעויות.
- בדקו למי עוד יש גישה. לפני שיתוף דרך פורטל או סביבת עבודה, עברו על רשימת החברים והסירו את מי שלא צריך את פרטי ההתחברות.
- אשרו את המסירה בערוץ שני. אם הקישור נשלח באימייל, התקשרו למספר טלפון מוכר או שאלו בערוץ הפרויקט הרגיל אם הגישה עבדה. אל תכללו את הסוד בהודעה הזו.
שתפו את הסוד רק עם האדם שיגדיר את נקודת הקצה, ותנו לו להכניס אותו למאגר הסודות של הלקוח. אם כמה מהנדסים צריכים אותו, את מי שרואה אותו מנהלים בבקרות הגישה של המאגר הזה, ולא בעותקים נפרדים לכל אחד מהם.
הכנת הסוד לפני המסירה
החליטו למה שייכים פרטי ההתחברות, איפה הלקוח צריך לשמור אותם וכמה זמן המסירה תישאר פתוחה. ההכנה הזו חוסכת הרבה בלבול כשתצטרכו להחליף את הסוד או לפתור תקלות.
- סוד אחד לכל לקוח או נקודת קצה. כשמשתמשים באותו ערך שוב, חשיפה אחת מגיעה לכל אינטגרציה שחולקת אותו, והחלפה אצל לקוח אחד משבשת את כולן. נהלו רישום פנימי של נקודת הקצה שכל סוד שייך אליה, בלי לשכפל את הערך בהערות הפרויקט.
- שמרו את העותק שלכם במנהל סודות. לא בקובץ טקסט מקומי, בכרטיס או במסמך משותף. אותה משמעת חלה על שיתוף מפתחות API: הגבילו מי יכול להגיע לפרטי ההתחברות, ושמרו על מסירה קצרה.
- קבעו חלון לאיסוף. תנו ללקוח מספיק זמן לאסוף את הערך ולסיים את ההגדרה, ולא יותר. קישור שנמחק אחרי פתיחה אחת ותוקפו פג אחרי יום מתאים לרוב המסירות. אם החלון עבר, צרו קישור חדש ואל תפתחו מחדש את הישן.
- שלחו את הוראות ההגדרה בנפרד. כתובת ה-URL של נקודת הקצה, כותרת החתימה ושלבי האימות שייכים לתיעוד של הלקוח או לערוץ הפרויקט. כשהם נפרדים מהסוד, מי שמעתיק את עמוד ההוראות לא מעתיק איתו גם את פרטי ההתחברות.
עזרה ללקוח לשמור את הסוד ולהשתמש בו בבטחה
המסירה לא מסתיימת כשהלקוח יכול לקרוא את הערך. היא מסתיימת כשהשרת קורא אותו בצורה מאובטחת ומשתמש בו כדי לאמת חתימות נכנסות.
- שמרו אותו במנהל סודות או במשתנה סביבה מוגן שתהליך השרת יכול לקרוא, עם גישה שמוגבלת לאפליקציה ולאנשים שמפעילים אותה.
- הרחיקו אותו מקוד המקור, מהלוגים ומה-payload של ה-webhook. הסוד משמש לחישוב חתימה או לאימות שלה. הוא אף פעם לא עובר בגוף הבקשה, והוא לא אמור להופיע בפלט דיבאג, במאגרי קוד או בכרטיסי תמיכה. בדקו מה כלי הפריסה שלכם רושמים לפני שאתם מפעילים אבחון מפורט.
- אמתו חתימות בשרת. המקבל מחשב מחדש את החתימה על גוף הבקשה הגולמי עם הסוד המשותף ומשווה אותה לכותרת שהשולח קבע. החתימה מוכיחה שהבקשה אמיתית ולא שונתה; היא לא מצפינה את ה-payload. המדריך של HackerOne לחתימה על webhooks מסביר למה חשובים גם הגוף הגולמי וגם הסוד הנכון.
- הריצו אירוע בדיקה. בקשו מהלקוח לוודא שחתימה תקינה מתקבלת ושחתימה שקולקלה בכוונה נדחית. כך תופסים את הטעויות הנפוצות: הסוד של נקודת קצה אחרת, או גוף בקשה שעבר ניתוח (parsing) לפני האימות. אם האינטגרציה תומכת בזה, הפרידו בין פרטי ההתחברות של סביבת הבדיקה לאלה של סביבת הייצור.
צמצום הסיכון אחרי המסירה
המסירה צריכה להשאיר רישום שאפשר לעבוד איתו, לא שובל של עותקים מיותרים.
- תעדו מי קיבל הרשאה ומתי. רשמו את הנמען, את נקודת הקצה או הלקוח ואת זמן המסירה. אף פעם לא את הערך. אם אי אפשר לדעת אם קישור נפתח או מי יכול היה להגיע לתיקייה משותפת, זו סיבה להדק את התהליך בפעם הבאה.
- החליפו את הסוד בכל חשד לחשיפה. סוד שהודבק בכרטיס, נשלח לכתובת שגויה או נמצא בלוג כבר לא פרטי. צרו סוד חלופי, עדכנו את נקודת הקצה ובטלו את תוקף הערך הישן. הסרת קישור השיתוף לא מבטלת את החשיפה; רק החלפת הסוד עושה את זה.
- סכמו על תהליך ההחלפה כבר עכשיו. החליטו מי מבקש, יוצר ומתקין סוד חלופי, אם המימוש תומך בחפיפה קצרה בין הערכים, ואיך תבדקו את הערך החדש לפני שתוציאו את הישן משימוש. נוהל מוכר עדיף על התכתבות דחופה באמצע השבתה.
- נקו אחריכם. אחרי שהלקוח מאשר שקיבל את הסוד, בטלו את הגישה הזמנית ומחקו עותקים שנשארו בטיוטות, בכרטיסים ובהערות. בדקו את כללי השמירה של כל מערכת מעורבת; מחיקת הודעה מתצוגה אחת כמעט אף פעם לא מוחקת אותה מהגיבויים.
פתרון תקלות בלי לחשוף את הסוד
בעיה במסירה היא לא סיבה לשלוח שוב את פרטי ההתחברות בערוץ פחות מאובטח. קודם בררו איזה משלושה דברים לא עובד: הלקוח לא מצליח לאסוף את הסוד, לא מצליח להגדיר את נקודת הקצה, או מקבל בקשות ולא מצליח לאמת את החתימות.
- האיסוף נכשל או שהחלון עבר. ודאו שוב את זהות הנמען וצרו מסירה מבוקרת חדשה. אל תדביקו את הערך בכרטיס, ואל תבקשו מהלקוח לשלוח לכם את הערך שלו להשוואה.
- החתימה לא תואמת. כמעט תמיד הבעיה בקלט של האימות: סוד לא נכון לנקודת הקצה הזו, גוף בקשה שעוצב מחדש לפני חישוב ה-hash, או כותרת שנקראה לא נכון. בקשו מהלקוח לבדוק עם אירוע ידוע דרך כלי הבדיקה של השולח.
- בקשות לא מגיעות בכלל. זו בעיה של מסירה או ניתוב, לא של פרטי ההתחברות. בדקו חותמות זמן, קודי תגובה ובחירת נקודת הקצה לפני שמישהו שוקל להחליף את הסוד. תיעוד ה-webhooks של Stripe הוא דוגמה טובה להפרדה בין רישום נקודות קצה ומסירת אירועים לבין אימות חתימות.
- שתפו נתוני אבחון מושחרים. מזהה האירוע, חותמת הזמן, נקודת הקצה וסוג השגיאה מספיקים. הסירו את הסוד, את החתימה המלאה כשהיא רגישה ושדות פרטיים ב-payload, ובדקו את ההשחרה לפני שאתם שולחים בקשה לדוגמה.
ודאו מי הנמען ומסרו לו את הסוד פעם אחת, בערוץ שלא שומר אותו. בדקו שהסוד הגיע למאגר סודות, ואם ייתכן שדלף, החליפו אותו בלי לחכות. על השימוש הרחב יותר בקישורים חד-פעמיים בתהליכי עבודה של פיתוח, ראו שיתוף קישורים מאובטח למפתחים.