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

Для предоставления возможности достоверно установить, что автором запроса является 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> "" <path_and_query> "" <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¹.

Важно

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

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

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

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

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

Footnotes

1. RFC 4648 | The Base16, Base32, and Base64 Data Encodings ↩ ↩² ↩³

2. RFC 2104 | HMAC: Keyed-Hashing for Message Authentication ↩

3. RFC 6234 | US Secure Hash Algorithms ↩

4. RFC 9110 | HTTP Semantics ↩

5. RFC 3230 | Instance Digests in HTTP ↩

6. RFC 9110 | HTTP Semantics ↩

7. RFC 7235 | Hypertext Transfer Protocol (HTTP/1.1): Authentication ↩