Request Signing
Request Signing проверяет API-запросы с помощью API-секрета. Ключ идентифицирует ваш доступ, а секрет создаёт подпись и никогда не должен передаваться в запросах.
Address Label API и Risk Score API используют отдельные ключи и секреты. Используйте учётные данные вызываемого сервиса.
Включение Request Signing
Полные процедуры настройки, ротации и отключения см. в API Security Settings.
Откройте Settings → APIs → API Keys, затем Security Settings нужного API.
Выберите Request Signing и создайте API-секрет. Скопируйте и безопасно сохраните его: он отображается только один раз.
Выберите, когда подписанные запросы станут обязательными, затем Save Changes:
In 24 hours: используйте переходный период для обновления и тестирования приложений. Новый секрет работает после сохранения; до указанного времени запросы без подписи принимаются с учётом других правил доступа.
Immediately: после сохранения каждый запрос должен иметь действительную подпись. Убедитесь, что приложения готовы.
Отправляйте подписанные запросы по инструкциям ниже. Обновите все приложения до времени, указанного в Security Settings.
Недействительная подпись отклоняется даже в переходный период. Если включён и IP Allowlist, IP источника должен быть разрешён, а подпись — действительна. Тесты используют реальные рабочие запросы и могут расходовать квоту; отдельного тестового секрета или эндпоинта проверки подписи нет.
Заголовки запроса
Api-Key
API-ключ соответствующего сервиса
X-Timestamp
Текущая метка времени Unix в секундах
X-Nonce
Новое случайное уникальное значение для каждого запроса, не более 256 байт
X-Signature
v1=, затем подпись HMAC-SHA256 в шестнадцатеричном виде строчными буквами
Метка времени должна отличаться от времени сервера не более чем на 5 минут. Синхронизируйте часы. При каждом повторе создавайте новые метку времени, nonce и подпись.
Используйте API-ключ и секрет только в серверном коде. Загружайте их из переменных окружения или менеджера секретов; никогда не коммитьте их и не включайте в сборки браузерных или мобильных приложений.
Используйте HTTPS с проверкой сертификатов. Request Signing аутентифицирует запросы, но не шифрует содержимое. Не помещайте учётные данные в URL или параметры запроса. Маскируйте ключи, секреты, заголовки подписи и чувствительные данные запросов/ответов в журналах, трассировках, снимках экрана и вложениях для поддержки.
Создание канонической строки
Соедините следующие шесть полей одним символом новой строки (\n). Не добавляйте завершающий перевод строки.
METHOD: HTTP-метод в верхнем регистре, например
GETилиPOST.PATH: полный путь URL с префиксом сервиса, без схемы, хоста и строки запроса. Например,
/address-compliance/api/v3/risk-score. Использование только/risk-scoreприведёт к ошибке проверки.SORTED_QUERY_STRING: строка запроса, нормализованная по правилам ниже. При отсутствии параметров используйте пустую строку.
BODY_SHA256: хеш SHA-256 точных байтов отправляемого тела в шестнадцатеричном виде строчными буквами. Для пустого тела хешируйте пустую последовательность байтов.
TIMESTAMP и NONCE: те же значения, что отправлены в заголовках.
Сериализуйте тело один раз, хешируйте эти байты и отправляйте их без изменений. Изменение пробелов JSON после подписи делает её недействительной.
Нормализация параметров запроса
Разделите исходную строку по
&, затем каждую пару по первому=. Отсутствующее значение считайте пустой строкой.Декодируйте ключи и значения.
Сортируйте по декодированному ключу, затем значению в порядке байтов UTF-8. Сохраняйте повторяющиеся ключи.
Примените процентное кодирование RFC 3986 к каждому ключу и значению. Не экранируйте только
A–Z,a–z,0–9,-,_,.и~. Пробел кодируйте как%20, буквальный плюс — как%2B.Соедините пары
key=valueчерез&, без начального?.
Пример:
Используйте UTF-8. Избегайте исходного + в значениях; используйте %20 для пробелов и %2B для плюса. flag и flag= нормализуются в flag=.
Вычисление подписи
Используйте байты UTF-8 отображаемого значения секрета. Не декодируйте его как hex или Base64.
Пример Python
Пример вызывает эндпоинт поддерживаемых цепей Risk Score API. Задайте MS_API_KEY и MS_API_SECRET своими данными Risk Score. Используется HTTPS-эндпоинт рабочей среды. Для разрешённых тестовых сред используйте отдельные данные; не отправляйте рабочие учётные данные недоверенным хостам.
Для JSON POST сериализуйте данные в байты UTF-8, используйте их для хеша тела, затем передайте те же байты в Request как data=body. Установите Content-Type: application/json.
Параметры запросов см. в APIs.
Пример Node.js
Требуется Node.js 18 или новее. Используйте те же переменные Risk Score, что в примере Python. Подписываются точные байты UTF-8, которые отправляются.
Оба примера отклоняют перенаправления. Не пересылайте учётные данные и заголовки подписи на адрес перенаправления. Проверьте ожидаемые HTTPS-хост и путь перед созданием и подписанием нового запроса. HTTP-статус сам по себе не означает успех операции; проверяйте бизнес-код JSON согласно разделу Формат ответа.
Устранение неполадок
401001
Request signing is not configured
Настройте подпись и убедитесь, что для этого API-сервиса доступен секрет.
401002
Invalid request signature
Проверьте данные сервиса, полноту заголовков, полный путь, метод, нормализованный запрос, точные байты тела и длину nonce (до 256 байт).
401003
Invalid request timestamp
Используйте секунды Unix и синхронизируйте часы; разница с сервером не должна превышать 5 минут.
401004
Request has already been used
При каждом повторе создавайте новый nonce и подпись.
403002
Request IP is not allowed
Сверьте публичный исходящий IP приложения с активным списком разрешённых адресов.
500003
Request signing verification is unavailable
Повторите с ограниченной задержкой и новым nonce/подписью. Если проблема сохраняется, обратитесь в поддержку.
Полный список и обработку HTTP см. в разделе Формат ответа.
Успешный повтор может оплачиваться снова: nonce предотвращает воспроизведение, а не повторное списание. Любой непустой заголовок подписи запускает проверку даже при отключённой подписи.
Ротация секрета
Создайте новый секрет в Security Settings, безопасно скопируйте его и выберите срок старого. Для применения ротации выберите Save Changes; создание несохранённого секрета не заменяет текущий.
In 24 hours: после сохранения оба секрета работают в переходный период. Обновите все приложения до истечения старого секрета.
Immediately: старый секрет перестаёт работать после сохранения. Используйте этот вариант при подозрении на раскрытие.
API-ключ не меняется. Пока идёт ротация, новую начать нельзя. Дождитесь истечения старого секрета или отзовите его досрочно. Досрочный отзыв немедленно отклоняет запросы, подписанные этим секретом.
Последнее обновление