Access Token, Refresh Token

Ресурс /v2/oauth/token

Ресурс /v2/oauth/token используется для получения Access Token.

Перед использованием ресурса /v2/oauth/token необходимо получить сертификаты и настроить TLS соединение.

Host и полный url для вызова ресурса на тестовом и промышленном контурах см. в разделе URL для вызова API СберБизнес ID.

Ресурс /v2/oauth/token позволяет получать Access Token путем обмена кода авторизации (см. получение кода авторизации в разделе Authorization code или токена обмена (Refresh Token), который предоставляется вместе с Access Token.

Направления взаимодействия, описанные в разделе, выделены на схеме красным.

Схема

При запросе ресурса /v2/oauth/token используются параметры, полученные при регистрации приложения Партнера.

Параметры запроса Access Token

Параметры, которые необходимо передавать при вызове ресурса /v2/oauth/token при запросе Access Token.

Параметр Описание
Заголовок
Content-Type Обязательный параметр. Должен содержать значение application/x-www-form-urlencoded
Accept Необязательный параметр.
Если ответ не требуется в зашифрованном виде, то может быть не указан или передан со значением application/json.
Если необходимо получить ответ на запрос токена в зашифрованном виде, то необходимо передать параметр со значением application/jose.
Параметры запроса (entity body)
grant_type Обязательный параметр. Значение должно быть authorization_code
code Обязательный параметр. В параметре необходимо использовать значение code полученное Приложением партнера на адрес redirect_uri. Каждый code может быть использован только один раз. Например, если при запросе access_token по коду авторизации была допущена ошибка в каком либо из параметров и передано значение code, то повторное использование данного значения code уже будет недопустимо.
client_id Обязательный параметр. Уникальный идентификатор Приложения Партнера, полученный при регистрации приложения.
redirect_uri Обязательный параметр.
Должен в точности совпадать со значением переданным ранее при вызове ресурса /v2/oauth/authorize.
Пример:
Если в redirect_uri было указано https://example.ru/auth/login/register, то точно такое же значение должно быть указано при запросе /v2/oauth/token, даже если зарегистрирован redirect_uri = https://example.ru/auth/login
client_secret Обязательный параметр. Секрет Приложения Партнера, полученный при регистрации приложения.
code_verifier Необязательный параметр. Параметр в соответствии с надстройкой PKCE над протоколом OAuth 2.0. Раскодированное значение code_challenge переданное ранее при вызове ресурса /authorize. См. правила формирования параметра в PKCE.
Становится обязательным, если при регистрации приложения настройка PKCE была подключена или при вызове ресурса /authorize параметр code_challenge был передан.
Вызов ресурса должен осуществляться только с использованием экранирования специальных символов.

Пример запроса без экранирования

POST /ic/sso/api/v2/oauth/token
Host: edupirfintech.sberbank.ru:9443
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=authorization_code&code=f710576d-7263-4ec6-a01b-8404aca2850d-1&client_id=999999&client_secret=da658d9360604e41a5bac9611d0f1620&redirect_uri=https://example.ru/login?return_to=settings

Пример запроса с экранированием

POST /ic/sso/api/v2/oauth/token
Host: edupirfintech.sberbank.ru:9443
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=authorization_code&code=f710576d-7263-4ec6-a01b-8404aca2850d-1&client_id=999999&client_secret=da658d9360604e41a5bac9611d0f1620&redirect_uri=https%3A%2F%2Fexample.ru%2Flogin%3Freturn_to%3Dsettings

Содержание ответа на запрос Access Token

В теле ответа на запрос Access Token будут содержаться следующие параметры:

Параметр Описание
Заголовок ответа
Content-Type Если в запросе:
- не был передан заголовок Accept или передан в значении application/json, то в ответе параметр будет содержать значение application/json
- был передан заголовок Accept в значении application/jose, то в ответе будет указано application/jose и полученное тело ответа потребуется расшифровать.
Более подробно о расшифровке ответа, см. в разделе Access Token, Refresh Token
Параметры ответа
access_token Авторизационный токен
token_type Тип токена. Всегда возвращается значение «Bearer»
expires_in Срок жизни токена в секундах.
Срок жизни access_token составляет 60 минут.
refresh_token Токен обновления. Используется для обновления Access Token. Подробнее про применение значения refresh_token см. в Параметры запроса на обновление Access Token
Срок жизни refresh_token составляет 180 дней.
scope Область сведений (разрешения), до которых разрешен доступ Приложению Партнера.
id_token Закодированный в Base64URL набор атрибутов клиента, необходимых для идентификации пользователя. Атрибуты разделены символами «.», каждый необходимо декодировать отдельно. Подробнее о декодировании и параметрах id_token см. в ID Token

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

HTTP/1.1 200 OK
Content-Type: application/json
{
"scope": "openid PAYROLL name",
"access_token": "c76fb018-27c9-43f7-a751-62646eda7e1a-1",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "03e0be32-e72e-47ec-b740-a00b333a8ac4-1",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJnb3N0MzQuMTAtMjAxMiJ9.eyJzdWIiOiI1OGMzMzE2ZTBmMDgyYzk1ZjZlZDE1ZGZlNzdmNzZkOTljNjI2ZGVhMmQ4ZTJmZWYyNDcyMzM5Y2QyNzMzNWQzIiwiYXVkIjoiNjMyMjk0IiwiYWNyIjoibG9hLTMiLCJhenAiOiI2MzIyOTQiLCJhdXRoX3RpbWUiOjE2MzE1MzQ1NjIsImFtciI6Intwd2QsIG1jYSwgbWZhLCBvdHAsIHNtc30iLCJpc3MiOiJodHRwOi8vc2J0LW9hZnMtNjM4OjkwODAvaWNkayIsImV4cCI6MTYzMTUzNDkxMSwiaWF0IjoxNjMxNTM0NjExLCJub25jZSI6IjdiZTY2YWM5LWQwN2MtNDk2Ny1hZGVkLWNhMjcwYTI3ZTllOCJ9.B46H281g1HKLnTOxhitBI25zgmEseNyGLp1hFQGPWnZWlv5xAjJhAJSQPTbiseLmX_MVKhaT9Dq3QF2F0fa7Vg"
}

Параметры запроса на обновление Access Token

При обмене кода авторизации на токен, СберБизнес ID возвращает пару access_token и refresh_token.

Полученный refresh_token применяется для обновления access_token после истечения срока его действия или в случае его компрометации.

При использовании refresh_token формируется новая пара access_token и refresh_token.

При этом использованный refresh_token переводится в статус резервного на 2 часа с момента выпуска новой пары ключей (access_token/refresh_token).

Если по каким-то причинам сформированная пара не была получена от банка, то рекомендуется повторно отправить запрос на актуализацию ключей в течение 1 часа от момента отправки первой попытки, используя тот же refresh_token.

Для последующих обновлений ключей доступа необходимо использовать refresh_token из новой пары ключей (access_token/refresh_token).

Схема

Для обновления access_token по refresh_token, необходимо вызывать ресурс /v2/oauth/token со следующими параметрами:

Параметр Описание
Заголовок
Content-Type Обязательный параметр. Должен содержать значение application/x-www-form-urlencoded
Accept Необязательный параметр.
Если ответ не требуется в зашифрованном виде, то может быть не указан или передан со значением application/json.
Если необходимо получить ответ на запрос токена в зашифрованном виде, то необходимо передать параметр со значением application/jose.
Параметры запроса (entity body)
grant_type Обязательный параметр. Значение должно быть refresh_token
client_id Обязательный параметр. Уникальный идентификатор Приложения Партнера, полученный при регистрации приложения.
refresh_token Обязательный параметр. Значение refresh_token полученное при обмене кода авторизации на access_token
client_secret Обязательный параметр. Секрет Приложения Партнера, полученный при регистрации приложения.

Пример запроса

POST /ic/sso/api/v2/oauth/token
Host: edupirfintech.sberbank.ru:9443
grant_type=refresh_token
&code=03e0be32-e72e-47ec-b740-a00b333a8ac4-1
&client_id=999999
&client_secret=da658d9360604e41a5bac9611d0f1620

Содержание ответа на запрос обновления Access Token

Параметры ответа на запрос access_token по refresh_token аналогичны ответу на запрос Access Token по коду авторизации за исключением отсутствия параметра id_token.

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

HTTP/1.1 200 OK
Content-Type: application/json
{
"scope": "openid PAYROLL name",
"access_token": "c76fb018-27c9-43f7-a751-62646eda7e1a-1",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "03e0be32-e72e-47ec-b740-a00b333a8ac4-1"
}

Коды возврата

В случае возникновения ошибок при вызове ресурса /v2/oauth/token в ответ будут возвращены следующие параметры:

Параметр Описание
error Код возникшей ошибки
error_description Описание возникшей ошибки

Перечень исключений, которые могут быть возвращены при вызове ресурса /v2/oauth/token:

error error_description Описание причины
SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTION В соответствии с текущими настройками сервиса с clientId={0} необходимо запрашивать ответ в формате JSON Для Приложения Партнера установлен запрет на прием запросов с http-заголовком Accept со значением application/jose
SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTION В соответствии с текущими настройками сервиса с clientId={0} необходимо запрашивать ответ в формате JWE Compact Serialization Для Приложения Партнера установлен запрет на прием запросов с http-заголовком Accept со значением application/json
invalid_grant Missing grant_type parameter value Не заполнен обязательный параметр grant_type
invalid_grant One of the params (code, refresh_token) is required at request Не заполнен один из обязательных параметров code или refresh_token
unsupported_grant_type Grant type '{0}' is not supported" В параметре grant_type указано значение отличное от authorization_code или refresh_token
invalid_request Missing parameters: code В параметре grant_type указано значение authorization_code, но отсутствует значение в параметре code
invalid_grant Failed to extract shoulder ID from {0} В параметре code указано некорректное значение
invalid_request Missing parameters: refresh_token В параметре grant_type указано значение refresh_token, но отсутствует значение в параметре refresh_token
invalid_grant Failed to extract shoulder ID from {0} В параметре refresh_token указано некорректное значение
unauthorized_client Unknown client_id = '{0}' Переданный client_id не зарегистрирован
invalid_grant Unknown code = '{0}' Не найдено переданное значение code. Например, потому что срок действия кода истек или по данному коду уже осуществлялся вызов.
invalid_grant Unknown refresh token = '{0}' Не найдено переданное значение refresh_token. Например, потому что срок действия токена истек или по данному токену уже был осуществлен обмен на access_token.
invalid_grant Ext service for authz code '{0}' is blocked Приложение Партнера зарегистрированное по указанному client_id - заблокировано.
unauthorized_client Client '{0}' is blocked Приложение Партнера зарегистрированное по указанному client_id - заблокировано.
invalid_grant Invalid credentials for authz code '{0}' При запросе access_token по коду авторизации указан неверный client_secret`
invalid_grant Invalid credentials for refresh_token '{0}' При запросе access_token по refresh_token указан неверный client_secret
invalid_request Missing parameters: {0} Отсутствует параметр redirect_uri
invalid_grant Redirect uri '{0}' is invalid Переданный параметр redirect_uri не совпадает со значением полученным ранее при запросе кода авторизации
invalid_request client secret expired Истек срок действия client_secret
invalid_request Code verifier required При запросе кода авторизации был указан code_challenge, но в параметрах запроса токена отсутствует параметр code_verifier
invalid_request Invalid code verifier Значение code_verifier не отвечает параметрам протокола PKCE
invalid_grant Failed to verify code verifier Хешированное значение code_challenge, полученное в запросе /authorize не совпадает со значением полученным в параметре code_verifier

Также могут быть получены следующие параметры в ответе при обращении к серверу:

Параметр Описание
errorCode Код возникшей ошибки
errorMsg Описание возникшей ошибки

Данный тип параметров возвращается, если на сервере возникли следующие исключения:

http-code errorCode/errorMsg Описание причины
403 requestForbidden

The server configuration prohibits executing a request to the endpoint {0}
На данном сервере запрещен вызов указанного ресурса. Например, вызов ресурса /v2/oauth/token осуществляется на домен https://sbi.sberbank.ru:9443, а должен осуществляться на домен https://fintech.sberbank.ru:9443
403 certificateNotFound

The certificate was not whitelisted for client_id={0}
Не пройдена проверка сертификата по белому списку

ID Token

ID Token:

  • Является основным расширением, которое спецификация OpenID Connect накладывает на протокол OAuth 2.0 и добавляется в ответ на запрос Access Token, если в состав scope включено значение openid;
  • Является токеном безопасности и содержит информацию об аутентификации пользователя с использованием СбреБизнес ID для входа в Приложение Партнера;
  • Представляет собой JSON Web Token (JWT).

В соответствии со спецификации JSON Web Token (JWT) ID Token представлен структурой вида:

  • Алгоритм подписи и тип токена (Header);
  • Полезная нагрузка (Payload);
  • Электронная подпись (Signature).

Каждая часть ответа, разделенная точкой должна декодироваться отдельно. Для декодирования ID Token следует воспользоваться алгоритмом Base64URL Encoding. Для проверки подписи в поле id_token на стороне Приложения Партнера, необходимо вычислить подпись публичным ключом Банка, декодировав блок Header и Payload по Base64URL (содержимое между двумя точками). Далее необходимо сравнить полученное значение c блоком Электронная подпись (содержимое после второй точки), декодированным по Base64URL.

Пример ID Token

id_token Описание

        
eyJ0eXAiOiJKV1QiLCJhbGciOiJ
nb3N0MzQuMTAtMjAxMiJ9.eyJzd
WIiOiJmYWQ0YjYzMThiNjYyZDIx
YjJlMTk2ZWJlYjBmMDhYWI3NDJj
NGYzYmFhMmUxZTE1ZGNhNjkwZmM
YjJkYTkwIiwiYXVkIjoiMTExMjk
2IiwiYWNyIjoibG9hLTMiLCJhen
AiOiIxMTEyOTYiLCJhdXRoX3Rpb
WUiOjE2MzExNjcxNjgsImFtciI6
Intwd2QsIG1jYSwgbWZhLCBvdHA
sIHNtc30iLCJpc3MiOiJodHRwO
8vc2J0LW9hZnMtNjM4OjkwODAva
WNkayIsImV4cCI6MTYzMTE2NzUy
NywiaWF0IjoxNjMxMTY3MjI3LCJ
b25jZSI6IjdiZTY2YWM5LWQwN2M
tNDk2Ny1hZGVkLWNhMjcwYTI3ZT
llOCJ9.NnGurMyyyket3i9TkyRx
LRbllZTxfqNJfrDhNXy7N_B5BbE
fj3kdxKxaDMChug2MXflrbzn7WY
SbSPV6H_Kjug
        

Заголовок. Алгоритм и тип токена

            
{
"typ": "JWT",
"alg": "gost34.10-2012"
}]
            
            

Полезная нагрузка

            
{
"sub": "fad4b6318b662d21b2e196ebeb0f02aab742c4f3baa2e1e15dca690fc3b2da90",
"aud": "111296",
"acr": "loa-3",
"azp": "111296",
"auth_time": 1631167168,
"amr": "{pwd, mca, mfa, otp, sms}",
"iss": "http://sbt-oafs-638:9080/icdk",
"exp": 1631167527,
"iat": 1631167227,
"nonce": "7be66ac9-d07c-4967-aded-ca270a27e9e8"
}
            
            

Электронная подпись

            
<Массив байт электронной подписи>
            
            

По умолчанию в ID Token включены следующие параметры:

Параметр Описание
Заголовок (Header)
typ Тип токена
alg Алгоритм шифрования
Полезная нагрузка (Payload)
acr Уровень аутентификации пользователя:
- acr=loa-2 (пользователь аутентифицируется с помощью устройства защиты)
- acr=loa-3 (пользователь использует подтверждение по одноразовому SMS-паролю для аутентификации)
amr Методы аутентификации:
- amr=pwd — пользователь аутентифицируется с помощью устройства защиты;
- amr= {pwd, mca, mfa, otp, sms} — пользователь использует подтверждение по одноразовому SMS-паролю для аутентификации
aud Идентификатор Приложения Партнера, для которого сформирован ID Token
auth_time Время аутентификации пользователя в СберБизнес ID. Формат поля Unix time
azp Идентификатор Приложения Партнера, для которого сформирован ID Token
exp Время, после которого ID Token не принимается для обработки. Формат поля Unix time
iat Время формирования ID Token. Формат поля Unix time
iss URL сервиса, сформировавшего ID Token
nonce Значение параметра nonce, полученного при запросе авторизации
sub Уникальный идентификатор пользователя
Электронная подпись (Signature)
Массив байт электронной подписи Проверка электронной подписи, полученной в ID Token (содержимое ответа ID Tokena после второй точки), выполняется, используя алгоритм, указанный в параметре заголовка JWT alg. Приложению Партнера необходимо проверить подпись сертификатом Банка

Если при формировании ID Token, какой-либо параметр не может быть заполнен, то такой параметр не будет включен в ответ.

Получение Access Token в зашифрованном виде

Для получения значений в зашифрованном виде, необходимо согласовать настройки со своим менеджером. Выпустить сертификаты и зарегистрировать на токене (РутокенTLS и VPNKeyTLS). Предоставить в Банк следующую информацию: Алиас криптопрофиля и Серийный номер TLS-сертификата, который будет использоваться при шифровании.

Для того, чтобы на запрос токена доступа получить ответ в зашифрованном виде необходимо в запросе передать http-заголовок Accept со значением application/jose, тогда сформированный не ошибочный ответ (код ответа 200) будет представлен в JOSE в представлении JWE Compact Serialization. При этом в ответе также будет содержаться http-заголовок Content-Type со значением application/jose.

JWE Compact Serialization состоит из 5 частей, разделитель между частями - символ '.'

В нашем случае структура JWE Compact Serialization будет иметь следующий вид:

BASE64URL(UTF8(JWE Protected Header)) || '.' '.' '.' || BASE64URL(JWE Ciphertext) || '.'

Защищенный заголовок (Protected Header) будет иметь следующий вид:

{
"typ": "JOSE",
"enc": "gost28147-89",
"kid": "UUID TLS-сертификата, который был использован при шифровании"
}

Параметр enc содержит алгоритм, по которому был зашифрован ответ, в нашем случае gost28147-89.

Пример зашифрованного Access Token и расшифроки его заголовка

Пример JWE Compact Serialization

eyJ0eXAiOiJKT1NFIiwiZW5jIjoiZ29zdDI4MTQ3LTg5Iiwia2lkIjoiNzc4NkE0QkJCNTg4QjZBQTQ4MTEifQ...MIIIWAYJKoZIhvcNAQcDoIIISTCCCEUCAQCgggSfoIIEmzCCBJcwggRGoAMCAQICCneGpLu1iLaqSBEwCAYGKoUDAgIDMIIBEzELMAkGA1UEBhMCUlUxLzAtBgNVBAoMJtCe0JDQniAi0KHQsdC10YDQsdCw0L3QuiDQoNC-0YHRgdC40LgiMU0wSwYDVQQLDETQo9C00L7RgdGC0L7QstC10YDRj9GO0YnQuNC5INGG0LXQvdGC0YAg0KHQkSDQoNCkICjQotC10YHRgtC-0LLRi9C5KTE-MDwGA1UEAww10JvQsNCy0YDQuNC90KHQki3QotC10YHRgtC-0LLQsNGPINC_0LXRh9Cw0YLRjC3Qo9CmLTkxITAfBgNVBCEMGNCi0LXRgdGC0LjRgNGD0Y7RidC40LkgUTEhMB8GCSqGSIb3DQEJARYSY2FzYnJmQHNiZXJiYW5rLnJ1MB4XDTE5MDkxMzA5MTAwMFoXDTIyMDkxMzA5MTE0NlowggE0MS8wLQYDVQQDDCbQn9C10YLRgCDQn9C10YLRgNC-INCf0LXRgtGA0L7QstC40YfQqjERMA8GA1UEBAwI0J_QtdGC0YAxJjAkBgNVBCoMHdCf0LXRgtGA0L4g0J_QtdGC0YDQvtCy0LjRh9CqMQswCQYDVQQGEwJSVTFzMHEGA1UECgxq0J7QsdGJ0LXRgdGC0LLQviDRgSDQvtCz0YDQsNC90LjRh9C10L3QvdC-0Lkg0L7RgtCy0LXRgtGB0YLQstC10L3QvdC-0YHRgtGM0Y4gItCc0LDRiNCwINC4INCc0LXQtNCy0LXQtNGMIjEOMAwGA1UECwwFcWV3cWUxEjAQBgNVBCEMCUJvb3Nzc3NzczEgMB4GCSqGSIb3DQEJARYRcXdlcXdlcUBtYXJycnIucnIwYzAcBgYqhQMCAhMwEgYHKoUDAgIjAgYHKoUDAgIeAQNDAARArVLHRJLdJl0SnsxGemCQ86Q8_9ZVBpV3KWRHLCLBXSWGGuqF5JoSBtWtNhbuA26bBRg2V7pPhQ0Rdc7oIPa4DaOCAVMwggFPMGAGBSqFA2RvBFcMVdCh0YDQtdC00YHRgtCy0L4g0Y3Qu9C10LrRgtGA0L7QvdC90L7QuSDQv9C-0LTQv9C40YHQuCAi0KDRg9GC0L7QutC10L0g0K3QptCfIDIuMCDQoCIwEwYDVR0gBAwwCjAIBgYqhQNkcQEwJgYHKoUDA3sDAQQbDBlBMDAyQVIyMHTQn9C10YLRgCDQny4g0J8uMBQGByqFAwN7AwQECQYHKoUDA3sFBDAOBgNVHQ8BAf8EBAMCBPAwFAYJYIZIAYb4QgEBAQH_BAQDAgeAMBYGA1UdJQEB_wQMMAoGCCsGAQUFBwMCMBoGByqFAwN7AwUEDwwNVExTMDk4MjYwNzQzMDAdBgNVHQ4EFgQU5rnb2j7CXqcq3qijl32MWcYW_4owHwYDVR0jBBgwFoAUm1I0EBH4CDR3jgrM1iYY3L4YOZwwCAYGKoUDAgIDA0EAT_HWRP_z_gCdULkErGU064jF5vLjJNfJMXlRnczgxVV6upiaymDBhzLReusDu_GWhHN60R5nXFm198nL2FeJzTGB5DCB4QIBAoAU5rnb2j7CXqcq3qijl32MWcYW_4owHAYGKoUDAgITMBIGByqFAwICIwIGByqFAwICHgEEgacwgaQwKAQgN2n6mDPKLkCbYvWnjfEOzrvMkQ4Rb4eDzbXzO6O5M4UEBAcGfKigeAYHKoUDAgIfAaBjMBwGBiqFAwICEzASBgcqhQMCAiMCBgcqhQMCAh4BA0MABEBPEe-IR0GYa26Z77B9FzIKxo3euVtYBELWZb0vkz7yfd6oyGSaN3j83nycBsTu8ZOPzocWgHT9liOIuTXPcZF8BAivndzmaFRyBzCCArQGCSqGSIb3DQEHATAdBgYqhQMCAhUwEwQIzSoQ3lW4vDkGByqFAwICHwGAggKGOGS_PZ95Iiw7m9uK1VhOn8JC5G2s6bTsrdna9UyNubpVqmfaViS6jqiDNfkQdL4MQSIXuRwGoi7BEQg1tq9kTy_gK9IFiaRiVWzfQ9dunCMibmkK8fntSMez-vUb3Ur_86Fr0V5DO0YisSyMfGf4G-PiDHgEX5OrhvWD6MhS2XKxPFdhxsDjdN6F_B49kcVjKIJGpsKM9RKqc7WNTPfHlHteAhpKJaPKPoFzmRgVziTMRfrILY97T63swAdLgWDRNaVoaZzn4Dk_9-tFPACwLSo8pi-W4GjcqvW16Q-k9Kj-Gqa_mtwyJeZXghDmxslEiDUcNwXnoI6f6BHzxslFTdMklpqTItRKr-fWzc0n5i7Ed3naIggOmzhKjqRWp8Kt-aD1HkeR-e0axvUMqDaAEUgLceuOO1pzGtxK64tEO4YZilvlcaEgg9njNG1gLx6zh4Fh4CirSTUWg5dasAxhV80FdZTC75p5UL_FPULQ0z02auJ0rNw9jan2VISdR6cSKpK2vCTjPMw50TQF28-PSP1xBjeNF11BaGcEQS-bJnXDGycKLlg0Q1Pf9NsEfScIfqTrpB9gAtoPnEos6sX6cQNIGYEtXgNz7Z73ycnXtgD9P0TzDieJC-T1E4Hn6jonN60WskteZzZ0afk3TgH2x6l-Z0bpeQLndnQF0zWXT3WxpSsG4ad2cGcwRiVplFXctn-mBQwQ9vUTrLQJc6Lv6qEnTd4yVVF8pj9F1mj0I57x62tkqDH9-bgaMxFrlN8CSJ65TgoTwh442bxjC2mDmEdVvjirq76gC6D6SLmWfvuUf0wP06twKI1bFodSWHJlvpfgPqnRu-LN-rOZQBGuyMKO5dXFIg.

Пример декодированного (из BASE64URL) Protected Header

{
"typ": "JOSE",
"enc": "gost28147-89",
"kid": "7786A4BBB588B6AA4811"
}

Описание алгоритма расшифрования

Для того, чтобы расшифровать JWE Ciphertext необходимо выполнить следующие действия на VPNKeyTLS:

  • Проинициализировать устройство (INIT_DECIPHER_ID) путем передачи части с заголовком.
  • Внести данные для расшифрования (DECIPHER_ID – 1 или более вызовов) и получить в ответ расшифрованные данные.
Запросы необходимо отправлять на http://localhost:28016/vpnkeylocal/<SID2>/, где SID2 - идентификатор сессии, получаемый после перехода в бизнес-систему.

Инициализация расшифрования

Параметры запроса

Параметры Ограничение Описание
id INIT_DECIPHER_ID Тип = ID_FORMAT
Соответствует id функции
head Для прошивок 399+: 2048 URL-encoded байтов base64;
Для прошивок 500+: 2048 байт бинарных данных (размер base64, требуемый для их кодировки, не регламентирован)
Тип = BASE64
Данные начала CMS в base64
obj_id 8 байт Тип = HANDLE
Id сертификата для расшифрования
*с версии 500 игнорируется
mode 1,2 Тип = ENUM
Стандарт крипто операции: КС1 - токен только генерирует ключевую пару, данные шифруются «стартом.ехе» / КС2 - токен генерирует ключевую пару и шифрует данные.
*Только нечетные версии 500+; Опционально; по умолчанию: 2.

Пример запроса

POST http://localhost:28016/vpnkeylocal/iJbnPrTXFHOd85ZxdKQyrqGV9cOe11WmCY/
POST data:
id=INIT_DECIPHER_ID&head=MIIIWAYJKoZIhvcNAQcDoIIISTCCCEUCAQCgggSfoIIEmzCCBJcwggRGoAMCAQICCneGpLu1iLaqSBEwCAYGKoUDAgIDMIIBEzELMAkGA1UEBhMCUlUxLzAtBgNVBAoMJtCe0JDQniAi0KHQsdC10YDQsdCw0L3QuiDQoNC%2B0YHRgdC40LgiMU0wSwYDVQQLDETQo9C00L7RgdGC0L7QstC10YDRj9GO0YnQuNC5INGG0LXQvdGC0YAg0KHQkSDQoNCkICjQotC10YHRgtC%2B0LLRi9C5KTE%2BMDwGA1UEAww10JvQsNCy0YDQuNC90KHQki3QotC10YHRgtC%2B0LLQsNGPINC%2F0LXRh9Cw0YLRjC3Qo9CmLTkxITAfBgNVBCEMGNCi0LXRgdGC0LjRgNGD0Y7RidC40LkgUTEhMB8GCSqGSIb3DQEJARYSY2FzYnJmQHNiZXJiYW5rLnJ1MB4XDTE5MDkxMzA5MTAwMFoXDTIyMDkxMzA5MTE0NlowggE0MS8wLQYDVQQDDCbQn9C10YLRgCDQn9C10YLRgNC%2BINCf0LXRgtGA0L7QstC40YfQqjERMA8GA1UEBAwI0J%2FQtdGC0YAxJjAkBgNVBCoMHdCf0LXRgtGA0L4g0J%2FQtdGC0YDQvtCy0LjRh9CqMQswCQYDVQQGEwJSVTFzMHEGA1UECgxq0J7QsdGJ0LXRgdGC0LLQviDRgSDQvtCz0YDQsNC90LjRh9C10L3QvdC%2B0Lkg0L7RgtCy0LXRgtGB0YLQstC10L3QvdC%2B0YHRgtGM0Y4gItCc0LDRiNCwINC4INCc0LXQtNCy0LXQtNGMIjEOMAwGA1UECwwFcWV3cWUxEjAQBgNVBCEMCUJvb3Nzc3NzczEgMB4GCSqGSIb3DQEJARYRcXdlcXdlcUBtYXJycnIucnIwYzAcBgYqhQMCAhMwEgYHKoUDAgIjAgYHKoUDAgIeAQNDAARArVLHRJLdJl0SnsxGemCQ86Q8%2F9ZVBpV3KWRHLCLBXSWGGuqF5JoSBtWtNhbuA26bBRg2V7pPhQ0Rdc7oIPa4DaOCAVMwggFPMGAGBSqFA2RvBFcMVdCh0YDQtdC00YHRgtCy0L4g0Y3Qu9C10LrRgtGA0L7QvdC90L7QuSDQv9C%2B0LTQv9C40YHQuCAi0KDRg9GC0L7QutC10L0g0K3QptCfIDIuMCDQoCIwEwYDVR0gBAwwCjAIBgYqhQNkcQEwJgYHKoUDA3sDAQQbDBlBMDAyQVIyMHTQn9C10YLRgCDQny4g0J8uMBQGByqFAwN7AwQECQYHKoUDA3sFBDAOBgNVHQ8BAf8EBAMCBPAwFAYJYIZIAYb4QgEBAQH%2FBAQDAgeAMBYGA1UdJQEB%2FwQMMAoGCCsGAQUFBwMCMBoGByqFAwN7AwUEDwwNVExTMDk4MjYwNzQzMDAdBgNVHQ4EFgQU5rnb2j7CXqcq3qijl32MWcYW%2F4owHwYDVR0jBBgwFoAUm1I0EBH4CDR3jgrM1iYY3L4YOZwwCAYGKoUDAgIDA0EAT%2FHWRP%2Fz%2FgCdULkErGU064jF5vLjJNfJMXlRnczgxVV6upiaymDBhzLReusDu%2FGWhHN60R5nXFm198nL2FeJzTGB5DCB4QIBAoAU5rnb2j7CXqcq3qijl32MWcYW%2F4owHAYGKoUDAgITMBIGByqFAwICIwIGByqFAwICHgEEgacwgaQwKAQgN2n6mDPKLkCbYvWnjfEOzrvMkQ4Rb4eDzbXzO6O5M4UEBAcGfKigeAYHKoUDAgIfAaBjMBwGBiqFAwICEzASBgcqhQMCAiMCBgcqhQMCAh4BA0MABEBPEe%2BIR0GYa26Z77B9FzIKxo3euVtYBELWZb0vkz7yfd6oyGSaN3j83nycBsTu8ZOPzocWgHT9liOIuTXPcZF8BAivndzmaFRyBzCCArQGCSqGSIb3DQEHATAdBgYqhQMCAhUwEwQIzSoQ3lW4vDkGByqFAwICHwGAggKGOGS%2FPZ95Iiw7m9uK1VhOn8JC5G2s6bTsrdna9UyNubpVqmfaViS6jqiDNfkQdL4MQSIXuRwGoi7BEQg1tq9kTy%2FgK9IFiaRiVWzfQ9dunCMibmkK8fntSMez%2BvUb3Ur%2F86Fr0V5DO0YisSyMfGf4G%2BPiDHgEX5OrhvWD6MhS2XKxPFdhxsDjdN6F%2FB49kcVjKIJGpsKM9RKqc7WNTPfHlHteAhpKJaPKPoFzmRgVziTMRfrILY97T63swAdLgWDRNaVoaZzn4Dk%2F9%2BtFPACwLSo8pi%2BW4GjcqvW16Q%2Bk9Kj%2BGqa%2FmtwyJeZXghDmxslEiDUcNwXnoI6f6BHzxslFTdMklpqTItRKr%2BfWzc0n5i7Ed3naIggOmzhKjqRWp8Kt%2BaD1HkeR%2Be0axvUMqDaAEUgLceuOO1pzGtxK64tEO4YZilvlcaEgg9njNG1gLx6zh4Fh4CirSTUWg5dasAxhV80FdZTC75p5UL%2FFPULQ0z02auJ0rNw9jan2VISdR6cSKpK2vCTjPMw50TQF28%2BPSP1xBjeNF11BaGcEQS%2BbJnXDGycKLlg0Q1Pf9NsEfScIfqTrpB9gAtoPnEos6sX6cQNIGYEtXgNz7Z73ycnXtgD9P0TzDieJC%2BT1E4Hn6jonN60WskteZzZ0afk3TgH2x6l%2BZ0bpeQLndnQF0zWXT3WxpSsG4ad2cGcwRiVplFXctn%2BmBQwQ9vUTrLQJc6Lv6qEnTd4yVVF8pj8%3D&mode=1

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

Параметры Ограничение Описание
retcode 2 байт Тип = ENUM
код возврата функции
ctx_handle 8 байт Тип = HANDLE
хендл контекста операции
body_displ 2^32 - 1 Тип = NUMBER
Размер (смещение) начала CMS в чистом виде (до кодирования base64)

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

ctx_handle="AU6BTBjL"&body_displ="0"&retcode="1"

Расшифрование данных

Параметры запроса

Параметры Ограничение Описание
id DECIPHER_ID Тип = ID_FORMAT
id функции
data Для прошивок 399+: 6144 URL-encoded байтов base64;
Для прошивок 500+ чётных версий и нечётных ранее 507:
для режима КС1: 15360 байтов бинарных данных;
для режима КС2: 16777216 байтов бинарных данных;
для нечётных 507 и выше: 2^64 - 1 байтов бинарных данных; (размер base64, требуемый для их кодировки, не ограничен)
Тип = BASE64
Данные для расшифрования в base64; размер декодированных данных должен быть кратным 8, начиная с размера (смещения) начала CMS в чистом виде (до кодирования base64)
ctx_handle 8 байт Тип = HANDLE
хендл контекста операции

Пример запроса

POST http://localhost:28016/vpnkeylocal/iJbnPrTXFHOd85ZxdKQyrqGV9cOe11WmCY/
POST data:
id=DECIPHER_ID&data=MIIIWAYJKoZIhvcNAQcDoIIISTCCCEUCAQCgggSfoIIEmzCCBJcwggRGoAMCAQICCneGpLu1iLaqSBEwCAYGKoUDAgIDMIIBEzELMAkGA1UEBhMCUlUxLzAtBgNVBAoMJtCe0JDQniAi0KHQsdC10YDQsdCw0L3QuiDQoNC%2B0YHRgdC40LgiMU0wSwYDVQQLDETQo9C00L7RgdGC0L7QstC10YDRj9GO0YnQuNC5INGG0LXQvdGC0YAg0KHQkSDQoNCkICjQotC10YHRgtC%2B0LLRi9C5KTE%2BMDwGA1UEAww10JvQsNCy0YDQuNC90KHQki3QotC10YHRgtC%2B0LLQsNGPINC%2F0LXRh9Cw0YLRjC3Qo9CmLTkxITAfBgNVBCEMGNCi0LXRgdGC0LjRgNGD0Y7RidC40LkgUTEhMB8GCSqGSIb3DQEJARYSY2FzYnJmQHNiZXJiYW5rLnJ1MB4XDTE5MDkxMzA5MTAwMFoXDTIyMDkxMzA5MTE0NlowggE0MS8wLQYDVQQDDCbQn9C10YLRgCDQn9C10YLRgNC%2BINCf0LXRgtGA0L7QstC40YfQqjERMA8GA1UEBAwI0J%2FQtdGC0YAxJjAkBgNVBCoMHdCf0LXRgtGA0L4g0J%2FQtdGC0YDQvtCy0LjRh9CqMQswCQYDVQQGEwJSVTFzMHEGA1UECgxq0J7QsdGJ0LXRgdGC0LLQviDRgSDQvtCz0YDQsNC90LjRh9C10L3QvdC%2B0Lkg0L7RgtCy0LXRgtGB0YLQstC10L3QvdC%2B0YHRgtGM0Y4gItCc0LDRiNCwINC4INCc0LXQtNCy0LXQtNGMIjEOMAwGA1UECwwFcWV3cWUxEjAQBgNVBCEMCUJvb3Nzc3NzczEgMB4GCSqGSIb3DQEJARYRcXdlcXdlcUBtYXJycnIucnIwYzAcBgYqhQMCAhMwEgYHKoUDAgIjAgYHKoUDAgIeAQNDAARArVLHRJLdJl0SnsxGemCQ86Q8%2F9ZVBpV3KWRHLCLBXSWGGuqF5JoSBtWtNhbuA26bBRg2V7pPhQ0Rdc7oIPa4DaOCAVMwggFPMGAGBSqFA2RvBFcMVdCh0YDQtdC00YHRgtCy0L4g0Y3Qu9C10LrRgtGA0L7QvdC90L7QuSDQv9C%2B0LTQv9C40YHQuCAi0KDRg9GC0L7QutC10L0g0K3QptCfIDIuMCDQoCIwEwYDVR0gBAwwCjAIBgYqhQNkcQEwJgYHKoUDA3sDAQQbDBlBMDAyQVIyMHTQn9C10YLRgCDQny4g0J8uMBQGByqFAwN7AwQECQYHKoUDA3sFBDAOBgNVHQ8BAf8EBAMCBPAwFAYJYIZIAYb4QgEBAQH%2FBAQDAgeAMBYGA1UdJQEB%2FwQMMAoGCCsGAQUFBwMCMBoGByqFAwN7AwUEDwwNVExTMDk4MjYwNzQzMDAdBgNVHQ4EFgQU5rnb2j7CXqcq3qijl32MWcYW%2F4owHwYDVR0jBBgwFoAUm1I0EBH4CDR3jgrM1iYY3L4YOZwwCAYGKoUDAgIDA0EAT%2FHWRP%2Fz%2FgCdULkErGU064jF5vLjJNfJMXlRnczgxVV6upiaymDBhzLReusDu%2FGWhHN60R5nXFm198nL2FeJzTGB5DCB4QIBAoAU5rnb2j7CXqcq3qijl32MWcYW%2F4owHAYGKoUDAgITMBIGByqFAwICIwIGByqFAwICHgEEgacwgaQwKAQgN2n6mDPKLkCbYvWnjfEOzrvMkQ4Rb4eDzbXzO6O5M4UEBAcGfKigeAYHKoUDAgIfAaBjMBwGBiqFAwICEzASBgcqhQMCAiMCBgcqhQMCAh4BA0MABEBPEe%2BIR0GYa26Z77B9FzIKxo3euVtYBELWZb0vkz7yfd6oyGSaN3j83nycBsTu8ZOPzocWgHT9liOIuTXPcZF8BAivndzmaFRyBzCCArQGCSqGSIb3DQEHATAdBgYqhQMCAhUwEwQIzSoQ3lW4vDkGByqFAwICHwGAggKGOGS%2FPZ95Iiw7m9uK1VhOn8JC5G2s6bTsrdna9UyNubpVqmfaViS6jqiDNfkQdL4MQSIXuRwGoi7BEQg1tq9kTy%2FgK9IFiaRiVWzfQ9dunCMibmkK8fntSMez%2BvUb3Ur%2F86Fr0V5DO0YisSyMfGf4G%2BPiDHgEX5OrhvWD6MhS2XKxPFdhxsDjdN6F%2FB49kcVjKIJGpsKM9RKqc7WNTPfHlHteAhpKJaPKPoFzmRgVziTMRfrILY97T63swAdLgWDRNaVoaZzn4Dk%2F9%2BtFPACwLSo8pi%2BW4GjcqvW16Q%2Bk9Kj%2BGqa%2FmtwyJeZXghDmxslEiDUcNwXnoI6f6BHzxslFTdMklpqTItRKr%2BfWzc0n5i7Ed3naIggOmzhKjqRWp8Kt%2BaD1HkeR%2Be0axvUMqDaAEUgLceuOO1pzGtxK64tEO4YZilvlcaEgg9njNG1gLx6zh4Fh4CirSTUWg5dasAxhV80FdZTC75p5UL%2FFPULQ0z02auJ0rNw9jan2VISdR6cSKpK2vCTjPMw50TQF28%2BPSP1xBjeNF11BaGcEQS%2BbJnXDGycKLlg0Q1Pf9NsEfScIfqTrpB9gAtoPnEos6sX6cQNIGYEtXgNz7Z73ycnXtgD9P0TzDieJC%2BT1E4Hn6jonN60WskteZzZ0afk3TgH2x6l%2BZ0bpeQLndnQF0zWXT3WxpSsG4ad2cGcwRiVplFXctn%2BmBQwQ9vUTrLQJc6Lv6qEnTd4yVVF8pj9F1mj0I57x62tkqDH9%2BbgaMxFrlN8CSJ65TgoTwh442bxjC2mDmEdVvjirq76gC6D6SLmWfvuUf0wP06twKI1bFodSWHJlvpfgPqnRu%2BLN%2BrOZQBGuyMKO5dXFIg%3D%3D&ctx_handle=AU6BTBjL

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

Параметры Ограничение Описание
retcode 2 байт Тип = ENUM
код возврата функции
deciphered_blob Соответствует размеру поданного на вход поля "data" Тип = BASE64
часть расшифрованных данных

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

deciphered_blob="eyJhY2Nlc3NfdG9rZW4iOiI0YTNlMzE3Zi01MGQ5LTQ0MjItOGQ4Yy0zZDliNDczMWFlOTktMSIsInRva2VuX3R5cGUiOiJCZWFyZXIiLCJleHBpcmVzX2luIjozNjAwLCJyZWZyZXNoX3Rva2VuIjoiNDhhZDQwMzEtMjIxMC00MTFlLTgxZWEtNzc0YTA2YjUyYTJmLTEiLCJpZF90b2tlbiI6ImV5SjBlWEFpT2lKS1YxUWlMQ0poYkdjaU9pSm5iM04wTXpRdU1UQXRNakF4TWlKOS5leUp6ZFdJaU9pSTNORFl5WkRKbVpEbGpaR1V6WmpNelltRXdOR1UxTkRjMk1EZG1aR0ZsWmpCak9UTTROV1UxWWpNeE1XSmhNRGsyTVRZeU0yUXhZalpqTkRaaFl6VTNJaXdpWVhWa0lqb2lNakl6TXlJc0ltRmpjaUk2SW14dllTMHpJaXdpWVhwd0lqb2lNakl6TXlJc0ltRjFkR2hmZEdsdFpTSTZNVFU1TURRM016SXdNU3dpWVcxeUlqb2llM0IzWkN3Z2JXTmhMQ0J0Wm1Fc0lHOTBjQ3dnYzIxemZTSXNJbWx6Y3lJNkltaDBkSEE2THk5elluUXRiMkZtY3kwMk16ZzZPVEE0TUM5cFkyUnJJaXdpWlhod0lqb3hOVGt3TkRjek5UQXpMQ0pwWVhRaU9qRTFPVEEwTnpNeU1ETXNJbTV2Ym1ObElqb2lNemtpZlEuVF9UdUoxWFlrTFRKWm5Sc2RPQlJXSmcwRk56enNhcWRIc0FLWTBiaWt5SkpYbmVneUZobklKZHBYWDdTbkJqVGpkT1oyamZCUHNILVhBVExRWTNqV3cifQ=="&retcode="1"

После декодирования из BASE64URL параметра ответа deciphered_blob получаем ответ в виде JSON

Пример декодированного (из BASE64) параметра ответа deciphered_blob

{
"access_token": "4a3e317f-50d9-4422-8d8c-3d9b4731ae99-1",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "48ad4031-2210-411e-81ea-774a06b52a2f-1",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJnb3N0MzQuMTAtMjAxMiJ9.eyJzdWIiOiI3NDYyZDJmZDljZGUzZjMzYmEwNGU1NDc2MDdmZGFlZjBjOTM4NWU1YjMxMWJhMDk2MTYyM2QxYjZjNDZhYzU3IiwiYXVkIjoiMjIzMyIsImFjciI6ImxvYS0zIiwiYXpwIjoiMjIzMyIsImF1dGhfdGltZSI6MTU5MDQ3MzIwMSwiYW1yIjoie3B3ZCwgbWNhLCBtZmEsIG90cCwgc21zfSIsImlzcyI6Imh0dHA6Ly9zYnQtb2Fmcy02Mzg6OTA4MC9pY2RrIiwiZXhwIjoxNTkwNDczNTAzLCJpYXQiOjE1OTA0NzMyMDMsIm5vbmNlIjoiMzkifQ.T_TuJ1XYkLTJZnRsdOBRWJg0FNzzsaqdHsAKY0bikyJJXnegyFhnIJdpXX7SnBjTjdOZ2jfBPsH-XATLQY3jWw"
}

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней