Skip to main content
НачалоБлогРъководстваКак да конфигурирате и ротирате API ключовете за проследяване на пратки, без да нарушите интеграцията си

Как да конфигурирате и ротирате API ключовете за проследяване на пратки, без да нарушите интеграцията си

17TRACK

За да конфигурирате и безопасно да ротирате API ключовете за проследяване на пратки, съхранявайте идентификационните данни в сървърен мениджър на тайни, идентифицирайте всяко приложение, което ги използва, и тествайте заместващ ключ, преди да изведете стария от употреба. Ако вашият доставчик поддържа едновременно валидни идентификационни данни, мигрирайте потребителите постепенно и отнемете стария ключ едва след проверка. Ако заместващият ключ незабавно обезсилва съществуващия, планирайте координирано превключване с устойчиви опашки и проверки за възстановяване, вместо да предполагате нулево прекъсване.

Как да конфигурирате и ротирате API ключове за проследяване на пратки

Това ръководство е предназначено за разработчици и оперативни екипи, които поддържат интеграции за проследяване в платформи за електронна търговия, системи за управление на поръчки, складов софтуер и услуги за известяване на клиенти. Целта не е просто да се изпрати удостоверена заявка, а да се запазят регистрациите на пратките, актуализациите за проследяване и последващата обработка през цялата промяна.

Потвърдете как доставчикът обработва идентификационните данни

Преди да промените производствената конфигурация, изяснете жизнения цикъл на идентификационните данни при доставчика. Действие в таблото, обозначено като „генериране наново“, може да се държи различно от „създаване на друг ключ“. Не правете изводи за поведението само по етикета на бутона.

  • Формат на удостоверяване: Потвърдете необходимия хедър или друг механизъм за удостоверяване, версията на крайния пункт и свързването с акаунта.
  • Период на припокриване: Могат ли две идентификационни данни да останат валидни едновременно? Отменя ли генерирането на заместващ ключ незабавно предишния?
  • Разрешения: Определете дали ключовете имат отделни обхвати, ограничения на средата или контроли за достъп. Използвайте тези контроли, когато са налични; не предполагайте, че съществуват.
  • Отмяна: Потвърдете как се деактивира идентификационно средство и дали трябва да се отчете поведение при разпространение на промяната.
  • Оперативни ефекти: Установете дали квотите, регистрираните пратки и настройките на уебхуковете принадлежат на акаунта, приложението или отделния ключ.

За интеграция с 17TRACK започнете с официалната документация на Tracking API и продуктовата страница на Tracking API. Използвайте документацията, за да потвърдите договора за удостоверяване на вашата интеграция, и потвърдете поведението на жизнения цикъл на идентификационните данни чрез контролите на акаунта или чрез поддръжката, преди да планирате ротация. Процедурата по-долу е оперативен наръчник, а не твърдение, че 17TRACK предлага конкретен работен процес с два ключа или генериране наново.

Правило за избор: Използвайте внедряване с припокриващи се ключове само когато е потвърдена едновременната им валидност. В противен случай третирайте ротацията като координирана замяна на идентификационни данни. Стратегията за внедряване не може да създаде период на припокриване, който доставчикът не поддържа.

Конфигурирайте ключа еднократно, без да го разпространявате из системата

Поддържайте удостоверяването на сървъра

Съхранявайте производствените идентификационни данни в управлявано хранилище за тайни или в еквивалентна контролирана система. Нека приложението ги извлича чрез идентичността на работното натоварване, платформата за внедряване или друг одобрен механизъм. Ограничете достъпа за четене до работните натоварвания и операторите, които се нуждаят от него.

Не вграждайте ключа в JavaScript за браузъра, пакети на мобилни приложения, изходен код, образи на контейнери или споделени примери за конфигурация. Страница за проследяване, предназначена за клиенти, трябва да извиква вашия бекенд, който може да се удостоверява пред доставчика на проследяването, без да разкрива неговите идентификационни данни.

OWASP Secrets Management Cheat Sheet препоръчва централизирано управление на тайни, контролиран достъп, одит и управление на жизнения цикъл. Неговият REST Security Cheat Sheet също препоръчва API ключовете да не се поставят в URL адреси, където регистрирането и друга обработка могат да ги разкрият. Следвайте документирания метод за удостоверяване на доставчика и премахвайте стойностите за удостоверяване от журналите на заявките и диагностичните експорти.

Разделяйте средите и идентифицирайте внедрената версия

Използвайте отделни идентификационни данни за разработка, тестова и производствена среда, когато доставчикът ги поддържа. Когато отделни идентификационни данни или акаунти не са налични, документирайте ограничението и не допускайте непроизводствени задачи да извършват неконтролирани записи в производствената среда.

Дайте на тайната логическа конфигурационна препратка, например SHIPMENT_TRACKING_API_KEY. Записвайте отделно версията на мениджъра на тайни или несекретен етикет за внедряване. Този етикет позволява на операторите да отговорят на въпроса „Коя версия използва този работник?“, без да проверяват или регистрират самите идентификационни данни.

Определете изрично как приложенията получават актуализации. Процес, който чете променлива на средата при стартиране, обикновено се нуждае от рестартиране или повторно внедряване, за да получи променена стойност. Монтираният файл с тайна или търсенето по време на изпълнение имат различно поведение при опресняване. Актуализирането на хранилището за тайни не доказва, че всеки работещ процес е приел заместващата стойност.

Направете заявките възстановими преди ротацията

Запазвайте задачите за проследяване, преди да ги изпратите към доставчика. При регистрация на пратка съхранявайте вътрешен идентификатор на операцията, референция към пратката, състояние на обработката и история на повторните опити. Дръжте тези бизнес данни отделно от удостоверяването, така че поставените в опашка задачи да използват активния ключ при изпълнение.

Не сериализирайте API ключове в съобщенията на опашката. Това оставя забавените задачи свързани с остарели идентификационни данни и разпространява тайни в хранилището на опашката, опашките за мъртви съобщения и инструментите за отстраняване на грешки.

При операции за запис установете правилата на доставчика за обработка на дубликати, преди да активирате повторни опити. Изтичането на времето не доказва, че регистрацията е неуспешна: доставчикът може да е приел заявката преди прекъсването на връзката. Използвайте документиран механизъм за идемпотентност, ако съществува, или съгласувайте състоянието на пратката, преди да я изпратите отново.

Създайте инвентар на потребителите и базова линия за мониторинг

Най-често пропусканият потребител често не е основното приложение. Направете инвентар на планирани импорти, работници на опашки, безсървърни функции, административни скриптове, инструменти за поддръжка, внедрявания за аварийно възстановяване и услуги, които в момента са мащабирани до нула.

За всеки потребител запишете неговия собственик, среда, препратка към тайната, механизъм за опресняване, график за изпълнение и метод на внедряване. Идентифицирайте дълго работещите задачи, които могат да задържат идентификационни данни в паметта. Проверете и повторно използваемите HTTP клиенти, които могат да запазят стар хедър за удостоверяване след промени в конфигурацията.

Преди превключването установете базова линия за:

  • Неуспешни удостоверявания, групирани по услуга, среда, краен пункт и версия на внедряването.
  • Латентност на отговорите на доставчика, изтичания на времето, отговори за ограничаване на честотата и сървърни грешки.
  • Дълбочина на опашката, възраст на най-старата чакаща задача и обем на мъртвите съобщения.
  • Успешни регистрации на пратки и нерешени опити за регистрация.
  • Получаване и обработка на уебхукове, ако уебхуковете са част от интеграцията.

Разделяйте състоянието на интеграцията от движението на пратките. Пратка без ново събитие от превозвача не е непременно доказателство за грешка в API. По време на ротация успешните удостоверени заявки и здравите опашки за обработка са по-преки сигнали от броя пратки, чието състояние на доставка се е променило.

Ротирайте с припокриващи се ключове, когато това се поддържа

  1. Създайте заместващия ключ, без да отнемате активния. Проверете, че старите идентификационни данни остават валидни. Съхранете новите като отделна версия на тайната и ограничете достъпа по подходящ начин.
  2. Проверете заместващия ключ изолирано. Използвайте документирана операция с ниско въздействие в предназначената среда. Проверете както HTTP резултата, така и резултата на ниво приложение в тялото на отговора.
  3. Тествайте представителен работен процес. Проверете операциите, от които приложението действително се нуждае, а не само базова проверка на свързаността. Ако е необходима регистрация, използвайте разрешена тестова пратка и отчетете възможните ефекти върху квотите или таксуването.
  4. Внедрете в малка група потребители. Преместете една група работници или един екземпляр на приложението към заместващия ключ, след което проверете удостоверяването, резултатите от обработката и поведението на опашката.
  5. Разгърнете към всички останали потребители. Актуализирайте инвентара, когато всяка услуга презареди или рестартира. Включете планираните задачи, неактивните работни натоварвания и конфигурациите за възстановяване.
  6. Наблюдавайте подходящ период за проверка. Обхванете съответния живот на работниците, поведението на кеша на конфигурацията, забавянето при повторни опити и графика на задачите. Няма универсален период на изчакване, който да доказва приемането.
  7. Отнемете стария ключ и проверете отново. Следете за остарели потребители, след което изведете старите препратки към тайни от употреба съобразно изискванията за съхранение и реакция при инциденти.

Когато отчетите за използване на ключове от страна на доставчика не са налични, използвайте записите за внедряване и етикетите на версиите на тайните, докладвани от приложенията, за да проверите приемането. Това предоставя оперативно доказателство, но не заменя пълния инвентар на потребителите.

Обработвайте незабавната замяна като координирано превключване

Ако издаването на заместващ ключ незабавно обезсилва стария, непрекъснатото удостоверяване не може да бъде гарантирано чрез поетапно внедряване. Проектирайте прехода така, че работата да бъде безопасно отложена, а не загубена.

  1. Подгответе внедряването на приложението, препратката към тайната, операторския достъп и командите за възстановяване, преди да замените идентификационните данни.
  2. Поставете на пауза изходящите заявки за проследяване на контролирана граница, като продължите да приемате работата в устойчиво хранилище, когато е практично.
  3. Източете или отчетете заявките в процес на изпълнение. Маркирайте неясните резултати от операции за запис за съгласуване, вместо автоматично да ги третирате като неуспешни.
  4. Заменете идентификационните данни на доставчика, актуализирайте хранилището за тайни и опреснете всеки потребител.
  5. Изпълнете проверки на удостоверяването и работния процес, преди да освободите целия натрупан обем.
  6. Възобновете обработката постепенно, като спазвате ограниченията на честотата на доставчика и проверявате за дублирани регистрации.

Ако интеграцията не може да поставя работата на пауза, да я запазва или предвидимо да опреснява идентификационните данни, отстранете тези слабости преди рутинна ротация. При подозирано компрометиране обаче ограничаването на инцидента може да изисква незабавна отмяна, дори когато това причинява временно прекъсване.

Поддържайте API удостоверяването отделно от сигурността на уебхуковете

Изходният API ключ и входящата тайна за проверка на уебхукове служат за различни цели. Не предполагайте, че ротацията на единия променя другия или че и двата използват една и съща стойност. Следвайте независимо документираните от доставчика правила за удостоверяване и доставка на уебхукове.

По време на превключване на изходните идентификационни данни поддържайте приемането на уебхукове, освен ако няма отделна причина да го спрете. Проверявайте входящите съобщения според спецификацията на доставчика, приемайте ги устойчиво преди потвърждение, когато архитектурата позволява, и направете обработката устойчива на дублирани доставки.

Успешното удостоверено API извикване не доказва, че доставката или обработката на уебхукове е изправна. Проверявайте двата пътя отделно и избягвайте да променяте и двете идентификационни данни в една и съща операция по поддръжка, освен ако дизайнът на доставчика не го изисква.

Отстранявайте грешки, без да създавате лавина от повторни опити

СимптомПърви проверкиБезопасен отговор
Неуспешни удостоверявания след внедряванеВерсия на тайната, формат на хедера, среда, интервали, кеширани клиентиСпрете сляпото повторение; коригирайте конфигурацията и проверете една заявка.
Неуспешни са само някои работнициСтари процеси, пропуснати внедрявания, забавени задачи, остарели кешове на тайниОпреснете засегнатите потребители и сравнете етикетите на версиите.
Ограничения на честотата при възстановяванеСкорост на освобождаване на натрупаните задачи и обща конкурентностОграничете възстановяването и следвайте документираните указания за повторни опити.
Регистрацията изтичаДали доставчикът вече е приел операциятаСъгласувайте или използвайте документирана идемпотентност, преди да повторите.

HTTP 401 обикновено се отнася до липсващо или невалидно удостоверяване, докато 403 означава, че сървърът отказва заявката. Специфичните тела на отговорите от доставчика могат да обяснят причината по-точно. Не класифицирайте всяка грешка 403 като изтекъл ключ и не приемайте, че всяка неуспешна операция използва HTTP статус за грешка.

Използвайте ограничени повторни опити с обратно нарастване и случайно разпределение за подходящи временни грешки. Многократното изпращане на невалидни идентификационни данни няма да ги поправи. Уведомете оператор, запазете работата и предотвратете превръщането на конфигурационна грешка в неконтролирана лавина от заявки.

Определете връщането назад и завършването преди промяната

При ротация с припокриващи се ключове връщането назад може да означава временно връщане на потребителите към старите идентификационни данни, докато те все още са валидни и надеждни. След отмяната тази възможност вече не съществува. Ако старият ключ може да е компрометиран, не го възстановявайте само за да върнете наличността; издайте други идентификационни данни и продължете напред.

Завършете ротацията само когато всички потребители от инвентара използват заместващия ключ, грешките при удостоверяване са се върнали към очакваната базова линия, поставената в опашка работа се възстановява, неясните записи са съгласувани и обработката на уебхукове остава изправна. Запишете собственика, часа на завършване, внедрената версия на тайната и резултата от отмяната, без да записвате стойността на ключа.

За текуща API сигурност изберете график за ротация въз основа на организационната политика, риска от излагане на идентификационните данни и възможностите на доставчика. Извършвайте ротация извън този график при подозирано изтичане или неподходящ достъп. Повторяемата, тествана процедура е по-полезна от произволна честота, която интеграцията не може безопасно да поддържа.

ЧЗВ

Мога ли да ротирам API ключ за проследяване без прекъсване?

Потенциално да, ако доставчикът поддържа едновременни идентификационни данни и всеки потребител може да мигрира преди отмяната. Ако генерирането наново незабавно деактивира стария ключ, планирайте контролирано прекъсване на изходящите заявки. Устойчивите опашки могат да запазят работата през този интервал, но не правят връзката с доставчика постоянно налична.

Трябва ли задачите за пратки в опашката да съдържат API ключа?

Не. Съхранявайте операцията за пратката и нейните метаданни за обработка, след което разрешавайте активните идентификационни данни при изпълнение на работника. Това намалява излагането на тайни и предотвратява многократното използване на обезсилен ключ от забавени задачи.

Изтрива ли ротацията на ключа регистрираните пратки?

Не приемайте нито един от двата резултата. Потвърдете дали регистрираните пратки и свързаните настройки са прикачени към акаунта, приложението или идентификационните данни. Самото успешно удостоверяване не доказва, че заместващият ключ има достъп до очакваните записи за пратки.

Какво да направя, ако ключ се появи в хранилище или журнал?

Третирайте го като потенциално компрометиран. Отменете или заменете го незабавно, проверете записите за достъп и използване, когато са налични, и следвайте процеса си за реакция при инциденти. Премахването на видимата стойност не е достатъчно, защото копия могат да останат в историята, експортирани журнали или други системи.

Как да разбера дали стара планирана задача все още използва предишния ключ?

Проверете препратката към тайната, внедрената конфигурация и поведението при опресняване по време на изпълнение. Стартирайте я чрез контролирано изпълнение, когато е безопасно, или проверете внедряването ѝ преди следващото планирано стартиране. Тихото табло не доказва, че рядко използван потребител е мигрирал.

Източници

  • Документация на 17TRACK Tracking API — справочник на доставчика за конфигуриране на интеграцията и проверка на документирания договор за заявки.
  • 17TRACK Tracking API — официален продуктов контекст за интеграции за проследяване на пратки.
  • OWASP Secrets Management Cheat Sheet — указания за съхранение на тайни, контроли за достъп, одит, ротация и жизнен цикъл.
  • OWASP REST Security Cheat Sheet — обработка на API идентификационни данни и практики за сигурност на REST.
  • RFC 9110: HTTP Semantics — статус кодове, свързани с HTTP удостоверяването, и съображения за автоматично повторение на заявки.