Skip to main content
HjemBloggVeiledningerSlik konfigurerer og roterer du API-nøkler for forsendelsessporing uten å ødelegge integrasjonen din

Slik konfigurerer og roterer du API-nøkler for forsendelsessporing uten å ødelegge integrasjonen din

17TRACK

For å konfigurere og rotere API-nøkler for forsendelsessporing på en sikker måte bør du oppbevare legitimasjon i en serverbasert hemmelighetsbehandler, identifisere alle applikasjoner som bruker dem og teste en erstatning før den gamle nøkkelen avvikles. Hvis leverandøren støtter overlappende legitimasjon, bør du migrere forbrukerne gradvis og tilbakekalle den gamle nøkkelen først etter verifisering. Hvis en erstatning umiddelbart ugyldiggjør den eksisterende nøkkelen, bør du planlegge et koordinert skifte med holdbare køer og gjenopprettingskontroller i stedet for å anta null nedetid.

Slik konfigurerer og roterer du API-nøkler for forsendelsessporing uten

Denne veiledningen er for utviklere og driftsteam som vedlikeholder sporingsintegrasjoner i e-handelsplattformer, ordrebehandlingssystemer, lagerprogramvare og tjenester for kundemeldinger. Målet er ikke bare å sende en autentisert forespørsel, men å bevare forsendelsesregistreringer, sporingsoppdateringer og videre behandling gjennom hele endringen.

Bekreft hvordan leverandøren håndterer legitimasjon

Før du endrer produksjonskonfigurasjonen, må du kartlegge leverandørens livssyklus for legitimasjon. En handling i et kontrollpanel merket «regenerate» kan fungere annerledes enn «create another key». Ikke trekk konklusjoner ut fra knappeetiketten.

  • Autentiseringsformat: Bekreft nødvendig header eller annen autentiseringsmekanisme, endepunktversjon og kontotilknytning.
  • Overlapping: Kan to legitimasjoner forbli gyldige samtidig? Tilbakekalles den tidligere legitimasjonen umiddelbart når en erstatning genereres?
  • Tillatelser: Finn ut om nøkler har separate omfang, miljøbegrensninger eller tilgangskontroller. Bruk disse kontrollene når de er tilgjengelige; ikke anta at de finnes.
  • Tilbakekalling: Bekreft hvordan en legitimasjon deaktiveres, og om eventuell forsinkelse i propagasjonen må tas hensyn til.
  • Driftseffekter: Avklar om kvoter, registrerte forsendelser og webhook-innstillinger tilhører kontoen, en applikasjon eller en individuell nøkkel.

For en 17TRACK-integrasjon bør du begynne med den offisielle dokumentasjonen for Tracking API og produktsiden for Tracking API. Bruk dokumentasjonen til å bekrefte autentiseringskontrakten for integrasjonen, og bekreft livssyklusen for legitimasjon gjennom kontokontrollene eller kundestøtten før du planlegger en rotasjon. Fremgangsmåten nedenfor er en operativ veiledning, ikke en påstand om at 17TRACK tilbyr en bestemt arbeidsflyt for to nøkler eller regenerering.

Beslutningsregel: Bruk en utrulling med overlappende nøkler bare når samtidig gyldighet er bekreftet. Ellers må rotasjonen behandles som en koordinert utskifting av legitimasjon. En utrullingsstrategi kan ikke opprette et overlappingsvindu som leverandøren ikke støtter.

Konfigurer nøkkelen én gang uten å spre den gjennom systemet

Hold autentiseringen på serveren

Oppbevar produksjonslegitimasjonen i en administrert hemmelighetslagring eller et tilsvarende kontrollert system. La applikasjonen hente den gjennom arbeidsbelastningens identitet, utrullingsplattformen eller en annen godkjent mekanisme. Begrens lesetilgang til arbeidsbelastninger og operatører som trenger den.

Ikke bygg inn nøkkelen i JavaScript i nettleseren, pakker for mobilapplikasjoner, kildekode, containerbilder eller delte konfigurasjonseksempler. En sporingsside som vises til kunder, bør kalle backend-systemet ditt, som kan autentisere mot sporingsleverandøren uten å eksponere leverandørlegitimasjonen.

OWASP sin Secrets Management Cheat Sheet støtter sentralisert håndtering av hemmeligheter, kontrollert tilgang, revisjon og livssyklusstyring. REST Security Cheat Sheet anbefaler også å unngå å plassere API-nøkler i URL-er, der logging og annen behandling kan eksponere dem. Følg leverandørens dokumenterte autentiseringsmetode, og fjern autentiseringsverdier fra forespørselslogger og diagnostiske eksporter.

Skill miljøene og identifiser den utrullede versjonen

Bruk separate legitimasjoner for utvikling, staging og produksjon når leverandøren støtter dette. Når separate legitimasjoner eller kontoer ikke er tilgjengelige, må du dokumentere begrensningen og hindre at jobber utenfor produksjon utfører ukontrollerte skrivinger i produksjon.

Gi hemmeligheten en logisk konfigurasjonsreferanse, for eksempel SHIPMENT_TRACKING_API_KEY. Registrer versjonen i hemmelighetsbehandleren eller en ikke-hemmelig utrullingsetikett separat. Denne etiketten gjør det mulig for operatører å svare på «Hvilken versjon bruker denne arbeideren?» uten å inspisere eller logge selve legitimasjonen.

Bestem uttrykkelig hvordan applikasjonene mottar oppdateringer. En prosess som leser en miljøvariabel ved oppstart, trenger vanligvis omstart eller ny utrulling for å motta en endret verdi. En montert hemmelighetsfil eller et oppslag ved kjøring har en annen oppdateringsatferd. At hemmelighetslagringen er oppdatert, er ikke bevis på at alle kjørende prosesser har tatt i bruk erstatningen.

Gjør forespørsler gjenopprettbare før rotasjon

Bevar sporingsarbeidet før det sendes til leverandøren. For registrering av forsendelser bør du beholde en intern operasjons-ID, forsendelsesreferanse, behandlingsstatus og historikk over nye forsøk. Hold disse forretningsdataene adskilt fra autentiseringen slik at køjobber kan bruke den aktive legitimasjonen når de kjøres.

Ikke serialiser API-nøkler i kømeldinger. Det binder forsinkede jobber til en foreldet legitimasjon og sprer hemmeligheter til kølagring, dead-letter-køer og feilsøkingsverktøy.

For skriveoperasjoner må du avklare leverandørens regler for håndtering av duplikater før du aktiverer nye forsøk. En tidsavbruddshendelse beviser ikke at registreringen mislyktes: leverandøren kan ha godtatt forespørselen før forbindelsen ble avbrutt. Bruk en dokumentert idempotensmekanisme hvis en slik finnes, eller avstem forsendelsens status før du sender den inn på nytt.

Bygg en oversikt over forbrukere og et overvåkingsgrunnlag

Den forbrukeren som lettest overses, er ofte ikke hovedapplikasjonen. Kartlegg planlagte importer, køarbeidere, serverløse funksjoner, administrative skript, supportverktøy, katastrofegjenopprettingsutrullinger og tjenester som for øyeblikket er skalert til null.

For hver forbruker registrerer du eier, miljø, hemmelighetsreferanse, oppdateringsmekanisme, kjøreplan og utrullingsmetode. Identifiser langvarige jobber som kan beholde legitimasjon i minnet. Undersøk også gjenbrukbare HTTP-klienter som kan beholde en gammel autentiseringsheader etter konfigurasjonsendringer.

Før skiftet bør du etablere et grunnlag for:

  • Autentiseringsfeil gruppert etter tjeneste, miljø, endepunkt og utrullingsversjon.
  • Leverandørens svarlatens, tidsavbrudd, svar på hastighetsbegrensninger og serverfeil.
  • Kødybde, alderen på den eldste ventende jobben og mengden i dead-letter-køen.
  • Vellykkede forsendelsesregistreringer og uavklarte registreringsforsøk.
  • Mottaks- og behandlingsstatus for webhooker hvis webhooker inngår i integrasjonen.

Skill integrasjonshelsen fra selve forsendelsens bevegelse. En pakke uten en ny hendelse fra transportøren er ikke nødvendigvis tegn på en API-feil. Under rotasjon er vellykkede autentiserte forespørsler og sunne behandlingskøer mer direkte signaler enn antallet forsendelser der leveringsstatusen er endret.

Roter med overlappende nøkler når dette støttes

  1. Opprett erstatningen uten å tilbakekalle den aktive nøkkelen. Bekreft at den gamle legitimasjonen fortsatt er gyldig. Lagre den nye legitimasjonen som en separat hemmelighetsversjon og begrens tilgangen på riktig måte.
  2. Valider erstatningen isolert. Bruk en dokumentert operasjon med lav påvirkning mot det tiltenkte miljøet. Kontroller både HTTP-resultatet og eventuelle resultater på applikasjonsnivå i svarteksten.
  3. Test en representativ arbeidsflyt. Valider operasjonene applikasjonen faktisk trenger, ikke bare en enkel tilkoblingskontroll. Hvis registrering er nødvendig, bruker du en autorisert testforsendelse og tar hensyn til mulig kvote- eller faktureringseffekt.
  4. Rull ut til en liten forbrukergruppe. Flytt én arbeidergruppe eller applikasjonsinstans til erstatningen, og kontroller deretter autentisering, behandlingsresultater og køatferd.
  5. Rull ut til alle gjenværende forbrukere. Oppdater oversikten når hver tjeneste laster konfigurasjonen på nytt eller starter på nytt. Ta med planlagte oppgaver, inaktive arbeidsbelastninger og gjenopprettingskonfigurasjoner.
  6. Overvåk i et passende verifiseringsvindu. Ta hensyn til relevant levetid for arbeidere, hurtigbufring av konfigurasjon, forsinkelse ved nye forsøk og jobbplanen. Det finnes ingen universell ventetid som beviser at alle har tatt i bruk erstatningen.
  7. Tilbakekall den gamle nøkkelen og kontroller på nytt. Se etter foreldede forbrukere, og avvikle deretter gamle hemmelighetsreferanser i henhold til kravene til oppbevaring og hendelseshåndtering.

Når rapportering av nøkkelbruk på leverandørsiden ikke er tilgjengelig, bruker du utrullingsregistre og etiketter for hemmelighetsversjoner rapportert av applikasjonen for å bekrefte at erstatningen er tatt i bruk. Dette gir operasjonelle bevis, men erstatter ikke en fullstendig oversikt over forbrukere.

Håndter umiddelbar utskifting som et koordinert skifte

Hvis utstedelse av en erstatning umiddelbart ugyldiggjør den gamle nøkkelen, kan uavbrutt autentisering ikke garanteres gjennom en rullerende utrulling. Utform overgangen slik at arbeid trygt forsinkes i stedet for å gå tapt.

  1. Forbered applikasjonsutrullingen, hemmelighetsreferansen, operatørtilgangen og gjenopprettingskommandoene før legitimasjonen erstattes.
  2. Sett utgående sporingsforespørsler på pause ved en kontrollert grense, samtidig som du fortsetter å ta imot arbeid i varig lagring der det er praktisk mulig.
  3. Tøm eller ta høyde for forespørsler som allerede er under behandling. Merk uklare skriveresultater for avstemming i stedet for automatisk å behandle dem som feil.
  4. Erstatt leverandørlegitimasjonen, oppdater hemmelighetslagringen og oppdater alle forbrukere.
  5. Kjør autentiserings- og arbeidsflytkontroller før hele etterslepet frigis.
  6. Gjenoppta behandlingen gradvis, respekter leverandørens hastighetsbegrensninger og kontroller for doble registreringer.

Hvis integrasjonen ikke kan settes på pause, beholde arbeid eller oppdatere legitimasjon på en forutsigbar måte, må du rette disse svakhetene før en rutinemessig rotasjon. Ved mistanke om kompromittering kan inneslutning likevel kreve umiddelbar tilbakekalling, selv om det fører til et midlertidig avbrudd.

Hold API-autentisering adskilt fra webhook-sikkerhet

En utgående API-nøkkel og en innkommende hemmelighet for webhook-verifisering har ulike formål. Ikke anta at rotasjon av den ene endrer den andre, eller at begge bruker samme verdi. Følg leverandørens dokumenterte autentisering og leveringsatferd for webhooker separat.

Under et skifte av utgående legitimasjon bør webhook-mottaket fortsette å kjøre med mindre det finnes en separat grunn til å stoppe det. Valider innkommende meldinger i henhold til leverandørens spesifikasjon, ta imot dem varig før du bekrefter mottak når arkitekturen tillater det, og gjør behandlingen tolerant for doble leveranser.

Et vellykket autentisert API-kall beviser ikke at levering eller behandling av webhooker fungerer. Kontroller de to banene separat, og unngå å endre begge legitimasjonene i samme vedlikeholdshandling med mindre leverandørens utforming krever det.

Feilsøk feil uten å skape en storm av nye forsøk

SymptomFørste kontrollerSikker respons
Autentiseringsfeil etter utrullingHemmelighetsversjon, header-format, miljø, mellomrom, hurtigbufrede klienterStans blinde nye forsøk; korriger konfigurasjonen og valider én forespørsel.
Bare enkelte arbeidere feilerGamle prosesser, manglende utrullinger, forsinkede jobber, foreldede hemmelighetsbuffereOppdater berørte forbrukere og sammenlign versjonsetiketter.
Hastighetsbegrensninger under gjenopprettingHastighet for frigivelse av etterslep og samlet samtidighetBegrens gjenopprettingen og følg dokumenterte råd om nye forsøk.
Registrering får tidsavbruddOm leverandøren allerede godtok operasjonenAvstem eller bruk dokumentert idempotens før du spiller av operasjonen på nytt.

HTTP 401 gjelder vanligvis manglende eller ugyldig autentisering, mens 403 betyr at serveren avviser forespørselen. Leverandørspesifikke svartekster kan forklare årsaken mer presist. Ikke klassifiser alle 403-svar som en utløpt nøkkel, og ikke anta at alle mislykkede operasjoner bruker en HTTP-feilkode.

Bruk avgrensede nye forsøk med backoff og jitter for egnede midlertidige feil. Gjentatte innsendinger med ugyldig legitimasjon reparerer ikke problemet. Varsle en operatør, behold arbeidet og hindre at en konfigurasjonsfeil utvikler seg til en ukontrollert forespørselsstorm.

Definer tilbakeføring og fullføring før endringen

Ved rotasjon med overlappende nøkler kan tilbakeføring bety at forbrukerne midlertidig returneres til den gamle legitimasjonen mens den fortsatt er gyldig og klarert. Etter tilbakekalling finnes ikke dette alternativet lenger. Hvis den gamle nøkkelen kan være kompromittert, må du ikke gjenopprette den bare for å få tilbake tilgjengeligheten; utsted en ny legitimasjon og fortsett fremover.

Fullfør rotasjonen først når alle kartlagte forbrukere bruker erstatningen, autentiseringsfeilene er tilbake på forventet grunnnivå, køarbeidet er i ferd med å hente seg inn, uklare skriveresultater er avstemt, og webhook-behandlingen fortsatt er sunn. Registrer eier, fullføringstidspunkt, utrullet hemmelighetsversjon og resultatet av tilbakekallingen uten å registrere nøkkelverdien.

For løpende API-sikkerhet velger du en rotasjonsplan basert på organisasjonens retningslinjer, risikoen for at legitimasjon eksponeres og leverandørens muligheter. Roter utenfor planen etter mistanke om lekkasje eller feilaktig tilgang. En repeterbar og testet prosedyre er mer nyttig enn en vilkårlig hyppighet som integrasjonen ikke kan støtte på en sikker måte.

Vanlige spørsmål

Kan jeg rotere en API-nøkkel for sporing uten nedetid?

Potensielt, hvis leverandøren støtter samtidige legitimasjoner og alle forbrukere kan migreres før tilbakekalling. Hvis regenerering umiddelbart deaktiverer den gamle nøkkelen, bør du planlegge et kontrollert avbrudd i utgående forespørsler. Holdbare køer kan bevare arbeidet i dette tidsrommet, men gjør ikke leverandørforbindelsen kontinuerlig tilgjengelig.

Bør kølagrede forsendelsesjobber inneholde API-nøkkelen?

Nei. Lagre forsendelsesoperasjonen og behandlingsmetadataene, og slå deretter opp den aktive legitimasjonen når arbeideren kjører. Dette reduserer eksponeringen av hemmeligheter og hindrer forsinkede jobber i å bruke en ugyldiggjort nøkkel flere ganger.

Sletter rotasjon av nøkkelen registrerte forsendelser?

Ikke anta noen av delene. Bekreft om registrerte forsendelser og relaterte innstillinger er knyttet til kontoen, applikasjonen eller legitimasjonen. Vellykket autentisering alene beviser ikke at erstatningen har tilgang til de forventede forsendelsespostene.

Hva bør jeg gjøre hvis en nøkkel dukker opp i et depot eller en logg?

Behandle den som potensielt kompromittert. Tilbakekall eller erstatt den umiddelbart, undersøk tilgangs- og bruksregistre der dette er tilgjengelig, og følg prosessen for hendelseshåndtering. Det er ikke nok å fjerne den synlige verdien, fordi kopier kan finnes i historikk, loggeksporter eller andre systemer.

Hvordan kan jeg vite om en gammel planlagt jobb fortsatt bruker den forrige nøkkelen?

Kontroller hemmelighetsreferansen, den utrullede konfigurasjonen og oppdateringsatferden ved kjøring. Kjør den gjennom en kontrollert utførelse når det er trygt, eller bekreft utrullingen før neste planlagte oppstart. Et stille kontrollpanel beviser ikke at en sjelden brukt forbruker er migrert.

Kilder