Πώς στέλνετε με ασφάλεια το μυστικό υπογραφής webhook σε πελάτη

Το μυστικό υπογραφής ενός webhook (webhook signing secret) είναι διαπιστευτήριο, όχι λεπτομέρεια της ρύθμισης. Στείλτε το όπως θα στέλνατε έναν κωδικό πρόσβασης: επιβεβαιώστε ποιος το παραλαμβάνει, παραδώστε το από ένα κανάλι που δεν κρατά αντίγραφα και φροντίστε να καταλήξει σε χώρο αποθήκευσης μυστικών και όχι σε ένα ticket. Με λίγα λόγια: ένας μυστικός σύνδεσμος μίας χρήσης προς μια επαληθευμένη επαφή, με τις οδηγίες ρύθμισης σε ξεχωριστό μήνυμα.

Ο υπόλοιπος οδηγός εξηγεί πώς διαλέγετε κανάλι, τι ελέγχετε πριν από την αποστολή, τι πρέπει να κάνει ο πελάτης με την τιμή και πώς χειρίζεστε την εναλλαγή κλειδιών και την αντιμετώπιση προβλημάτων χωρίς να επικολλήσετε ποτέ ξανά το μυστικό.

Ποιο κανάλι πρέπει να μεταφέρει το μυστικό;

Το κανάλι κρίνεται με δύο ερωτήματα: μπορείτε να επιβεβαιώσετε ποιος έχει τη δυνατότητα να το ανοίξει, και πόσα αντίγραφα αφήνει πίσω του; Το email και το chat αποτυγχάνουν στο δεύτερο, γιατί κάθε μήνυμα διατηρείται, συγχρονίζεται και εξάγεται πολύ μετά το τέλος της παράδοσης.

Μια πύλη πελατών με ατομικούς λογαριασμούς είναι καλή πρώτη επιλογή, όταν υπάρχει. Δώστε πρόσβαση σε ένα συγκεκριμένο άτομο, όχι σε ένα κοινό νήμα του έργου, και αφαιρέστε την μόλις ολοκληρωθεί η παράδοση.

Ένας σύνδεσμος μίας χρήσης κρατά το διαπιστευτήριο έξω από το email ή το μήνυμα chat με το οποίο συντονίζεστε. Στο LinkPilot το μυστικό κρυπτογραφείται στο πρόγραμμα περιήγησής σας πριν αποθηκευτεί, το αποθηκευμένο αντίγραφο καταστρέφεται μετά από ένα άνοιγμα και μπορείτε να ορίσετε λήξη του συνδέσμου μετά από μια ώρα, μια ημέρα ή μια εβδομάδα. Τα πακέτα Pro προσθέτουν φράση πρόσβασης, την οποία δίνετε από ξεχωριστό κανάλι. Αυτές οι ρυθμίσεις περιορίζουν την παράδοση. Δεν αντικαθιστούν τον έλεγχο ότι στην άλλη άκρη βρίσκεται το σωστό άτομο.

Η κρυπτογραφημένη ανταλλαγή μηνυμάτων είναι η εφεδρική λύση, όταν καμία από τις παραπάνω δεν είναι πρακτική. Η κρυπτογράφηση κατά τη μεταφορά δεν διορθώνει ένα μήνυμα που στάλθηκε σε λάθος διεύθυνση ή μια ομάδα συνομιλίας με πάρα πολλά μέλη, οπότε ο έλεγχος του παραλήπτη μετράει ακόμη περισσότερο.

Ό,τι κι αν διαλέξετε, το μη κρυπτογραφημένο email και το chat να χρησιμοποιούνται μόνο για συντονισμό. Ακόμη και οι υπηρεσίες που κρυπτογραφούν κατά τη μεταφορά δεν σας αφήνουν να ελέγχετε τη διατήρηση, τα αντίγραφα ασφαλείας και την πρόσβαση στους λογαριασμούς.

Επαληθεύστε τον πελάτη και τον παραλήπτη

Ένα ασφαλές κανάλι δεν προσφέρει τίποτα αν το μυστικό καταλήξει σε λάθος γραμματοκιβώτιο. Πριν το στείλετε, επιβεβαιώστε ότι αυτός που το ζητά είναι υπεύθυνος για την ενοποίηση και ότι η διαδρομή που σκοπεύετε να χρησιμοποιήσετε είναι πράγματι δική του.

• Επιβεβαιώστε την ταυτότητα από ένα γνωστό αρχείο. Χρησιμοποιήστε μια αξιόπιστη καταχώριση επαφής, μια υπάρχουσα επαγγελματική σχέση ή την καθιερωμένη διαδικασία του πελάτη. Ένα αίτημα από νέο πρόσωπο, μια ξαφνική αλλαγή επαφής ή μια ασυνήθιστη βιασύνη χρειάζονται ανεξάρτητο έλεγχο.
• Διαβάστε τη διεύθυνση χαρακτήρα προς χαρακτήρα, ειδικά όταν την αντιγράφετε από ένα ticket ή από πρόσφατο μήνυμα. Τα λάθη γίνονται στα παρόμοια ονόματα και στα κοινόχρηστα γραμματοκιβώτια.
• Ελέγξτε ποιος άλλος έχει πρόσβαση. Πριν από την κοινή χρήση μέσω πύλης ή χώρου εργασίας, δείτε τη λίστα μελών του και αφαιρέστε όποιον δεν χρειάζεται το διαπιστευτήριο.
• Επιβεβαιώστε την παράδοση από δεύτερο κανάλι. Αν ο σύνδεσμος στάλθηκε με email, ρωτήστε σε έναν γνωστό αριθμό τηλεφώνου ή στο συνηθισμένο κανάλι του έργου αν η πρόσβαση λειτούργησε. Μη βάλετε το μυστικό σε αυτό το μήνυμα.

Δώστε το μυστικό μόνο στο άτομο που θα ρυθμίσει το endpoint, ώστε να το βάλει το ίδιο στον χώρο αποθήκευσης μυστικών του πελάτη. Αν το χρειάζονται αρκετοί μηχανικοί, οι έλεγχοι πρόσβασης αυτού του χώρου είναι το σωστό σημείο για να ορίσετε ποιος το βλέπει, όχι ξεχωριστά αντίγραφα για τον καθένα.

Προετοιμάστε το μυστικό πριν από την παράδοση

Αποφασίστε σε τι ανήκει το διαπιστευτήριο, πού πρέπει να το κρατήσει ο πελάτης και πόσο καιρό θα μείνει ανοιχτή η παράδοση. Με αυτή την προετοιμασία, η εναλλαγή κλειδιών και η αντιμετώπιση προβλημάτων αργότερα είναι πολύ πιο ξεκάθαρες.

• Ένα μυστικό ανά πελάτη ή endpoint. Αν η ίδια τιμή χρησιμοποιείται σε πολλά σημεία, μία διαρροή εκθέτει κάθε ενοποίηση που τη μοιράζεται, και η αλλαγή του κλειδιού για έναν πελάτη επηρεάζει όλους. Κρατήστε ένα εσωτερικό αρχείο για το σε ποιο endpoint ανήκει κάθε μυστικό, χωρίς να αντιγράφετε την τιμή σε σημειώσεις του έργου.
• Αποθηκεύστε το δικό σας αντίγραφο σε διαχειριστή μυστικών. Όχι σε τοπικό αρχείο κειμένου, σε ticket ή σε κοινόχρηστο έγγραφο. Η ίδια πειθαρχία ισχύει και για την κοινή χρήση κλειδιών API: περιορίστε ποιος έχει πρόσβαση στο διαπιστευτήριο και κρατήστε την παράδοση σύντομη.
• Ορίστε ένα χρονικό περιθώριο παραλαβής. Δώστε στον πελάτη αρκετό χρόνο για να πάρει την τιμή και να ολοκληρώσει τη ρύθμιση, και όχι περισσότερο. Ένας σύνδεσμος που διαγράφεται οριστικά μετά από ένα άνοιγμα και λήγει σε μια ημέρα καλύπτει τις περισσότερες παραδόσεις. Αν περάσει το περιθώριο, δημιουργήστε νέο σύνδεσμο αντί να ανοίξετε ξανά τον παλιό.
• Στείλτε τις οδηγίες ρύθμισης χωριστά. Το URL του endpoint, η κεφαλίδα της υπογραφής και τα βήματα επαλήθευσης ανήκουν στην τεκμηρίωση του πελάτη ή στο κανάλι του έργου. Όταν μένουν χωριστά από το μυστικό, μια σελίδα οδηγιών που αντιγράφηκε δεν είναι ταυτόχρονα και διαπιστευτήριο που αντιγράφηκε.

Βοηθήστε τον πελάτη να το αποθηκεύσει και να το χρησιμοποιήσει με ασφάλεια

Η παράδοση δεν τελειώνει όταν ο πελάτης μπορεί να διαβάσει την τιμή. Τελειώνει όταν ο διακομιστής μπορεί να τη διαβάσει με ασφάλεια και τη χρησιμοποιεί για να επαληθεύει τις εισερχόμενες υπογραφές.

• Αποθηκεύστε το σε διαχειριστή μυστικών ή σε προστατευμένη μεταβλητή περιβάλλοντος που μπορεί να διαβάσει η διεργασία του διακομιστή, με πρόσβαση μόνο για την εφαρμογή και τους ανθρώπους που τη λειτουργούν.
• Κρατήστε το έξω από τον πηγαίο κώδικα, τα αρχεία καταγραφής και τα payload των webhook. Το μυστικό χρησιμοποιείται για τον υπολογισμό ή την επαλήθευση μιας υπογραφής. Δεν ταξιδεύει ποτέ στο σώμα του αιτήματος και δεν πρέπει να εμφανίζεται σε έξοδο αποσφαλμάτωσης, σε αποθετήρια ή σε ticket υποστήριξης. Ελέγξτε τι καταγράφουν τα εργαλεία ανάπτυξης πριν ενεργοποιήσετε αναλυτικά διαγνωστικά.
• Επαληθεύετε τις υπογραφές στον διακομιστή. Ο παραλήπτης υπολογίζει ξανά την υπογραφή πάνω στο ακατέργαστο σώμα του αιτήματος με το κοινό μυστικό και τη συγκρίνει με την κεφαλίδα που όρισε ο αποστολέας. Η υπογραφή αποδεικνύει ότι το αίτημα είναι γνήσιο και δεν έχει αλλοιωθεί. Δεν κρυπτογραφεί το payload. Ο οδηγός της HackerOne για την υπογραφή webhook εξηγεί γιατί μετράνε και το ακατέργαστο σώμα και το σωστό μυστικό.
• Στείλτε ένα δοκιμαστικό συμβάν. Ζητήστε από τον πελάτη να επιβεβαιώσει ότι μια έγκυρη υπογραφή γίνεται δεκτή και μια σκόπιμα αλλοιωμένη απορρίπτεται. Έτσι πιάνονται τα συνηθισμένα λάθη: το μυστικό άλλου endpoint ή ένα σώμα που αναλύθηκε πριν από την επαλήθευση. Κρατήστε χωριστά τα διαπιστευτήρια δοκιμών και παραγωγής, όπου το υποστηρίζει η ενοποίηση.

Μειώστε τον κίνδυνο μετά την παράδοση

Η παράδοση πρέπει να αφήνει ένα χρήσιμο αρχείο, όχι μια σειρά από επιπλέον αντίγραφα.

• Καταγράψτε ποιος εξουσιοδοτήθηκε και πότε. Σημειώστε τον παραλήπτη, το endpoint ή τον πελάτη και την ώρα της παράδοσης. Ποτέ την τιμή. Αν δεν μπορείτε να πείτε αν ένας σύνδεσμος ανοίχτηκε ή ποιος είχε πρόσβαση σε έναν κοινόχρηστο φάκελο, αυτός είναι λόγος να κάνετε τη διαδικασία αυστηρότερη την επόμενη φορά.
• Αντικαταστήστε το κλειδί με νέο σε κάθε υποψία έκθεσης. Ένα μυστικό που επικολλήθηκε σε ticket, στάλθηκε σε λάθος διεύθυνση ή βρέθηκε σε αρχείο καταγραφής δεν είναι πια ιδιωτικό. Δημιουργήστε αντικατάσταση, ενημερώστε το endpoint και ακυρώστε την παλιά τιμή. Η αφαίρεση ενός συνδέσμου κοινής χρήσης δεν αναιρεί την έκθεση. Αυτό το κάνει μόνο η αντικατάσταση του κλειδιού.
• Συμφωνήστε τώρα τη διαδικασία εναλλαγής. Αποφασίστε ποιος ζητά, δημιουργεί και εγκαθιστά την αντικατάσταση, αν η υλοποίηση υποστηρίζει μια σύντομη περίοδο επικάλυψης και πώς θα δοκιμάσετε τη νέα τιμή πριν αποσύρετε την παλιά. Μια γνωστή διαδικασία είναι καλύτερη από μια βιαστική ανταλλαγή στη μέση μιας διακοπής λειτουργίας.
• Καθαρίστε. Μόλις ο πελάτης επιβεβαιώσει την παραλαβή, ανακαλέστε την προσωρινή πρόσβαση και διαγράψτε τα αντίγραφα που ξέμειναν σε πρόχειρα, ticket και σημειώσεις. Ελέγξτε τους κανόνες διατήρησης κάθε συστήματος που εμπλέκεται. Η διαγραφή ενός μηνύματος από ένα σημείο σπάνια το αφαιρεί από τα αντίγραφα ασφαλείας.

Αντιμετώπιση προβλημάτων χωρίς έκθεση του μυστικού

Ένα πρόβλημα στην παράδοση δεν είναι λόγος να ξαναστείλετε το διαπιστευτήριο από ένα πιο αδύναμο κανάλι. Βρείτε πρώτα ποιο από τα τρία ισχύει: ο πελάτης δεν μπορεί να παραλάβει το μυστικό, δεν μπορεί να ρυθμίσει το endpoint ή λαμβάνει αιτήματα αλλά δεν μπορεί να επαληθεύσει τις υπογραφές.

• Η παραλαβή απέτυχε ή το περιθώριο έληξε. Επιβεβαιώστε ξανά τον παραλήπτη και κάντε μια νέα ελεγχόμενη παράδοση. Μην επικολλήσετε την τιμή σε ticket και μη ζητήσετε από τον πελάτη να σας στείλει πίσω τη δική του για σύγκριση.
• Η υπογραφή δεν ταιριάζει. Σχεδόν πάντα το πρόβλημα βρίσκεται στα δεδομένα της επαλήθευσης: το μυστικό άλλου endpoint, ένα σώμα που άλλαξε μορφή πριν από τον υπολογισμό του hash ή μια κεφαλίδα που διαβάστηκε λάθος. Ζητήστε από τον πελάτη να δοκιμάσει με ένα γνωστό συμβάν από τα εργαλεία δοκιμών του αποστολέα.
• Τα αιτήματα δεν φτάνουν ποτέ. Αυτό είναι πρόβλημα παράδοσης ή δρομολόγησης, όχι διαπιστευτηρίου. Ελέγξτε χρονοσφραγίδες, κωδικούς απόκρισης και την επιλογή endpoint πριν σκεφτεί κανείς την εναλλαγή κλειδιών. Η τεκμηρίωση της Stripe για τα webhook είναι ένα χρήσιμο πρότυπο για το πώς ξεχωρίζουν η καταχώριση του endpoint και η παράδοση των συμβάντων από την επαλήθευση της υπογραφής.
• Στείλτε διαγνωστικά με αφαιρεμένα τα ευαίσθητα στοιχεία. Το αναγνωριστικό του συμβάντος, η χρονοσφραγίδα, το endpoint και η κατηγορία του σφάλματος αρκούν. Αφαιρέστε το μυστικό, την πλήρη υπογραφή όπου είναι ευαίσθητη και τα ιδιωτικά πεδία του payload, και ελέγξτε την απόκρυψη πριν στείλετε ένα δείγμα αιτήματος.

Επαληθεύστε τον παραλήπτη, παραδώστε το μυστικό μία φορά από ένα κανάλι που δεν το κρατά, φροντίστε να καταλήξει σε χώρο αποθήκευσης μυστικών και αντικαταστήστε το χωρίς δισταγμό αν μπορεί να έχει διαρρεύσει. Για τη γενικότερη χρήση συνδέσμων μίας χρήσης στη δουλειά των μηχανικών, δείτε την ασφαλή κοινή χρήση συνδέσμων για developers.