Kaip sukonfigūruoti ir pakeisti siuntų sekimo API raktus nesutrikdant integracijos
Norėdami saugiai sukonfigūruoti ir keisti siuntų sekimo API raktus, laikykite prisijungimo duomenis serverio pusės paslapčių tvarkyklėje, nustatykite kiekvieną juos naudojančią programą ir išbandykite pakaitinį raktą prieš išjungdami senąjį. Jei jūsų teikėjas palaiko persidengiančius prisijungimo duomenis, palaipsniui perkelkite naudotojus ir atšaukite senąjį raktą tik po patikrinimo. Jei pakeitus raktą esamas raktas iš karto tampa negaliojantis, suplanuokite koordinuotą perjungimą su patvariomis eilėmis ir atkūrimo patikromis, o ne manykite, kad prastovos nebus.
Šis vadovas skirtas kūrėjams ir operacijų komandoms, prižiūrinčioms sekimo integracijas elektroninės prekybos platformose, užsakymų valdymo sistemose, sandėlių programinėje įrangoje ir klientų informavimo paslaugose. Tikslas nėra vien pateikti autentifikuotą užklausą: reikia išsaugoti siuntų registraciją, sekimo atnaujinimus ir tolesnį apdorojimą viso pakeitimo metu.
Sužinokite, kaip jūsų teikėjas tvarko prisijungimo duomenis
Prieš keisdami gamybinę konfigūraciją, nustatykite teikėjo prisijungimo duomenų gyvavimo ciklą. Valdymo skydelio veiksmas „regeneruoti“ gali veikti kitaip nei „sukurti kitą raktą“. Nedarykite išvadų vien pagal mygtuko pavadinimą.
- Autentifikavimo formatas: patvirtinkite reikalingą antraštę ar kitą autentifikavimo mechanizmą, galinio taško versiją ir paskyros susiejimą.
- Persidengimas: ar du prisijungimo duomenys gali galioti vienu metu? Ar sugeneravus pakaitinį raktą ankstesnis prisijungimo duomuo iš karto atšaukiamas?
- Leidimai: nustatykite, ar raktai turi atskiras aprėptis, aplinkos apribojimus ar prieigos valdiklius. Jei įmanoma, naudokite šiuos valdiklius; nemanykite, kad jie būtinai egzistuoja.
- Atšaukimas: patvirtinkite, kaip išjungti prisijungimo duomenį ir ar reikia atsižvelgti į kokį nors sklaidos elgesį.
- Veiklos poveikis: nustatykite, ar kvotos, registruotos siuntos ir webhook nustatymai priklauso paskyrai, programai ar atskiram raktui.
Jei naudojate 17TRACK integraciją, pradėkite nuo oficialios Tracking API dokumentacijos ir Tracking API produkto puslapio. Naudokite dokumentaciją integracijos autentifikavimo sutarčiai patvirtinti, o prieš planuodami keitimą patvirtinkite prisijungimo duomenų gyvavimo ciklą paskyros valdikliuose arba pas teikėjo palaikymo tarnybą. Toliau pateikta procedūra yra veiklos instrukcija, o ne teiginys, kad 17TRACK siūlo konkretų dviejų raktų ar regeneravimo procesą.
Sprendimo taisyklė: naudokite persidengiančių raktų diegimą tik tada, kai patvirtintas galiojimas vienu metu. Priešingu atveju laikykite keitimą koordinuotu prisijungimo duomenų pakeitimu. Diegimo strategija negali sukurti persidengimo laikotarpio, kurio teikėjas nepalaiko.
Sukonfigūruokite raktą vieną kartą, neplatindami jo savo sistemoje
Laikykite autentifikavimą serveryje
Gamybinį prisijungimo duomenį saugokite valdomoje paslapčių saugykloje arba lygiavertėje kontroliuojamoje sistemoje. Leiskite programai jį gauti per savo darbo krūvio tapatybę, diegimo platformą ar kitą patvirtintą mechanizmą. Apribokite skaitymo prieigą darbo krūviams ir operatoriams, kuriems jos reikia.
Neįterpkite rakto į naršyklės JavaScript, mobiliųjų programų paketus, šaltinio kodą, konteinerių atvaizdus ar bendrinamus konfigūracijos pavyzdžius. Klientams skirtas sekimo puslapis turėtų kreiptis į jūsų vidinę sistemą, kuri gali autentifikuotis pas sekimo teikėją neatskleisdama teikėjo prisijungimo duomenų.
OWASP Secrets Management Cheat Sheet rekomenduoja centralizuotą paslapčių valdymą, kontroliuojamą prieigą, auditavimą ir gyvavimo ciklo valdymą. Jo REST Security Cheat Sheet taip pat pataria nedėti API raktų į URL, nes registravimas ir kitas tvarkymas gali juos atskleisti. Laikykitės teikėjo dokumentuoto autentifikavimo metodo ir pašalinkite autentifikavimo reikšmes iš užklausų žurnalų bei diagnostikos eksportų.
Atskirkite aplinkas ir nustatykite įdiegtą versiją
Jei teikėjas tai palaiko, naudokite atskirus kūrimo, parengties ir gamybos prisijungimo duomenis. Jei atskiri prisijungimo duomenys ar paskyros nepasiekiami, dokumentuokite šį apribojimą ir neleiskite ne gamybinėms užduotims nekontroliuojamai rašyti į gamybinę aplinką.
Suteikite paslapčiai loginę konfigūracijos nuorodą, pavyzdžiui, SHIPMENT_TRACKING_API_KEY. Atskirai įrašykite paslapčių tvarkyklės versiją arba nepaslaptingą diegimo žymą. Ši žyma leidžia operatoriams atsakyti į klausimą „Kurią versiją naudoja šis darbuotojas?“, netikrinant ir neregistruojant paties prisijungimo duomens.
Aiškiai nuspręskite, kaip programos gauna atnaujinimus. Procesą, kuris paleidimo metu nuskaito aplinkos kintamąjį, paprastai reikia paleisti iš naujo arba iš naujo įdiegti, kad jis gautų pakeistą reikšmę. Prijungtas paslapties failas arba vykdymo metu atliekama paieška turi kitokį atnaujinimo elgesį. Paslapties saugyklos atnaujinimas neįrodo, kad kiekvienas veikiantis procesas priėmė pakeitimą.
Prieš keisdami raktą užtikrinkite, kad užklausas būtų galima atkurti
Prieš siųsdami sekimo darbus teikėjui, juos išsaugokite. Registruodami siuntą išsaugokite vidinį operacijos identifikatorių, siuntos nuorodą, apdorojimo būseną ir pakartotinių bandymų istoriją. Verslo duomenų rinkinį laikykite atskirai nuo autentifikavimo, kad eilėje esančios užduotys vykdymo metu galėtų naudoti aktyvų prisijungimo duomenį.
Nerašykite API raktų į eilės pranešimus. Taip uždelstos užduotys susiejamos su pasenusiu prisijungimo duomeniu, o paslaptys paskleidžiamos eilės saugykloje, neįteiktų pranešimų eilėse ir derinimo įrankiuose.
Prieš įjungdami pakartotinius bandymus nustatykite teikėjo pasikartojančių užklausų tvarkymo taisykles. Laiko limito viršijimas neįrodo, kad registracija nepavyko: teikėjas galėjo priimti užklausą prieš nutrūkstant ryšiui. Jei egzistuoja dokumentuotas idempotentiškumo mechanizmas, jį naudokite, arba prieš pateikdami iš naujo suderinkite siuntos būseną.
Sukurkite naudotojų sąrašą ir stebėjimo bazinį lygį
Dažniausiai nepastebimas naudotojas dažnai nėra pagrindinė programa. Sudarykite suplanuotų importų, eilės darbuotojų, serverless funkcijų, administracinių scenarijų, pagalbos įrankių, atkūrimo po avarijos diegimų ir paslaugų, kurios šiuo metu veikia nuliniu mastu, sąrašą.
Kiekvienam naudotojui įrašykite savininką, aplinką, paslapties nuorodą, atnaujinimo mechanizmą, vykdymo tvarkaraštį ir diegimo metodą. Nustatykite ilgai veikiančias užduotis, kurios gali laikyti prisijungimo duomenis atmintyje. Taip pat patikrinkite pakartotinai naudojamus HTTP klientus, kurie po konfigūracijos pakeitimų gali išlaikyti seną autentifikavimo antraštę.
Prieš perjungimą nustatykite šių rodiklių bazinį lygį:
- Autentifikavimo klaidos pagal paslaugą, aplinką, galinį tašką ir diegimo versiją.
- Teikėjo atsako delsa, laiko limitai, greičio ribojimo atsakai ir serverio klaidos.
- Eilės dydis, seniausios laukiančios užduoties amžius ir neįteiktų pranešimų kiekis.
- Sėkmingos siuntų registracijos ir neišspręsti registracijos bandymai.
- Webhook gavimo ir apdorojimo būklė, jei webhook yra integracijos dalis.
Atskirkite integracijos būklę nuo siuntos judėjimo. Siunta, kurioje nėra naujo vežėjo įvykio, nebūtinai rodo API klaidą. Keičiant raktą, sėkmingos autentifikuotos užklausos ir sveikos apdorojimo eilės yra tiesioginiai signalai nei siuntų, kurių pristatymo būsena pasikeitė, skaičius.
Keiskite persidengiančius raktus, kai tai palaikoma
- Sukurkite pakaitinį raktą neatšaukdami aktyvaus. Patikrinkite, ar senasis prisijungimo duomuo tebėra galiojantis. Naują prisijungimo duomenį išsaugokite kaip atskirą paslapties versiją ir tinkamai apribokite prieigą.
- Patikrinkite pakaitinį raktą izoliuotai. Naudokite dokumentuotą, mažo poveikio operaciją numatytoje aplinkoje. Patikrinkite ir HTTP rezultatą, ir bet kokį programos lygmens rezultatą atsako turinyje.
- Išbandykite tipišką darbo eigą. Patikrinkite operacijas, kurių iš tikrųjų reikia jūsų programai, o ne tik bazinį ryšį. Jei būtina registracija, naudokite autorizuotą bandomąją siuntą ir įvertinkite galimą kvotos ar atsiskaitymo poveikį.
- Įdiekite nedidelei naudotojų grupei. Perkelkite vieną darbuotojų grupę arba programos egzempliorių prie pakaitinio rakto, tada patikrinkite autentifikavimą, apdorojimo rezultatus ir eilės elgesį.
- Išplėskite diegimą visiems likusiems naudotojams. Atnaujinkite sąrašą, kai kiekviena paslauga persikrauna arba paleidžiama iš naujo. Įtraukite suplanuotas užduotis, neveikiančius darbo krūvius ir atkūrimo konfigūracijas.
- Stebėkite tinkamą patikros laikotarpį. Įvertinkite atitinkamą darbuotojo veikimo trukmę, konfigūracijos podėlio elgesį, pakartotinių bandymų delsą ir užduočių tvarkaraštį. Nėra universalaus laukimo laikotarpio, įrodančio, kad pakeitimas pritaikytas.
- Atšaukite seną raktą ir dar kartą patikrinkite. Stebėkite pasenusius naudotojus, tada pašalinkite senas paslapčių nuorodas pagal saugojimo ir reagavimo į incidentus reikalavimus.
Jei teikėjo pusėje nėra raktų naudojimo ataskaitų, naudokite diegimo įrašus ir programos pateikiamas paslapties versijos žymas, kad patikrintumėte pritaikymą. Tai suteikia veiklos įrodymų, tačiau nepakeičia išsamaus naudotojų sąrašo.
Neatidėliotiną pakeitimą atlikite kaip koordinuotą perjungimą
Jei išduodant pakaitinį raktą senasis iš karto tampa negaliojantis, nepertraukiamo autentifikavimo per laipsnišką diegimą užtikrinti negalima. Suprojektuokite perėjimą taip, kad darbai būtų saugiai atidėti, o ne prarasti.
- Prieš pakeisdami prisijungimo duomenį paruoškite programos diegimą, paslapties nuorodą, operatoriaus prieigą ir atkūrimo komandas.
- Kontroliuojamoje vietoje pristabdykite siunčiamas sekimo užklausas, o kur praktiška, toliau priimkite darbus į patvarią saugyklą.
- Ištuštinkite vykdomas užklausas arba jas apskaitykite. Neaiškius rašymo rezultatus pažymėkite suderinimui, o ne automatiškai laikykite nesėkmėmis.
- Pakeiskite teikėjo prisijungimo duomenį, atnaujinkite paslapčių saugyklą ir atnaujinkite kiekvieną naudotoją.
- Prieš išleisdami visą atsilikusių užduočių kiekį atlikite autentifikavimo ir darbo eigos patikras.
- Palaipsniui atnaujinkite apdorojimą, laikykitės teikėjo greičio ribojimų ir tikrinkite, ar nesikartoja registracijos.
Jei integracijos negalima pristabdyti, išsaugoti darbų ar patikimai atnaujinti prisijungimo duomenų, prieš įprastą keitimą pašalinkite šiuos trūkumus. Tačiau įtariamo pažeidimo atveju izoliavimui gali reikėti nedelsiant atšaukti raktą, net jei dėl to laikinai nutrūktų veikimas.
Atskirkite API autentifikavimą nuo webhook saugumo
Siunčiamas API raktas ir gaunamų webhook patvirtinimo paslaptis atlieka skirtingas funkcijas. Nemanykite, kad pakeitus vieną pasikeis ir kitas arba kad abiem naudojama ta pati reikšmė. Atskirai laikykitės teikėjo dokumentuoto webhook autentifikavimo ir pristatymo elgesio.
Keisdami siunčiamus prisijungimo duomenis, webhook gavimą palikite veikiantį, nebent yra atskira priežastis jį sustabdyti. Gaunamus pranešimus tikrinkite pagal teikėjo specifikaciją, jei architektūra leidžia, patvariai priimkite juos prieš patvirtindami gavimą ir užtikrinkite, kad apdorojimas toleruotų pasikartojančius pristatymus.
Sėkminga autentifikuota API užklausa neįrodo, kad webhook pristatymas ar apdorojimas veikia tinkamai. Tikrinkite šiuos du kelius atskirai ir nekeiskite abiejų prisijungimo duomenų per tą pačią priežiūros operaciją, nebent to reikalauja teikėjo dizainas.
Šalinkite klaidas nesukeldami pakartotinių užklausų audros
| Požymis | Pirmieji patikrinimai | Saugus atsakas |
|---|---|---|
| Autentifikavimo klaidos po diegimo | Paslapties versija, antraštės formatas, aplinka, tarpai, podėliuojami klientai | Sustabdykite aklus pakartotinius bandymus; pataisykite konfigūraciją ir patikrinkite vieną užklausą. |
| Sugenda tik kai kurie darbuotojai | Seni procesai, praleisti diegimai, uždelstos užduotys, pasenę paslapčių podėliai | Atnaujinkite paveiktus naudotojus ir palyginkite versijos žymas. |
| Greičio ribojimai atkūrimo metu | Atsilikusių užduočių išleidimo greitis ir bendras lygiagretumas | Apribokite atkūrimo greitį ir laikykitės dokumentuotų pakartotinių bandymų gairių. |
| Registracijos laikas baigiasi | Ar teikėjas jau priėmė operaciją | Prieš kartodami suderinkite būseną arba naudokite dokumentuotą idempotentiškumą. |
HTTP 401 paprastai susijęs su trūkstamu arba negaliojančiu autentifikavimu, o 403 reiškia, kad serveris atsisako vykdyti užklausą. Teikėjo atsako turinys gali tiksliau paaiškinti priežastį. Neklasifikuokite kiekvieno 403 kaip pasibaigusio rakto ir nemanykite, kad kiekvienai nesėkmingai operacijai naudojamas HTTP klaidos kodas.
Atitinkamoms laikinosioms klaidoms naudokite ribotus pakartotinius bandymus su eksponentiniu laukimu ir atsitiktine sklaida. Pakartotinis negaliojančio prisijungimo duomens siuntimas jo nepataisys. Įspėkite operatorių, išsaugokite darbą ir neleiskite, kad konfigūracijos klaida virstų nekontroliuojama užklausų audra.
Prieš pakeitimą apibrėžkite grįžimą ir užbaigimą
Keičiant persidengiančius raktus, grįžimas gali reikšti laikiną naudotojų grąžinimą prie seno prisijungimo duomens, kol jis dar galioja ir yra patikimas. Po atšaukimo ši galimybė nebeegzistuoja. Jei senasis raktas galėjo būti pažeistas, neatkurkite jo vien tam, kad atkurtumėte pasiekiamumą; išduokite kitą prisijungimo duomenį ir tęskite pirmyn.
Užbaikite keitimą tik tada, kai visi sąraše esantys naudotojai naudoja pakaitinį raktą, autentifikavimo klaidos grįžo į įprastą bazinį lygį, eilėje esantis darbas atkuriamas, neaiškūs rašymo rezultatai suderinti, o webhook apdorojimas išlieka sveikas. Užrašykite savininką, užbaigimo laiką, įdiegtą paslapties versiją ir atšaukimo rezultatą, bet neužrašykite rakto reikšmės.
Norėdami užtikrinti nuolatinį API saugumą, rotacijos tvarkaraštį pasirinkite pagal organizacijos politiką, prisijungimo duomenų atskleidimo riziką ir teikėjo galimybes. Įtariamo nutekėjimo ar netinkamos prieigos atveju keiskite ne pagal tvarkaraštį. Pakartojama ir išbandyta procedūra yra naudingesnė už savavališką dažnį, kurio integracija negali saugiai palaikyti.
DUK
Ar galiu pakeisti sekimo API raktą be prastovos?
Galbūt, jei teikėjas palaiko vienu metu galiojančius prisijungimo duomenis ir kiekvienas naudotojas gali būti perkeltas prieš atšaukimą. Jei regeneravus raktą senasis iš karto išjungiamas, suplanuokite kontroliuojamą siunčiamų užklausų pertrauką. Patvarios eilės gali išsaugoti darbą tuo metu, tačiau dėl jų ryšys su teikėju netampa nuolat pasiekiamas.
Ar eilėje esančiose siuntų užduotyse turėtų būti API raktas?
Ne. Išsaugokite siuntos operaciją ir jos apdorojimo metaduomenis, o aktyvų prisijungimo duomenį nustatykite darbuotojui vykdant užduotį. Taip sumažinamas paslapties atskleidimas ir neleidžiama uždelstoms užduotims pakartotinai naudoti nebegaliojančio rakto.
Ar pakeitus raktą ištrinamos registruotos siuntos?
Nemanykite nei vieno, nei kito. Patvirtinkite, ar registruotos siuntos ir susiję nustatymai priskirti paskyrai, programai ar prisijungimo duomeniui. Vien sėkmingas autentifikavimas neįrodo, kad pakaitinis raktas turi prieigą prie tikėtinų siuntų įrašų.
Ką daryti, jei raktas pasirodo saugykloje arba žurnale?
Laikykite jį galimai pažeistu. Nedelsdami atšaukite arba pakeiskite, patikrinkite prieigos ir naudojimo įrašus, jei jie prieinami, ir laikykitės reagavimo į incidentus proceso. Matomos reikšmės pašalinimo nepakanka, nes kopijos gali likti istorijoje, žurnalų eksportuose ar kitose sistemose.
Kaip sužinoti, ar sena suplanuota užduotis vis dar naudoja ankstesnį raktą?
Patikrinkite jos paslapties nuorodą, įdiegtą konfigūraciją ir vykdymo metu atliekamo atnaujinimo elgesį. Jei saugu, paleiskite ją kontroliuojamai arba patikrinkite jos diegimą prieš kitą suplanuotą paleidimą. Tylus valdymo skydelis neįrodo, kad retai naudojamas naudotojas buvo perkeltas.
Šaltiniai
- 17TRACK Tracking API dokumentacija — teikėjo nuoroda integracijai konfigūruoti ir dokumentuotai užklausos sutarčiai patikrinti.
- 17TRACK Tracking API — oficialus siuntų sekimo integracijų produkto kontekstas.
- OWASP Secrets Management Cheat Sheet — paslapčių saugojimo, prieigos valdiklių, audito, keitimo ir gyvavimo ciklo gairės.
- OWASP REST Security Cheat Sheet — API prisijungimo duomenų tvarkymo ir REST saugumo praktika.
- RFC 9110: HTTP Semantics — su HTTP autentifikavimu susiję būsenos kodai ir automatinio užklausų kartojimo aspektai.


