Skip to main content
HjemBlogVejledningerSådan konfigurerer og roterer du API-nøgler til forsendelsessporing uden at ødelægge din integration

Sådan konfigurerer og roterer du API-nøgler til forsendelsessporing uden at ødelægge din integration

17TRACK

For at konfigurere og rotere API-nøgler til forsendelsessporing sikkert skal du opbevare legitimationsoplysninger i en serverbaseret secrets manager, identificere alle applikationer, der bruger dem, og teste en erstatning, før den gamle nøgle udfases. Hvis din udbyder understøtter overlappende legitimationsoplysninger, skal du migrere forbrugere gradvist og først tilbagekalde den gamle nøgle efter verificering. Hvis en erstatning straks ugyldiggør den eksisterende nøgle, skal du planlægge en koordineret overgang med holdbare køer og gendannelseskontroller i stedet for at antage nul nedetid.

Sådan konfigurerer og roterer du API-nøgler til forsendelsessporing uden

Denne vejledning er beregnet til udviklere og driftsteams, der vedligeholder sporingsintegrationer i e-handelsplatforme, ordrebehandlingssystemer, lagerprogrammer og tjenester til kundemeddelelser. Formålet er ikke blot at sende en godkendt forespørgsel, men at bevare forsendelsesregistreringer, sporingsopdateringer og efterfølgende behandling under hele ændringen.

Bekræft, hvordan din udbyder håndterer legitimationsoplysninger

Før du ændrer produktionskonfigurationen, skal du fastlægge udbyderens livscyklus for legitimationsoplysninger. En dashboardhandling med navnet “generer igen” kan fungere anderledes end “opret en anden nøgle”. Udled ikke funktionen af knapteksten.

  • Godkendelsesformat: Bekræft den påkrævede header eller anden godkendelsesmekanisme, endpoint-versionen og kontotilknytningen.
  • Overlap: Kan to legitimationsoplysninger forblive gyldige samtidigt? Tilbagekalder generering af en erstatning den tidligere legitimationsoplysning med det samme?
  • Tilladelser: Fastslå, om nøgler har separate scopes, miljøbegrænsninger eller adgangskontroller. Brug disse kontroller, hvor de er tilgængelige; antag ikke, at de findes.
  • Tilbagekaldelse: Bekræft, hvordan en legitimationsoplysning deaktiveres, og om der skal tages højde for udbredelsesadfærd.
  • Driftsmæssige virkninger: Fastslå, om kvoter, registrerede forsendelser og webhook-indstillinger tilhører kontoen, en applikation eller en individuel nøgle.

For en 17TRACK-integration skal du begynde med den officielle Tracking API-dokumentation og produktsiden for Tracking API. Brug dokumentationen til at bekræfte godkendelseskontrakten for din integration, og bekræft adfærden for legitimationsoplysningernes livscyklus via dine kontroller eller support, før du planlægger en rotation. Proceduren nedenfor er en operationel runbook og ikke en påstand om, at 17TRACK tilbyder en bestemt arbejdsgang med to nøgler eller regenerering.

Beslutningsregel: Brug kun en udrulning med overlappende nøgler, når samtidig gyldighed er bekræftet. Ellers skal rotation behandles som en koordineret udskiftning af legitimationsoplysninger. En udrulningsstrategi kan ikke skabe et overlapvindue, som udbyderen ikke understøtter.

Konfigurer nøglen én gang uden at sprede den gennem dit system

Behold godkendelsen på serveren

Opbevar produktionslegitimationsoplysningen i et administreret secrets store eller et tilsvarende kontrolleret system. Lad applikationen hente den via sin workload-identitet, udrulningsplatform eller en anden godkendt mekanisme. Begræns læseadgangen til de workloads og operatører, der har brug for den.

Indlejr ikke nøglen i browser-JavaScript, mobilapplikationspakker, kildekode, containerimages eller delte konfigurationseksempler. En kundevendt sporingsside bør kalde din backend, som kan godkende over for sporingsudbyderen uden at eksponere udbyderens legitimationsoplysning.

OWASP’s Secrets Management Cheat Sheet understøtter centraliseret håndtering af hemmeligheder, kontrolleret adgang, revision og livscyklusstyring. Dens REST Security Cheat Sheet fraråder også at placere API-nøgler i URL’er, hvor logning og anden håndtering kan eksponere dem. Følg udbyderens dokumenterede godkendelsesmetode, og fjern godkendelsesværdier fra requestlogs og diagnostiske eksporter.

Adskil miljøer, og identificer den udrullede version

Brug separate legitimationsoplysninger til udvikling, staging og produktion, når udbyderen understøtter det. Hvor separate legitimationsoplysninger eller konti ikke er tilgængelige, skal du dokumentere denne begrænsning og forhindre ikke-produktionsjobs i at udføre ukontrollerede skrivninger i produktionen.

Giv hemmeligheden en logisk konfigurationsreference, f.eks. SHIPMENT_TRACKING_API_KEY. Registrer secrets-manager-versionen eller en ikke-hemmelig udrulningsetiket separat. Denne etiket lader operatører besvare spørgsmålet “Hvilken version bruger denne worker?” uden at inspicere eller logge selve legitimationsoplysningen.

Beslut udtrykkeligt, hvordan applikationer modtager opdateringer. En proces, der læser en miljøvariabel ved opstart, kræver normalt en genstart eller ny udrulning for at modtage en ændret værdi. En monteret hemmelighedsfil eller et opslag ved runtime har en anden opdateringsadfærd. Opdatering af secrets store er ikke et bevis på, at alle kørende processer har taget erstatningen i brug.

Gør forespørgsler gendannelige før rotation

Gem sporingsarbejde, før det sendes til udbyderen. For forsendelsesregistrering skal du bevare en intern operationsidentifikator, forsendelsesreference, behandlingstilstand og historik over forsøg. Hold disse forretningsdata adskilt fra godkendelsen, så kølagte jobs kan bruge den aktive legitimationsoplysning, når de udføres.

Serialiser ikke API-nøgler i kømeddelelser. Det binder forsinkede jobs til en forældet legitimationsoplysning og spreder hemmeligheder til kølagring, dead-letter-køer og fejlfindingsværktøjer.

For skriveoperationer skal du fastlægge udbyderens regler for håndtering af dubletter, før du aktiverer gentagne forsøg. En timeout beviser ikke, at registreringen mislykkedes: udbyderen kan have accepteret forespørgslen, før forbindelsen blev afbrudt. Brug en dokumenteret idempotensmekanisme, hvis en sådan findes, eller afstem forsendelsens tilstand, før du sender den igen.

Opret en forbrugerfortegnelse og en overvågningsbaseline

Den forbruger, der lettest overses, er ofte ikke hovedapplikationen. Oplist planlagte importer, kø-workers, serverløse funktioner, administrative scripts, supportværktøjer, disaster-recovery-udrulninger og tjenester, der i øjeblikket er skaleret til nul.

Registrer for hver forbruger dens ejer, miljø, hemmelighedsreference, opdateringsmekanisme, kørselsplan og udrulningsmetode. Identificer langvarige jobs, der kan have legitimationsoplysninger liggende i hukommelsen. Undersøg også genanvendelige HTTP-klienter, som kan beholde en gammel godkendelsesheader efter konfigurationsændringer.

Før overgangen skal du etablere en baseline for:

  • Godkendelsesfejl grupperet efter tjeneste, miljø, endpoint og udrulningsversion.
  • Udbyderens svarforsinkelse, timeouts, svar om hastighedsbegrænsning og serverfejl.
  • Kødybde, alderen på det ældste ventende job og mængden af dead-letter-meddelelser.
  • Vellykkede forsendelsesregistreringer og uafklarede registreringsforsøg.
  • Modtagelse og behandlingsstatus for webhooks, hvis webhooks indgår i integrationen.

Adskil integrationssundhed fra forsendelsesbevægelser. En pakke uden en ny hændelse fra transportøren er ikke nødvendigvis tegn på en API-fejl. Under rotation er vellykkede godkendte forespørgsler og sunde behandlingskøer mere direkte signaler end antallet af forsendelser, hvis leveringsstatus blev ændret.

Rotér med overlappende nøgler, når det understøttes

  1. Opret erstatningen uden at tilbagekalde den aktive nøgle. Bekræft, at den gamle legitimationsoplysning stadig er gyldig. Gem den nye legitimationsoplysning som en særskilt hemmeligheds-version, og begræns adgangen korrekt.
  2. Valider erstatningen isoleret. Brug en dokumenteret operation med lav påvirkning mod det tilsigtede miljø. Kontrollér både HTTP-resultatet og eventuelle resultater på applikationsniveau i svarlegemet.
  3. Test en repræsentativ arbejdsgang. Valider de operationer, som applikationen faktisk har brug for, ikke kun en grundlæggende forbindelsestest. Hvis registrering er påkrævet, skal du bruge en autoriseret testforsendelse og tage højde for eventuelle kvote- eller faktureringseffekter.
  4. Udrul til en lille forbrugergruppe. Flyt én worker-gruppe eller applikationsinstans til erstatningen, og kontrollér derefter godkendelse, behandlingsresultater og køadfærd.
  5. Udrul til alle resterende forbrugere. Opdater fortegnelsen, efterhånden som hver tjeneste genindlæser eller genstarter. Medtag planlagte opgaver, inaktive workloads og gendannelseskonfigurationer.
  6. Observer i et passende verificeringsvindue. Dæk den relevante worker-levetid, konfigurationscacheadfærd, gentagelsesforsinkelse og jobplan. Der findes ingen universel ventetid, der beviser, at erstatningen er taget i brug.
  7. Tilbagekald den gamle nøgle, og verificer igen. Hold øje med forældede forbrugere, og udfas derefter gamle hemmelighedsreferencer i henhold til kravene til opbevaring og hændelsesrespons.

Hvor rapportering af nøglebrug på udbydersiden ikke er tilgængelig, skal du bruge udrulningsregistre og applikationsrapporterede etiketter for hemmeligheds-versioner til at verificere ibrugtagningen. Dette giver driftsmæssige beviser, men erstatter ikke en komplet forbrugerfortegnelse.

Håndter øjeblikkelig erstatning som en koordineret overgang

Hvis udstedelse af en erstatning straks ugyldiggør den gamle nøgle, kan uafbrudt godkendelse ikke garanteres gennem en løbende udrulning. Design overgangen, så arbejdet forsinkes sikkert i stedet for at gå tabt.

  1. Forbered applikationsudrulningen, hemmelighedsreferencen, operatøradgangen og gendannelseskommandoerne, før du erstatter legitimationsoplysningen.
  2. Sæt udgående sporingsforespørgsler på pause ved en kontrolleret grænse, mens du fortsat accepterer arbejde i holdbar lagring, hvor det er praktisk muligt.
  3. Dræn eller gør rede for forespørgsler under behandling. Markér tvetydige skriveresultater til afstemning i stedet for automatisk at behandle dem som fejl.
  4. Erstat udbyderens legitimationsoplysning, opdater secrets store, og opdater alle forbrugere.
  5. Kør godkendelses- og arbejdsgangskontroller, før du frigiver hele backloggen.
  6. Genoptag behandlingen gradvist, respekter udbyderens hastighedsbegrænsninger, og kontrollér for duplikerede registreringer.

Hvis integrationen ikke kan sættes på pause, bevare arbejde eller opdatere legitimationsoplysninger forudsigeligt, skal du rette disse svagheder før en rutinemæssig rotation. Ved mistanke om kompromittering kan inddæmning dog kræve øjeblikkelig tilbagekaldelse, selv når det medfører en midlertidig afbrydelse.

Hold API-godkendelse adskilt fra webhook-sikkerhed

En udgående API-nøgle og en indgående webhook-verificeringshemmelighed tjener forskellige formål. Antag ikke, at rotation af den ene ændrer den anden, eller at de bruger samme værdi. Følg uafhængigt udbyderens dokumenterede godkendelses- og leveringsadfærd for webhooks.

Under en overgang til nye udgående legitimationsoplysninger skal webhook-indlæsningen fortsætte, medmindre der er en separat grund til at stoppe den. Valider indgående meddelelser i henhold til udbyderens specifikation, accepter dem holdbart, før du kvitterer, når arkitekturen tillader det, og gør behandlingen tolerant over for dublerede leveringer.

Et vellykket godkendt API-kald beviser ikke, at webhook-levering eller -behandling fungerer korrekt. Kontrollér de to stier separat, og undgå at ændre begge legitimationsoplysninger i samme vedligeholdelseshandling, medmindre udbyderens design kræver det.

Fejlfind uden at skabe en gentagelsesstorm

SymptomFørste kontrollerSikkert svar
Godkendelsesfejl efter udrulningHemmeligheds-version, headerformat, miljø, mellemrum, cachede klienterStop blinde gentagelser; ret konfigurationen, og valider én forespørgsel.
Kun nogle workers fejlerGamle processer, oversete udrulninger, forsinkede jobs, forældede hemmelighedscachesOpdater de berørte forbrugere, og sammenlign versionsetiketter.
Hastighedsbegrænsninger under gendannelseFrigivelseshastighed for backloggen og samlet samtidighedBegræns gendannelseshastigheden, og følg den dokumenterede vejledning om gentagelser.
Registrering får timeoutOm udbyderen allerede accepterede operationenAfstem eller brug dokumenteret idempotens, før du afspiller operationen.

HTTP 401 vedrører generelt manglende eller ugyldig godkendelse, mens 403 betyder, at serveren afviser forespørgslen. Udbyderspecifikke svarlegemer kan forklare årsagen mere præcist. Klassificér ikke alle 403-svar som en udløbet nøgle, og antag ikke, at enhver mislykket operation bruger en HTTP-fejlstatus.

Brug begrænsede gentagelser med backoff og jitter ved passende midlertidige fejl. Gentagen indsendelse med en ugyldig legitimationsoplysning løser den ikke. Underret en operatør, bevar arbejdet, og sørg for, at en konfigurationsfejl ikke bliver til en ukontrolleret forespørgselsstorm.

Definer tilbagerulning og færdiggørelse før ændringen

Ved rotation med overlappende nøgler kan tilbagerulning betyde midlertidigt at føre forbrugere tilbage til den gamle legitimationsoplysning, mens den stadig er gyldig og betroet. Efter tilbagekaldelse findes denne mulighed ikke længere. Hvis den gamle nøgle kan være kompromitteret, må du ikke gendanne den blot for at genoprette tilgængeligheden; udsted en anden legitimationsoplysning, og fortsæt fremad.

Gennemfør først rotationen, når alle forbrugere i fortegnelsen bruger erstatningen, godkendelsesfejlene er vendt tilbage til deres forventede baseline, kølagt arbejde er ved at blive behandlet, tvetydige skrivninger er afstemt, og webhook-behandlingen fortsat er sund. Registrer ejer, færdiggørelsestidspunkt, udrullet hemmeligheds-version og resultatet af tilbagekaldelsen uden at registrere nøgleværdien.

For løbende API-sikkerhed skal du vælge en rotationsplan baseret på organisationens politik, risikoen for eksponering af legitimationsoplysninger og udbyderens muligheder. Rotér uden for planen efter mistanke om læk eller upassende adgang. En gentagelig, afprøvet procedure er mere nyttig end en vilkårlig frekvens, som integrationen ikke sikkert kan understøtte.

Ofte stillede spørgsmål

Kan jeg rotere en API-nøgle til sporing uden nedetid?

Potentielt, hvis udbyderen understøtter samtidige legitimationsoplysninger, og alle forbrugere kan migrere før tilbagekaldelsen. Hvis regenerering straks deaktiverer den gamle nøgle, skal du planlægge en kontrolleret afbrydelse af udgående forespørgsler. Holdbare køer kan bevare arbejdet i dette interval, men de gør ikke forbindelsen til udbyderen kontinuerligt tilgængelig.

Bør kølagte forsendelsesjobs indeholde API-nøglen?

Nej. Gem forsendelsesoperationen og dens behandlingsmetadata, og slå derefter den aktive legitimationsoplysning op, når workeren udfører jobbet. Det reducerer eksponeringen af hemmeligheder og forhindrer forsinkede jobs i gentagne gange at bruge en ugyldiggjort nøgle.

Sletter rotation af nøglen registrerede forsendelser?

Antag ikke nogen af delene. Bekræft, om registrerede forsendelser og relaterede indstillinger er knyttet til kontoen, applikationen eller legitimationsoplysningen. Succesfuld godkendelse alene beviser ikke, at erstatningen har adgang til de forventede forsendelsesposter.

Hvad skal jeg gøre, hvis en nøgle vises i et repository eller en log?

Behandl den som potentielt kompromitteret. Tilbagekald eller erstat den straks, undersøg adgangs- og brugsregistre, hvor de er tilgængelige, og følg din proces for hændelsesrespons. Det er ikke nok at fjerne den synlige værdi, fordi kopier kan findes i historik, logeksporter eller andre systemer.

Hvordan kan jeg se, om et gammelt planlagt job stadig bruger den tidligere nøgle?

Kontrollér dets hemmelighedsreference, udrullede konfiguration og opdateringsadfærd ved runtime. Kør det gennem en kontrolleret eksekvering, hvor det er sikkert, eller verificer dets udrulning før næste planlagte start. Et stille dashboard beviser ikke, at en sjældent anvendt forbruger er migreret.

Kilder