Skip to main content
DomovBlogVodnikiKako konfigurirati in zamenjati ključe API za sledenje pošiljk, ne da bi pokvarili svojo integracijo

Kako konfigurirati in zamenjati ključe API za sledenje pošiljk, ne da bi pokvarili svojo integracijo

17TRACK

Za varno konfiguracijo in rotacijo ključev API za sledenje pošiljkam shranjujte poverilnice v strežniku za upravljanje skrivnosti, določite vsako aplikacijo, ki jih uporablja, in preizkusite zamenjavo, preden umaknete stari ključ. Če vaš ponudnik podpira prekrivajoče se poverilnice, uporabnike postopoma prenesite na nov ključ in starega prekličite šele po preverjanju. Če zamenjava takoj razveljavi obstoječi ključ, načrtujte usklajen prehod z obstojnimi vrstami in preverjanji obnovitve, namesto da bi predpostavili ničelni izpad.

Kako konfigurirati in rotirati ključe API za sledenje pošiljkam brez

Ta vodnik je namenjen razvijalcem in operativnim ekipam, ki vzdržujejo integracije sledenja v platformah za e-trgovino, sistemih za upravljanje naročil, programski opremi za skladišča in storitvah za obveščanje strank. Cilj ni le poslati preverjeno zahtevo, temveč ohraniti registracije pošiljk, posodobitve sledenja in nadaljnjo obdelavo skozi celotno spremembo.

Preverite, kako vaš ponudnik upravlja poverilnice

Pred spreminjanjem produkcijske konfiguracije določite življenjski cikel poverilnic pri ponudniku. Dejanje na nadzorni plošči z oznako »ustvari znova« se lahko obnaša drugače kot »ustvari drug ključ«. Obnašanja ne sklepajte na podlagi oznake gumba.

  • Oblika preverjanja pristnosti: Potrdite zahtevano glavo ali drug mehanizem preverjanja pristnosti, različico končne točke in povezavo z računom.
  • Prekrivanje: Ali lahko dve poverilnici ostaneta veljavni hkrati? Ali ustvarjanje zamenjave takoj prekliče prejšnjo poverilnico?
  • Dovoljenja: Ugotovite, ali imajo ključi ločena področja uporabe, omejitve okolja ali nadzor dostopa. Kjer so ti nadzori na voljo, jih uporabite; ne predpostavljajte, da obstajajo.
  • Preklic: Potrdite, kako onemogočiti poverilnico in ali je treba upoštevati kakršno koli vedenje pri širjenju spremembe.
  • Operativni učinki: Ugotovite, ali kvote, registrirane pošiljke in nastavitve spletnih kavljev pripadajo računu, aplikaciji ali posameznemu ključu.

Za integracijo s 17TRACK začnite z uradno dokumentacijo Tracking API in stranjo izdelka Tracking API. Dokumentacijo uporabite za potrditev pogodbe o preverjanju pristnosti za svojo integracijo, vedenje življenjskega cikla poverilnic pa pred načrtovanjem rotacije potrdite prek nadzornih funkcij računa ali podpore. Spodnji postopek je operativni priročnik in ne trdi, da 17TRACK ponuja določen postopek z dvema ključema ali ustvarjanjem novega ključa.

Pravilo odločanja: Uvedbo s prekrivajočima se ključema uporabite le, ko je potrjena hkratna veljavnost. V nasprotnem primeru rotacijo obravnavajte kot usklajeno zamenjavo poverilnice. Strategija uvajanja ne more ustvariti časovnega okna prekrivanja, ki ga ponudnik ne podpira.

Konfigurirajte ključ enkrat, ne da bi ga širili po sistemu

Preverjanje pristnosti naj poteka na strežniku

Produkcijsko poverilnico shranite v upravljano shrambo skrivnosti ali enakovreden nadzorovan sistem. Aplikaciji dovolite, da jo pridobi prek identitete svoje delovne obremenitve, platforme za uvajanje ali drugega odobrenega mehanizma. Dostop za branje omejite na delovne obremenitve in operaterje, ki ga potrebujejo.

Ključa ne vdelujte v JavaScript brskalnika, pakete mobilnih aplikacij, izvorno kodo, slike vsebnikov ali skupne primere konfiguracije. Stran za sledenje, namenjena strankam, naj kliče vaše zaledje, ki se lahko preverjeno poveže s ponudnikom sledenja, ne da bi razkrilo poverilnico ponudnika.

OWASP-ov dokument Secrets Management Cheat Sheet podpira centralizirano upravljanje skrivnosti, nadzorovan dostop, revizijo in upravljanje življenjskega cikla. Njegov dokument REST Security Cheat Sheet prav tako odsvetuje dodajanje ključev API v URL-je, kjer jih lahko razkrijejo beleženje in drugi postopki obdelave. Upoštevajte dokumentirani način preverjanja pristnosti ponudnika ter odstranite vrednosti za preverjanje pristnosti iz dnevnikov zahtev in diagnostičnih izvozov.

Ločite okolja in določite uvedeno različico

Kadar jih ponudnik podpira, uporabljajte ločene poverilnice za razvoj, pripravo in produkcijo. Kadar ločene poverilnice ali računi niso na voljo, to omejitev dokumentirajte in preprečite, da bi neprodukcijska opravila izvajala nenadzorovane zapise v produkciji.

Skrivnosti dodelite logično konfiguracijsko referenco, na primer SHIPMENT_TRACKING_API_KEY. Različico upravitelja skrivnosti ali ne skrivno oznako uvajanja zabeležite ločeno. Ta oznaka operaterjem omogoča odgovor na vprašanje »Katero različico uporablja ta delavec?«, ne da bi morali pregledati ali zabeležiti samo poverilnico.

Izrecno določite, kako aplikacije prejemajo posodobitve. Proces, ki prebere okoljsko spremenljivko ob zagonu, običajno potrebuje ponovni zagon ali ponovno uvajanje, da prejme spremenjeno vrednost. Priklopljena datoteka skrivnosti ali iskanje med izvajanjem imata drugačno vedenje osveževanja. Posodobitev shrambe skrivnosti ni dokaz, da je vsak izvajajoči se proces prevzel zamenjavo.

Pred rotacijo omogočite obnovljive zahteve

Delo s sledenjem shranite, preden ga pošljete ponudniku. Pri registraciji pošiljke ohranite notranji identifikator operacije, referenco pošiljke, stanje obdelave in zgodovino ponovnih poskusov. Te poslovne podatke hranite ločeno od preverjanja pristnosti, da lahko opravila v vrsti ob izvedbi uporabijo aktivno poverilnico.

Ključev API ne serializirajte v sporočila vrst. S tem bi odložena opravila vezali na zastarelo poverilnico in skrivnosti razširili v shrambo vrst, vrste zavrnjenih sporočil in orodja za odpravljanje napak.

Pri operacijah zapisovanja pred omogočanjem ponovnih poskusov določite pravila ponudnika za obravnavo dvojnikov. Časovna omejitev ne dokazuje, da registracija ni uspela: ponudnik je morda zahtevo sprejel, preden je bila povezava prekinjena. Če obstaja, uporabite dokumentirani mehanizem idempotentnosti ali pred ponovno oddajo uskladite stanje pošiljke.

Ustvarite evidenco uporabnikov in osnovo za spremljanje

Najpogosteje spregledani uporabnik pogosto ni glavna aplikacija. V evidenco vključite načrtovane uvoze, delavce vrst, brezstrežniške funkcije, skrbniške skripte, podporna orodja, uvedbe za obnovitev po katastrofi in storitve, ki so trenutno zmanjšane na nič.

Za vsakega uporabnika zabeležite lastnika, okolje, referenco skrivnosti, mehanizem osveževanja, urnik izvajanja in način uvajanja. Določite dolgotrajna opravila, ki lahko hranijo poverilnice v pomnilniku. Preglejte tudi večkrat uporabne odjemalce HTTP, ki bi lahko po spremembi konfiguracije ohranili staro glavo za preverjanje pristnosti.

Pred prehodom določite osnovne vrednosti za:

  • Napake preverjanja pristnosti, razvrščene po storitvi, okolju, končni točki in različici uvajanja.
  • Odzivni čas ponudnika, časovne omejitve, odzive ob omejitvi hitrosti in napake strežnika.
  • Globino vrste, starost najstarejšega čakajočega opravila in količino zavrnjenih sporočil.
  • Uspešne registracije pošiljk in nerešene poskuse registracije.
  • Prejemanje spletnih kavljev in stanje njihove obdelave, če so spletni kavlji del integracije.

Stanje integracije ločite od premikanja pošiljk. Paket brez novega dogodka prevoznika ni nujno dokaz napake API-ja. Med rotacijo so uspešne preverjene zahteve in zdrave vrste za obdelavo bolj neposredni kazalniki kot število pošiljk, katerih stanje dostave se je spremenilo.

Rotirajte s prekrivajočimi se ključi, kadar je to podprto

  1. Ustvarite zamenjavo, ne da bi preklicali aktivni ključ. Preverite, ali stara poverilnica ostaja veljavna. Novo poverilnico shranite kot ločeno različico skrivnosti in ustrezno omejite dostop.
  2. Zamenjavo preverite ločeno. Uporabite dokumentirano operacijo z majhnim vplivom v predvidenem okolju. Preverite rezultat HTTP in morebitni rezultat na ravni aplikacije v telesu odgovora.
  3. Preizkusite reprezentativen potek dela. Preverite operacije, ki jih aplikacija dejansko potrebuje, ne le osnovnega preverjanja povezljivosti. Če je registracija obvezna, uporabite odobreno testno pošiljko in upoštevajte morebitne učinke na kvoto ali obračun.
  4. Uvedite v majhno skupino uporabnikov. Eno skupino delavcev ali primerek aplikacije preklopite na zamenjavo, nato preverite preverjanje pristnosti, rezultate obdelave in vedenje vrste.
  5. Uvedite vsem preostalim uporabnikom. Evidenco posodobite, ko se posamezna storitev znova naloži ali zažene. Vključite načrtovana opravila, neaktivne delovne obremenitve in konfiguracije za obnovitev.
  6. Spremljajte ustrezno časovno okno za preverjanje. Zajmite ustrezno življenjsko dobo delavca, vedenje predpomnilnika konfiguracije, zamik ponovnih poskusov in urnik opravil. Univerzalnega čakalnega obdobja, ki bi dokazovalo prevzem, ni.
  7. Prekličite stari ključ in ponovno preverite. Bodite pozorni na zastarele uporabnike, nato stare reference skrivnosti umaknite v skladu z zahtevami glede hrambe in odzivanja na incidente.

Kadar poročanje o uporabi ključev na strani ponudnika ni na voljo, za preverjanje prevzema uporabite zapise uvajanja in oznake različic skrivnosti, ki jih sporoča aplikacija. To zagotavlja operativne dokaze, vendar ne nadomešča popolne evidence uporabnikov.

Takojšnjo zamenjavo obravnavajte kot usklajen prehod

Če izdaja zamenjave stari ključ takoj razveljavi, neprekinjenega preverjanja pristnosti z zaporednim uvajanjem ni mogoče zagotoviti. Prehod zasnujte tako, da se delo varno odloži, namesto da bi se izgubilo.

  1. Pred zamenjavo poverilnice pripravite uvajanje aplikacije, referenco skrivnosti, dostop operaterjev in ukaze za obnovitev.
  2. Odhodne zahteve za sledenje začasno zaustavite na nadzorovani meji, hkrati pa, kjer je praktično, še naprej sprejemajte delo v obstojno shrambo.
  3. Izpraznite zahteve v izvajanju ali jih ustrezno upoštevajte. Nejasne rezultate zapisovanja označite za uskladitev, namesto da jih samodejno obravnavate kot napake.
  4. Zamenjajte poverilnico ponudnika, posodobite shrambo skrivnosti in osvežite vse uporabnike.
  5. Pred sprostitvijo celotnega zaostanka izvedite preverjanje pristnosti in potekov dela.
  6. Obdelavo nadaljujte postopoma, upoštevajte omejitve hitrosti ponudnika in preverjajte podvojene registracije.

Če integracije ni mogoče začasno zaustaviti, ohraniti dela ali predvidljivo osvežiti poverilnic, te pomanjkljivosti odpravite pred običajno rotacijo. Pri sumu na kompromitacijo pa lahko zajezitev zahteva takojšen preklic, tudi če povzroči začasen izpad.

Preverjanje pristnosti API ločite od varnosti spletnih kavljev

Odhodni ključ API in skrivnost za preverjanje dohodnih spletnih kavljev imata različna namena. Ne predpostavljajte, da rotacija enega spremeni drugega ali da oba uporabljata isto vrednost. Neodvisno upoštevajte dokumentirano preverjanje pristnosti in vedenje dostave spletnih kavljev pri ponudniku.

Med prehodom odhodne poverilnice naj sprejemanje spletnih kavljev deluje naprej, razen če obstaja ločen razlog za zaustavitev. Dohodna sporočila preverjajte v skladu s specifikacijo ponudnika, kadar arhitektura to omogoča, jih obstojno sprejmite pred potrditvijo in poskrbite, da bo obdelava odporna na podvojene dostave.

Uspešen preverjen klic API ne dokazuje, da sta dostava ali obdelava spletnih kavljev zdravi. Obe poti preverjajte ločeno in se izogibajte spreminjanju obeh poverilnic v istem vzdrževalnem postopku, razen če to zahteva zasnova ponudnika.

Odpravljajte napake, ne da bi ustvarili nevihto ponovnih poskusov

SimptomPrva preverjanjaVarni odziv
Napake preverjanja pristnosti po uvedbiRazličica skrivnosti, oblika glave, okolje, presledki, predpomnjeni odjemalciUstavite slepe ponovne poskuse; popravite konfiguracijo in preverite eno zahtevo.
Odpovejo le nekateri delavciStari procesi, izpuščene uvedbe, odložena opravila, zastareli predpomnilniki skrivnostiOsvežite prizadete uporabnike in primerjajte oznake različic.
Omejitve hitrosti med obnovitvijoHitrost sproščanja zaostanka in skupna sočasnostOmejite hitrost obnovitve in upoštevajte dokumentirana navodila za ponovne poskuse.
Registracija poteče zaradi časovne omejitveAli je ponudnik operacijo že sprejelPred ponovnim predvajanjem uskladite stanje ali uporabite dokumentirano idempotentnost.

HTTP 401 se na splošno nanaša na manjkajoče ali neveljavno preverjanje pristnosti, medtem ko 403 pomeni, da strežnik zahtevo zavrne. Telesa odgovorov, specifična za ponudnika, lahko vzrok pojasnijo natančneje. Vsakega odziva 403 ne razvrščajte kot potekli ključ in ne predpostavljajte, da vsaka neuspešna operacija uporablja status napake HTTP.

Za ustrezne prehodne napake uporabite omejene ponovne poskuse z umikom in naključnim zamikom. Večkratna oddaja neveljavne poverilnice je ne bo popravila. Opozorite operaterja, ohranite delo in preprečite, da bi konfiguracijska napaka prerasla v nenadzorovano nevihto zahtev.

Pred spremembo določite povrnitev in zaključek

Pri rotaciji s prekrivajočima se ključema lahko povrnitev pomeni začasno vrnitev uporabnikov na stari ključ, dokler je še veljaven in zaupanja vreden. Po preklicu ta možnost ne obstaja več. Če je stari ključ morda ogrožen, ga ne obnovite zgolj zaradi razpoložljivosti; izdajte drugo poverilnico in nadaljujte naprej.

Rotacijo zaključite šele, ko vsi evidentirani uporabniki uporabljajo zamenjavo, so se napake preverjanja pristnosti vrnile na pričakovano osnovno raven, se obdelava čakajočega dela obnovlja, so bili nejasni zapisi usklajeni in obdelava spletnih kavljev ostaja zdrava. Zabeležite lastnika, čas zaključka, uvedeno različico skrivnosti in rezultat preklica, ne da bi zabeležili vrednost ključa.

Za stalno varnost API izberite urnik rotacije na podlagi organizacijske politike, tveganja izpostavljenosti poverilnic in zmogljivosti ponudnika. Zunaj tega urnika rotirajte po sumu uhajanja ali neustreznem dostopu. Ponovljiv in preizkušen postopek je uporabnejši od poljubne pogostosti, ki je integracija ne more varno podpirati.

Pogosta vprašanja

Ali lahko ključ API za sledenje rotiram brez izpada?

Morda, če ponudnik podpira sočasne poverilnice in lahko vsak uporabnik pred preklicem preide na novo. Če ustvarjanje novega ključa takoj onemogoči starega, načrtujte nadzorovan prekinitev odhodnih zahtev. Obstojne vrste lahko v tem času ohranijo delo, vendar povezave s ponudnikom ne naredijo neprekinjeno razpoložljive.

Ali naj čakajoča opravila pošiljk vsebujejo ključ API?

Ne. Shranite operacijo pošiljke in njene metapodatke obdelave, nato pa aktivno poverilnico razrešite, ko jo delavec izvaja. To zmanjša izpostavljenost skrivnosti in prepreči, da bi odložena opravila večkrat uporabljala razveljavljeni ključ.

Ali rotacija ključa izbriše registrirane pošiljke?

Ne predpostavljajte nobenega od obeh izidov. Potrdite, ali so registrirane pošiljke in povezane nastavitve vezane na račun, aplikacijo ali poverilnico. Sam uspeh preverjanja pristnosti ne dokazuje, da ima zamenjava dostop do pričakovanih zapisov pošiljk.

Kaj naj storim, če se ključ pojavi v repozitoriju ali dnevniku?

Obravnavajte ga kot potencialno ogroženega. Nemudoma ga prekličite ali zamenjajte, kjer je mogoče preglejte zapise dostopa in uporabe ter upoštevajte svoj postopek odzivanja na incidente. Odstranitev vidne vrednosti ni dovolj, ker lahko kopije ostanejo v zgodovini, izvozih dnevnikov ali drugih sistemih.

Kako lahko ugotovim, ali staro načrtovano opravilo še vedno uporablja prejšnji ključ?

Preverite njegovo referenco skrivnosti, uvedeno konfiguracijo in vedenje osveževanja med izvajanjem. Kjer je varno, ga zaženite v nadzorovanem okolju ali preverite njegovo uvedbo pred naslednjim načrtovanim zagonom. Tiha nadzorna plošča ne dokazuje, da je redko uporabljen uporabnik prešel na novo različico.

Viri