Skip to main content
EtusivuBlogiOppaatLähetysseurannan API-avainten määrittäminen ja vaihtaminen rikkomatta integraatiotasi

Lähetysseurannan API-avainten määrittäminen ja vaihtaminen rikkomatta integraatiotasi

17TRACK

Voit määrittää ja kierrättää lähetysseurannan API-avaimet turvallisesti säilyttämällä tunnistetiedot palvelinpuolen salaisuuksien hallintajärjestelmässä, tunnistamalla kaikki niitä käyttävät sovellukset ja testaamalla korvaavan avaimen ennen vanhan käytöstä poistamista. Jos palveluntarjoajasi tukee samanaikaisesti voimassa olevia tunnistetietoja, siirrä käyttäjät asteittain ja kumoa vanha avain vasta vahvistuksen jälkeen. Jos korvaava avain mitätöi nykyisen avaimen välittömästi, suunnittele koordinoitu siirtymä kestävien jonojen ja palautumistarkistusten avulla sen sijaan, että olettaisit käyttökatkojen puuttuvan.

Lähetysseurannan API-avainten määrittäminen ja kierrättäminen ilman

Tämä opas on tarkoitettu kehittäjille ja operatiivisille tiimeille, jotka ylläpitävät seuranta-integraatioita verkkokauppa-alustoilla, tilaustenhallintajärjestelmissä, varasto-ohjelmistoissa ja asiakasilmoituspalveluissa. Tavoitteena ei ole ainoastaan tehdä todennettua pyyntöä, vaan säilyttää lähetysrekisteröinnit, seurantapäivitykset ja niiden jälkeinen käsittely koko muutoksen ajan.

Varmista, miten palveluntarjoajasi käsittelee tunnistetietoja

Ennen tuotantokokoonpanon muuttamista selvitä palveluntarjoajan tunnistetietojen elinkaari. Hallintapaneelin toiminto nimeltä ”regenerate” voi toimia eri tavalla kuin ”create another key”. Älä päättele toimintaa painikkeen nimestä.

  • Todennusmuoto: Varmista vaadittu otsake tai muu todennusmekanismi, päätepisteen versio ja tiliyhteys.
  • Päällekkäisyys: Voivatko kaksi tunnistetietoa olla voimassa samanaikaisesti? Kumotaanko aiempi tunnistetieto heti, kun korvaava luodaan?
  • Käyttöoikeudet: Selvitä, onko avaimilla erillisiä käyttöalueita, ympäristörajoituksia tai käyttöoikeusvalvontaa. Käytä näitä valvontakeinoja, jos ne ovat saatavilla; älä oleta niiden olevan olemassa.
  • Kumoaminen: Varmista, miten tunnistetieto poistetaan käytöstä ja onko mahdollinen viive tai etenemisvaikutus huomioitava.
  • Toiminnalliset vaikutukset: Selvitä, liittyvätkö kiintiöt, rekisteröidyt lähetykset ja webhook-asetukset tiliin, sovellukseen vai yksittäiseen avaimeen.

Jos kyseessä on 17TRACK-integraatio, aloita virallisesta Tracking API -dokumentaatiosta ja Tracking API -tuotesivusta. Vahvista dokumentaation avulla integraatiosi todennussopimus ja varmista tunnistetietojen elinkaaren toiminta tilisi hallintatoiminnoista tai tuesta ennen kierrätyksen ajoittamista. Alla oleva menettely on operatiivinen toimintaohje, ei väite siitä, että 17TRACK tarjoaisi tietyn kahden avaimen tai uudelleenluonnin työnkulun.

Päätössääntö: Käytä päällekkäisten avainten käyttöönottoa vain, kun samanaikainen voimassaolo on vahvistettu. Muussa tapauksessa käsittele kierrätystä koordinoituna tunnistetietojen vaihtona. Käyttöönotto-strategia ei voi luoda päällekkäisyysjaksoa, jota palveluntarjoaja ei tue.

Määritä avain kerran levittämättä sitä järjestelmääsi

Pidä todennus palvelimella

Tallenna tuotannon tunnistetieto hallittuun salaisuuksien säilöön tai vastaavaan valvottuun järjestelmään. Anna sovelluksen hakea se työkuormatunnisteen, käyttöönottopalvelun tai muun hyväksytyn mekanismin avulla. Rajoita lukuoikeus niitä tarvitseville työkuormille ja ylläpitäjille.

Älä upota avainta selaimen JavaScriptiin, mobiilisovellusten paketteihin, lähdekoodiin, konttikuvien sisältöön tai jaettuihin kokoonpanoesimerkkeihin. Asiakkaille näkyvän seurantasivun tulee kutsua taustajärjestelmääsi, joka voi todentaa yhteyden seurantapalveluntarjoajaan paljastamatta palveluntarjoajan tunnistetietoa.

OWASP:n Secrets Management Cheat Sheet tukee keskitettyä salaisuuksien hallintaa, valvottua käyttöä, auditointia ja elinkaaren hallintaa. Sen REST Security Cheat Sheet neuvoo myös olemaan sijoittamatta API-avaimia URL-osoitteisiin, joissa lokitus ja muu käsittely voivat paljastaa ne. Noudata palveluntarjoajan dokumentoitua todennusmenetelmää ja poista todennustiedot pyyntölokeista ja vianmääritysvienneistä.

Erota ympäristöt ja tunnista käyttöönotettu versio

Käytä erillisiä kehitys-, testi- ja tuotantotunnistetietoja, jos palveluntarjoaja tukee niitä. Jos erillisiä tunnistetietoja tai tilejä ei ole saatavilla, dokumentoi rajoitus ja estä tuotannon ulkopuolisia töitä tekemästä hallitsemattomia kirjoituksia tuotantoon.

Anna salaisuudelle looginen kokoonpanoviite, kuten SHIPMENT_TRACKING_API_KEY. Tallenna salaisuuksienhallinnan versio tai muu ei-salainen käyttöönottotunniste erikseen. Tämän tunnisteen avulla ylläpitäjät voivat vastata kysymykseen ”Mitä versiota tämä työntekijä käyttää?” tarkastelematta tai lokittamatta itse tunnistetietoa.

Päätä nimenomaisesti, miten sovellukset vastaanottavat päivitykset. Prosessi, joka lukee ympäristömuuttujan käynnistyksen yhteydessä, tarvitsee yleensä uudelleenkäynnistyksen tai uuden käyttöönoton muuttuneen arvon vastaanottamiseksi. Liitetyn salaisuustiedoston tai ajonaikaisen haun päivitystoiminta on erilainen. Salaisuuksienhallinnan päivittäminen ei todista, että jokainen käynnissä oleva prosessi on ottanut korvaavan arvon käyttöön.

Tee pyynnöistä palautettavia ennen kierrätystä

Säilytä seurantatyö ennen sen lähettämistä palveluntarjoajalle. Lähetyksen rekisteröintiä varten säilytä sisäinen operaatiotunniste, lähetysviite, käsittelytila ja uudelleenyrityshistoria. Pidä tämä liiketoimintakuorma erillään todennuksesta, jotta jonotetut työt voivat käyttää aktiivista tunnistetietoa suoritushetkellä.

Älä serialisoi API-avaimia jonoviesteihin. Tällöin viivästyneet työt sidotaan vanhentuneeseen tunnistetietoon ja salaisuudet leviävät jonotallennukseen, hylkäysjonoihin ja vianmääritystyökaluihin.

Selvitä kirjoitusoperaatioita varten palveluntarjoajan säännöt kaksoiskäsittelylle ennen uudelleenyritysten käyttöönottoa. Aikakatkaisu ei todista rekisteröinnin epäonnistuneen: palveluntarjoaja on voinut hyväksyä pyynnön ennen yhteyden katkeamista. Käytä dokumentoitua idempotenssimenetelmää, jos sellainen on olemassa, tai sovita lähetyksen tila ennen uudelleenlähetystä.

Laadi käyttäjäluettelo ja seurannan perustaso

Helpommin huomaamatta jäävä käyttäjä ei usein ole pääsovellus. Luetteloi ajoitetut tuonnit, jonotyöntekijät, palvelimettomat funktiot, ylläpitoskriptit, tukityökalut, katastrofipalautuksen käyttöönotot ja palvelut, joiden skaalaus on tällä hetkellä nollassa.

Kirjaa kustakin käyttäjästä omistaja, ympäristö, salaisuusviite, päivitysmekanismi, suoritusajankohta ja käyttöönottomenetelmä. Tunnista pitkäkestoiset työt, jotka voivat säilyttää tunnistetietoja muistissa. Tarkista myös uudelleenkäytettävät HTTP-asiakkaat, jotka saattavat säilyttää vanhan todennusotsakkeen kokoonpanomuutosten jälkeen.

Ennen siirtymää määritä perustaso seuraaville:

  • Todennusvirheet ryhmiteltyinä palvelun, ympäristön, päätepisteen ja käyttöönotetun version mukaan.
  • Palveluntarjoajan vastausviive, aikakatkaisut, nopeusrajoitusvastaukset ja palvelinvirheet.
  • Jonon koko, vanhimman odottavan työn ikä ja hylkäysjonon määrä.
  • Onnistuneet lähetysrekisteröinnit ja ratkaisemattomat rekisteröintiyritykset.
  • Webhook-viestien vastaanoton ja käsittelyn tila, jos webhookit kuuluvat integraatioon.

Erota integraation tila lähetysten etenemisestä. Paketti, josta ei ole tullut uutta kuljetusyhtiön tapahtumaa, ei välttämättä ole todiste API-virheestä. Kierrätyksen aikana onnistuneet todennetut pyynnöt ja terveet käsittelyjonot ovat suorempia signaaleja kuin niiden lähetysten määrä, joiden toimitustila muuttui.

Kierrätä päällekkäisillä avaimilla, kun sitä tuetaan

  1. Luo korvaava avain kumoamatta aktiivista avainta. Varmista, että vanha tunnistetieto on edelleen voimassa. Tallenna uusi tunnistetieto erillisenä salaisuusversiona ja rajoita käyttöoikeus asianmukaisesti.
  2. Vahvista korvaava avain erillään. Käytä dokumentoitua, vähän vaikutusta aiheuttavaa operaatiota tarkoitetussa ympäristössä. Tarkista sekä HTTP-tulos että vastausrungon mahdollinen sovellustason tulos.
  3. Testaa edustava työnkulku. Vahvista sovelluksesi tosiasiallisesti tarvitsemat operaatiot, älä vain perusyhteystestiä. Jos rekisteröintiä tarvitaan, käytä hyväksyttyä testilähetystä ja huomioi mahdolliset kiintiö- tai laskutusvaikutukset.
  4. Ota käyttöön pienessä käyttäjäryhmässä. Siirrä yksi työntekijäryhmä tai sovellusinstanssi käyttämään korvaavaa avainta ja tarkista todennus, käsittelyn tulokset ja jonon toiminta.
  5. Ota käyttöön kaikilla jäljellä olevilla käyttäjillä. Päivitä luettelo, kun kukin palvelu lataa kokoonpanon uudelleen tai käynnistyy uudelleen. Sisällytä ajoitetut tehtävät, passiiviset työkuormat ja palautuskokoonpanot.
  6. Seuraa sopivan vahvistusajan ajan. Ota huomioon työntekijän käyttöikä, kokoonpanovälimuistin toiminta, uudelleenyrityksen viive ja työn ajoitus. Ei ole olemassa yleistä odotusaikaa, joka todistaisi käyttöönoton.
  7. Kiellä vanha avain ja tarkista uudelleen. Tarkkaile vanhoja käyttäjiä ja poista vanhat salaisuusviitteet käytöstä säilytys- ja poikkeamienhallintavaatimustesi mukaisesti.

Jos palveluntarjoajan puolelta ei ole saatavilla avainten käyttöraportointia, käytä käyttöönottoaineistoja ja sovelluksen ilmoittamia salaisuusversion tunnisteita käyttöönoton varmistamiseen. Tämä tarjoaa operatiivista näyttöä, mutta ei korvaa täydellistä käyttäjäluetteloa.

Käsittele välitön vaihto koordinoituna siirtymänä

Jos uuden avaimen myöntäminen mitätöi vanhan avaimen välittömästi, keskeytymätöntä todennusta ei voida taata asteittaisella käyttöönotolla. Suunnittele siirtymä niin, että työ viivästyy turvallisesti eikä katoa.

  1. Valmistele sovelluksen käyttöönotto, salaisuusviite, ylläpitäjän käyttöoikeus ja palautuskomennot ennen tunnistetiedon vaihtamista.
  2. Keskeytä lähtevät seurantapyynnöt hallitussa rajakohdassa ja jatka työn vastaanottamista kestävään tallennukseen, jos se on käytännöllistä.
  3. Tyhjennä käynnissä olevat pyynnöt tai käsittele ne asianmukaisesti. Merkitse epäselvät kirjoitustulokset sovitettaviksi sen sijaan, että käsittelisit ne automaattisesti epäonnistumisina.
  4. Vaihda palveluntarjoajan tunnistetieto, päivitä salaisuuksienhallinta ja päivitä jokainen käyttäjä.
  5. Suorita todennus- ja työnkulkutarkistukset ennen koko jonon vapauttamista.
  6. Jatka käsittelyä asteittain noudattaen palveluntarjoajan nopeusrajoituksia ja tarkista kaksoisrekisteröinnit.

Jos integraatiota ei voida keskeyttää, työtä säilyttää tai tunnistetietoja päivittää ennakoitavasti, korjaa nämä heikkoudet ennen rutiininomaista kierrätystä. Epäillyn vaarantumisen tapauksessa eristäminen voi kuitenkin edellyttää välitöntä kumoamista, vaikka se aiheuttaisi tilapäisen keskeytyksen.

Pidä API-todennus erillään webhook-turvallisuudesta

Lähtevä API-avain ja saapuvien webhookien varmennussalaisuus palvelevat eri tarkoituksia. Älä oleta, että toisen kierrättäminen muuttaa toista tai että molemmissa käytetään samaa arvoa. Noudata palveluntarjoajan dokumentoitua webhook-todennusta ja toimituskäyttäytymistä erikseen.

Pidä webhookien vastaanotto käynnissä lähtevän tunnistetiedon siirtymän aikana, ellei sen pysäyttämiseen ole erillistä syytä. Vahvista saapuvat viestit palveluntarjoajan määrittelyn mukaisesti, hyväksy ne pysyvästi ennen kuittausta, jos arkkitehtuuri sen sallii, ja tee käsittelystä kaksoistoimituksia kestävä.

Onnistunut todennettu API-kutsu ei todista webhookien toimituksen tai käsittelyn olevan kunnossa. Tarkista nämä kaksi polkua erikseen ja vältä molempien tunnistetietojen muuttamista samassa huoltotoimenpiteessä, ellei palveluntarjoajan rakenne sitä edellytä.

Vianmääritys ilman uudelleenyritysmyrskyä

OireEnsimmäiset tarkistuksetTurvallinen vastaus
Todennusvirheitä käyttöönoton jälkeenSalaisuusversio, otsakemuoto, ympäristö, välilyönnit, välimuistitetut asiakkaatLopeta sokeat uudelleenyritykset; korjaa kokoonpano ja vahvista yksi pyyntö.
Vain jotkin työntekijät epäonnistuvatVanhat prosessit, väliin jääneet käyttöönotot, viivästyneet työt, vanhentuneet salaisuusvälimuistitPäivitä ongelmalliset käyttäjät ja vertaa versiotunnisteita.
Nopeusrajoitukset palautumisen aikanaJonon vapautusnopeus ja yhteenlaskettu samanaikaisuusRajoita palautumisnopeutta ja noudata dokumentoituja uudelleenyritysohjeita.
Rekisteröinnin aikakatkaisuHyväksyikö palveluntarjoaja operaation joSovita tila tai käytä dokumentoitua idempotenssia ennen toistoa.

HTTP 401 liittyy yleensä puuttuvaan tai virheelliseen todennukseen, kun taas 403 tarkoittaa, että palvelin kieltäytyy pyynnöstä. Palveluntarjoajakohtaiset vastausrungot voivat selittää syyn tarkemmin. Älä luokittele jokaista 403-virhettä vanhentuneen avaimen aiheuttamaksi tai oleta, että jokainen epäonnistunut operaatio käyttää HTTP-virhetilaa.

Käytä sopiviin väliaikaisiin virheisiin rajattuja uudelleenyrityksiä, viivettä ja satunnaistamista. Virheellisen tunnistetiedon toistuva lähettäminen ei korjaa sitä. Hälytä ylläpitäjä, säilytä työ ja estä kokoonpanovirheen muuttuminen hallitsemattomaksi pyyntömyrskyksi.

Määritä palautus ja valmistuminen ennen muutosta

Päällekkäisten avainten kierrätyksessä palautus voi tarkoittaa kuluttajien palauttamista väliaikaisesti vanhaan tunnistetietoon, kun se on edelleen voimassa ja luotettu. Kumoamisen jälkeen tämä vaihtoehto ei ole enää käytettävissä. Jos vanha avain saattaa olla vaarantunut, älä palauta sitä vain saatavuuden palauttamiseksi; myönnä uusi tunnistetieto ja jatka eteenpäin.

Suorita kierrätys loppuun vasta, kun kaikki luetteloidut käyttäjät käyttävät korvaavaa tunnistetietoa, todennusvirheet ovat palanneet odotetulle perustasolle, jonotettu työ palautuu, epäselvät kirjoitukset on sovitettu ja webhook-käsittely toimii edelleen terveesti. Kirjaa omistaja, valmistumisaika, käyttöönotettu salaisuusversio ja kumoamisen tulos tallentamatta avaimen arvoa.

Valitse jatkuvaa API-turvallisuutta varten kierrätysaikataulu organisaation käytännön, tunnistetietojen paljastumisriskin ja palveluntarjoajan ominaisuuksien perusteella. Kierrätä aikataulun ulkopuolella epäillyn vuodon tai sopimattoman käytön jälkeen. Toistettava ja testattu menettely on hyödyllisempi kuin mielivaltainen tiheys, jota integraatio ei pysty turvallisesti tukemaan.

Usein kysytyt kysymykset

Voinko kierrättää seurannan API-avaimen ilman käyttökatkoa?

Mahdollisesti, jos palveluntarjoaja tukee samanaikaisia tunnistetietoja ja jokainen käyttäjä voidaan siirtää ennen kumoamista. Jos uudelleenluonti poistaa vanhan avaimen käytöstä välittömästi, suunnittele lähtevien pyyntöjen hallittu keskeytys. Kestävät jonot voivat säilyttää työn tämän ajanjakson aikana, mutta ne eivät tee palveluntarjoajayhteydestä jatkuvasti saatavilla olevaa.

Pitäisikö jonotettujen lähetystöiden sisältää API-avain?

Ei. Tallenna lähetysoperaatio ja sen käsittelyn metatiedot ja selvitä aktiivinen tunnistetieto työntekijän suoritushetkellä. Tämä vähentää salaisuuden paljastumista ja estää viivästyneitä töitä käyttämästä toistuvasti mitätöityä avainta.

Poistaako avaimen kierrättäminen rekisteröidyt lähetykset?

Älä oleta kumpaakaan lopputulosta. Varmista, liittyvätkö rekisteröidyt lähetykset ja niihin liittyvät asetukset tiliin, sovellukseen vai tunnistetietoon. Pelkkä todennuksen onnistuminen ei todista, että korvaavalla tunnistetiedolla on pääsy odotettuihin lähetystietoihin.

Mitä teen, jos avain näkyy repositoriossa tai lokissa?

Käsittele sitä mahdollisesti vaarantuneena. Kumoa tai vaihda se nopeasti, tarkista saatavilla olevat käyttö- ja käyttöhistoriatiedot ja noudata poikkeamienhallintaprosessiasi. Näkyvän arvon poistaminen ei riitä, koska kopioita voi olla historiassa, lokivienneissä tai muissa järjestelmissä.

Miten voin selvittää, käyttääkö vanha ajoitettu työ edelleen aiempaa avainta?

Tarkista sen salaisuusviite, käyttöönotettu kokoonpano ja ajonaikainen päivitystoiminta. Suorita se hallitusti, jos se on turvallista, tai tarkista sen käyttöönotto ennen seuraavaa ajoitettua käynnistystä. Hiljainen hallintapaneeli ei todista, että harvoin käytetty käyttäjä olisi siirtynyt.

Lähteet