Аутентификация запросов вебхуков

Для предоставления возможности достоверно установить, что автором запроса является ATI.SU, реализован механизм подписывания запросов, который позволяет проверить их подлинность (аутентифицировать).

Аутентификация

Аутентификация запросов проводится по следующему принципу: необходимо создать строку подписания, применить к ней алгоритм HMAC с использованием хеш-функции SHA-256 и сравнить результат в кодировке base64¹ с параметром аутентификации Signature. В случае, если значение параметра совпадает с полученным значением, запрос является подлинным.

Создание подписи

Подпись создается посредством алгоритма HMAC² с использованием хеш-функции SHA-256³ на основе:

ключа вебхука, генерируемого на стороне ATI.SU, узнать который можно с помощью GET-метода проверки состояния вебхука (поле hook.key);
строки подписания, сформированной из содержимого запроса.

Пример строки подписания

POST
/webhook?topic=orders
Thu, 01 Jan 1970 00:00:00 GMT;sha-256=SypZnuCTiysyLuUz9DOYckaU/vf0zrzdxKL1j/sHemg=;example.org:443

Грамматика строки подписания

<signing_string> ::= <method> "\n" <path_and_query> "\n" <signed_headers_values>

<method> ::= "GET" | "POST"

<signed_headers_values> ::= (<header_value> | ((<header_value> ";")+ <header_value>))

<method> — HTTP метод запроса;
<path_and_query> — путь запроса вместе с параметрами;
<signed_headers_values> – список значений заголовков через точку с запятой;
<header_value> — значение заголовка.

Для создания строки подписания всегда используются значения заголовков Date⁴, Digest⁵ и Host⁶. Таким образом, подпись различается в зависимости от времени её создания, содержимого запроса и от цели запроса. В совокупности с использованием протокола HTTPS это позволяет защитить вебхук от перехвата и модификации сообщений.

Важно!

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

Заголовок Authorization

Все подписываемые запросы имеют заголовок Authorization⁷, который содержит информацию об используемом алгоритме создания подписи, ключе, заголовках запроса, принимающих участие в подписании, и саму подпись в кодировке base64¹.

Пример заголовка Authorization

Authorization: HMAC-SHA-256
Credential=6447f577905114d5b9b2c618&SignedHeaders=Date;Digest;Host&Signature=V8CpKji2ysF5h5VVerhcq/GMQGxoHwf0EcGiDIL41e0=

Грамматика заголовка Authorization

<authorization> ::= <scheme> " " <parameters>

<scheme> ::= "HMAC-SHA-256"

<parameters> ::= <credential> "&" <signed_headers> "&" <signature>

<credential> ::= "Credential=" <key_id> 
<signed_headers> ::= "SignedHeaders=" (<header> | ((<header> ";")+ <header>))
<signature> ::= "Signature=" <base64_digest>

<scheme> — схема аутентификации;
<parameters> — параметры аутентификации;
<key_id> — идентификатор ключа вебхука;
<header> — название заголовка, принимающего участие в подписании;
<base64_digest> — подпись, представляет собой 264-битную строку в кодировке base64¹.

Важно!

Идентификатор ключа на данный момент совпадает с идентификатором вебхука, что в дальнейшем может быть изменено, поэтому он не должен использоваться для выявления принадлежности сообщения конкретному вебхуку.

Ротация ключей

Отправка сообщения, оповещающего о ротации, пока не предусмотрена, поэтому в случае если подпись не совпадает, следует запросить актуальный ключ. В том случае, если полученный ключ совпадает с текущим, запрос является поддельным.

Остались вопросы?

Напишите нам: Контакты.