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
&refresh_token=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 |
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 | Описание | |||
|---|---|---|---|---|
|
| |||
По умолчанию в 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, какой-либо параметр не может быть заполнен, то такой параметр не будет включен в ответ.