Подписание JSON RSA-сертификатом

Способ защиты данных определяется настройками интеграции. Для уточнения информации по настройке Вашей интеграции или запроса для установления нужных настроек необходимо написать на почту alfa_api@alfabank.ru. При запросе установления настроек необходимо сообщить способ защиты (подпись или подпись с шифрованием), а также алгоритм (RSA или ГОСТ).

Внимание

Для подписания сообщения необходимо предварительно выпустить сертификат в УЦ Альфа-Банка, используя сервис "Электронная подпись". Если Вы уже выпускали сертификат - повторно выпускать не нужно.

Подписание JSON

Подготовить сообщение в формате JSON

Пример сообщения

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true,
  "iat": 1657882689,
  "exp": 1657886289
}

Подписать запрос

Тело запроса сформировать алгоритмом RS256 в виде компактной сериализации в соответствии с JSON Web Signature и подписать тело запроса закрытым ключом сертификата, выпущенным в сервисе "Электронная подпись".

Формат JWS

BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload) || '.' || BASE64URL(JWS Signature)

Структура тела запроса

•
Заголовок (Header)
- •
  
  "kid": "серийный номер сертификата"
- •
  
  "typ": "JWT"
- •
  
  "alg": "RS256"
•

JSON-документ (Payload)
•

Подпись запроса (Signature)

Пример JWS

eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxMDAwMzYzY2NiNzU5Y2I0NDg2MDc4NjVkMDAwMTAwMDM2M2NjIn0.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTY1Nzg4MjY4OSwiZXhwIjoxNjU3ODg2Mjg5fQ.ApKNzZ9kLMtBY3LzReSHQ7_AyDnzocGo9GTQFRmxTiRS7Lj7a55Kr4ziwZAmmwloF1063JJMOaU0lS947q6_hSct9pxzPdZ9tTmpIDGnQL-ks0oB7zz9vUSUd3G00UZXSYnuhI9BBRXvmmTaue5Y2j5zVZofLdO2dqPWCnsQULyLn_vYf8PeABhnAQ29z1Bq42uxfRFTM35cF40Tp4VBSqXDI1vxfleLusQlOZM-5Sk7O3Vy4Sf-UB03RrRGSBerZjdoMRh7dgEyoYAXS6c4MejCm2vmXKqSd7pu2V2TxOM9UTchkCS16DL-RIJtnfMjznmznU5SoMCpncvs6gRNeQ

Для тестовой проверки можно использовать https://token.dev/.

Выполнить запрос

Если добавить заголовки Content-Type: application/json + X-Request-ChannelSecurity: NO и отправить запрос, то подпись запроса не будет проверяться.

Если добавить заголовки Content-Type: application/jose + X-Request-ChannelSecurity: SIGNATURE и отправить запрос, то подпись запроса будет проверяться.

Если подпись валидна - запрос обрабатывается, если невалидна - Банк определяет запрос как неподлинный и возвращает ошибку.

Любые другие комбинации заголовков Content-Type + X-Request-ChannelSecurity приведут к ошибке.

Проверка подписи JSON

Получить ответ

Если добавить заголовки Accept: application/json + X-Response-ChannelSecurity: NO , то ответ не будет подписан.

Если добавить заголовки Accept: application/jose + X-Response-ChannelSecurity: SIGNATURE , то полученный ответ (в том числе ошибки) будет подписан и представлен в виде компактной сериализации.

Любые другие комбинации заголовков Accept + X-Response-ChannelSecurity приведут к ошибке.

Декодирование компактной сериализации JWS

JWS формируется из трёх составляющих и представляет структуру вида:

•

Base64URL(Header);
•

Base64URL(Payload);
•

Base64URL(Signature).

Пример JWS

Закодированный Раскодированный

Закодированный	Раскодированный
eyJraWQiOiJhbGZhLXRlc3Qtand0IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJkZWJpdFR1cm5vdmVyIjp7ImFtb3VudCI6MCwiY3VycmVuY3lOYW1lIjoiUlVSIn19.Y1NqCkRjjtJ2GrVsW-a627g6ObfpEaKw-H92QVgVWqL9i7d1SHyaXVghF4ZNZAlrFasKySnKYZf2Ik8zVIlLN7hqeYxoeTdE2OLbiQdvPrD-JnI2Qzh0K32vcImwgGcpq2lt_QKx1f_YmaSRhH9O3xZePVcmFGCqhl_0prQSwcR4g-yuhidvspaF48QlUHcEaZ65Cr8hdyc6g9HPZDy7ipU-zCAZGgK0enxfWn4Osyqch8RRDIsfLG7OJ4wbYwYB22LYO5UaxX8Zy_R2jSnKlNghxQwSqJGxizMFhFhdCrATGTo-ysI-7OtfremD8YNj7z_iYciyYbtAgV0ZodEvMA	header `{ "kid": "alfa-test-jwt", "typ": "JWT", "alg": "RS256" }` payload `{ "debitTurnover": { "amount": 0, "currencyName": "RUR" } }` verify signature `RSASHA256( base64UrlEncode(header) + "." + base64UrlEncode(payload), )`

eyJraWQiOiJhbGZhLXRlc3Qtand0IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJkZWJpdFR1cm5vdmVyIjp7ImFtb3VudCI6MCwiY3VycmVuY3lOYW1lIjoiUlVSIn19.Y1NqCkRjjtJ2GrVsW-a627g6ObfpEaKw-H92QVgVWqL9i7d1SHyaXVghF4ZNZAlrFasKySnKYZf2Ik8zVIlLN7hqeYxoeTdE2OLbiQdvPrD-JnI2Qzh0K32vcImwgGcpq2lt_QKx1f_YmaSRhH9O3xZePVcmFGCqhl_0prQSwcR4g-yuhidvspaF48QlUHcEaZ65Cr8hdyc6g9HPZDy7ipU-zCAZGgK0enxfWn4Osyqch8RRDIsfLG7OJ4wbYwYB22LYO5UaxX8Zy_R2jSnKlNghxQwSqJGxizMFhFhdCrATGTo-ysI-7OtfremD8YNj7z_iYciyYbtAgV0ZodEvMA

header

{
  "kid": "alfa-test-jwt",
  "typ": "JWT",
  "alg": "RS256"
}

payload

{
  "debitTurnover": {
    "amount": 0,
    "currencyName": "RUR"
  }
}

verify signature

RSASHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),

)

Проверить подпись ответа от Банка

Используйте открытый ключ сертификата для проверки подписи.

Проверьте подпись в соответствии с данными, указанными в Заголовке (Header). В поле kid заголовка JWS будет записан серийный номер сертификата Банка.

Обработать ответ в формате JSON

Пример ответа

{
  "debitTurnover": {
    "amount": 0,
    "currencyName": "RUR"
  }
}