Sådan sender du en webhook-signeringshemmelighed sikkert til en kunde

En signeringshemmelighed til en webhook er lige så fortrolig som en adgangskode og ikke en detalje i opsætningen. Send den, som du ville sende en adgangskode: Bekræft, hvem der modtager den, overdrag den via en kanal, der ikke gemmer kopier, og sørg for, at den ender i en secrets manager og ikke i en sag i supportsystemet. Kort fortalt: send et hemmeligt engangslink til en bekræftet kontaktperson, og send opsætningsvejledningen for sig.

Resten af guiden handler om valget af kanal, kontrollen før du sender, hvad kunden skal gøre med værdien, og hvordan du klarer rotation og fejlsøgning uden nogensinde at indsætte hemmeligheden igen.

Hvilken kanal skal du sende hemmeligheden via?

Vælg kanal ud fra to spørgsmål: Kan du bekræfte, hvem der kan åbne den, og hvor mange kopier efterlader den? E-mail og chat dumper på det andet spørgsmål, fordi hver besked gemmes, synkroniseres og eksporteres længe efter, at overdragelsen er overstået.

En kundeportal med personlige logins er et godt førstevalg, når den findes. Giv adgang til en navngiven person, ikke til en fælles projekttråd, og fjern adgangen, når overdragelsen er færdig.

Et engangslink holder hemmeligheden ude af den e-mail eller chatbesked, du bruger til at koordinere. Med LinkPilot krypteres hemmeligheden i din browser, før den gemmes, den gemte kopi destrueres efter én åbning, og du kan sætte linket til at udløbe efter en time, en dag eller en uge. Pro-planerne tilføjer en adgangssætning, som du giver videre via en separat kanal. Disse funktioner begrænser overdragelsen. De erstatter ikke kontrollen af, at det er den rette person i den anden ende.

En krypteret beskedtjeneste er reserveløsningen, når ingen af de to første er praktiske. Kryptering under overførslen hjælper ikke, hvis beskeden er sendt til den forkerte, eller hvis gruppen er for stor, så kontrollen af modtageren betyder endnu mere her.

Uanset hvad du vælger, så brug kun e-mail og chat i klartekst til koordinering. Selv tjenester, der krypterer under overførslen, lader opbevaring, sikkerhedskopier og kontoadgang ligge uden for din kontrol.

Bekræft kunden og modtageren

En sikker kanal gør ingen nytte, hvis hemmeligheden havner i den forkerte indbakke. Bekræft, før du sender, at den person, der beder om den, er ansvarlig for integrationen, og at den vej, du vil bruge, faktisk er personens egen.

• Bekræft identiteten ud fra en kendt kilde. Brug en kontakt, du stoler på, et eksisterende forretningsforhold eller kundens faste procedure. En ny afsender, en pludselig ny kontaktperson eller usædvanligt hastværk kræver en uafhængig kontrol.
• Læs adressen tegn for tegn, især når du kopierer den fra en sag eller en nylig besked. Det er ved navne, der ligner hinanden, og ved fælles indbakker, at fejlene sker.
• Gennemgå, hvem der ellers har adgang. Før du deler via en portal eller et arbejdsområde, så se medlemslisten igennem, og fjern alle, der ikke har brug for hemmeligheden.
• Bekræft modtagelsen via en anden kanal. Blev linket sendt via e-mail, så spørg på et kendt telefonnummer eller i den sædvanlige projektkanal, om adgangen virkede. Skriv ikke hemmeligheden i den besked.

Del hemmeligheden med den ene person, der skal konfigurere endpointet, og lad vedkommende lægge den i kundens egen secrets manager. Har flere udviklere brug for den, er adgangsstyringen i det system det rette sted at bestemme, hvem der ser den, ikke separate kopier til hver af dem.

Forbered hemmeligheden før overdragelsen

Afgør, hvad hemmeligheden hører til, hvor kunden skal opbevare den, og hvor længe overdragelsen skal stå åben. Den forberedelse gør senere rotation og fejlsøgning langt mindre forvirrende.

• Én hemmelighed pr. kunde eller endpoint. Genbrug betyder, at én lækage rammer alle integrationer, der deler værdien, og at rotation for én kunde forstyrrer dem alle. Før en intern oversigt over, hvilket endpoint hver hemmelighed hører til, uden at gentage værdien i projektnoterne.
• Opbevar din egen kopi i en secrets manager. Ikke i en lokal tekstfil, en sag eller et delt dokument. Den samme disciplin gælder for deling af API-nøgler: Begræns, hvem der kan nå hemmeligheden, og hold overdragelsen kortvarig.
• Fastsæt et tidsrum til afhentning. Giv kunden tid nok til at hente værdien og gøre opsætningen færdig, og ikke mere. Et link, der slettes efter én åbning og udløber efter en dag, dækker de fleste overdragelser. Er tidsrummet gået, så opret et nyt link i stedet for at genåbne det gamle.
• Send opsætningsvejledningen for sig. Endpointets URL, signaturheaderen og trinnene til verificering hører hjemme i kundens dokumentation eller i projektkanalen. Holder du dem adskilt fra hemmeligheden, er en kopieret vejledning ikke samtidig en kopieret hemmelighed.

Hjælp kunden med at opbevare og bruge den sikkert

Leveringen er ikke færdig, når kunden kan læse værdien. Den er færdig, når serveren kan læse den sikkert og bruger den til at verificere signaturerne på indgående anmodninger.

• Opbevar den i en secrets manager eller en beskyttet miljøvariabel, som serverprocessen kan læse, med adgang begrænset til applikationen og de personer, der driver den.
• Hold den ude af kildekode, logs og webhook-payloads. Hemmeligheden bruges til at beregne eller verificere en signatur. Den sendes aldrig med i anmodningens body, og den må ikke dukke op i debug-output, repositories eller supportsager. Tjek, hvad dine deployment-værktøjer opsamler, før du slår udførlig diagnosticering til.
• Verificer signaturer på serveren. Modtageren beregner signaturen igen over den rå body med den delte hemmelighed og sammenligner den med den header, afsenderen har sat. Signeringen beviser, at anmodningen er ægte og uændret. Den krypterer ikke payloaden. HackerOnes guide til signering af webhooks forklarer, hvorfor både den rå body og den korrekte hemmelighed betyder noget.
• Kør en testhændelse. Lad kunden bekræfte, at en gyldig signatur accepteres, og at en bevidst ødelagt signatur afvises. Det fanger de typiske fejl: et andet endpoints hemmelighed eller en body, der blev parset før verificeringen. Hold hemmeligheder til test og produktion adskilt, hvor integrationen understøtter det.

Begræns risikoen efter leveringen

Overdragelsen skal efterlade en brugbar registrering, ikke et spor af ekstra kopier.

• Registrer, hvem der fik adgang, og hvornår. Log modtageren, endpointet eller kunden og tidspunktet for overdragelsen. Aldrig værdien. Kan du ikke se, om et link blev åbnet, eller hvem der kunne nå en delt mappe, så er det en grund til at stramme processen næste gang.
• Roter ved enhver mistanke om lækage. En hemmelighed, der er indsat i en sag, sendt til den forkerte adresse eller fundet i en log, er ikke længere privat. Generer en ny, opdater endpointet, og ugyldiggør den gamle værdi. At fjerne et delingslink gør ikke en lækage ugjort. Det gør kun rotation.
• Aftal rotationsproceduren nu. Afgør, hvem der anmoder om, opretter og installerer en ny hemmelighed, om implementeringen tillader et kort overlap, og hvordan den nye værdi testes, før den gamle udfases. En kendt procedure er bedre end en hastig udveksling under et nedbrud.
• Ryd op. Når kunden har bekræftet afhentningen, så tilbagekald den midlertidige adgang, og slet løse kopier i kladder, sager og noter. Tjek opbevaringsreglerne i hvert system, der var involveret. At slette en besked i én visning fjerner den sjældent fra sikkerhedskopierne.

Fejlsøg uden at afsløre hemmeligheden

Et problem med leveringen er ingen grund til at sende hemmeligheden igen via en svagere kanal. Find først ud af, hvilken af tre ting der er galt: Kunden kan ikke hente hemmeligheden, kan ikke konfigurere endpointet eller modtager anmodninger, men kan ikke validere signaturerne.

• Afhentningen mislykkedes, eller tidsrummet udløb. Bekræft modtageren igen, og lav en ny kontrolleret overdragelse. Indsæt ikke værdien i en sag, og bed ikke kunden om at sende sin egen tilbage til sammenligning.
• Signaturen passer ikke. Næsten altid et problem med input til verificeringen: den forkerte hemmelighed til endpointet, en body, der blev omformateret før hashingen, eller en header, der blev læst forkert. Lad kunden teste med en kendt hændelse via afsenderens testværktøjer.
• Anmodningerne kommer aldrig frem. Det er et problem med levering eller routing, ikke med hemmeligheden. Tjek tidsstempler, svarkoder og valget af endpoint, før nogen overvejer at rotere. Stripes webhook-dokumentation er en nyttig model for, hvordan man holder registrering af endpoints og levering af hændelser adskilt fra verificering af signaturer.
• Del diagnosticeringsdata uden følsomme felter. Hændelses-id, tidsstempel, endpoint og fejltype er nok. Fjern hemmeligheden, den fulde signatur, hvor den er følsom, og private felter i payloaden, og tjek, at alt følsomt er fjernet, før du sender en eksempelanmodning.

Bekræft modtageren, overdrag hemmeligheden én gang via en kanal, der glemmer den, sørg for, at den lander i en secrets manager, og roter uden tøven, hvis den kan være lækket. Det bredere mønster med engangslinks i udviklernes arbejdsgange finder du i sikker linkdeling for udviklere.