ym88659208ym87991671
Access Token, Refresh Token | Документация для разработчиков

Access Token, Refresh Token

Обновлено 11 сентября 2023

Ресурс /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:

errorerror_descriptionОписание причины
SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTIONВ соответствии с текущими настройками сервиса с clientId={0} необходимо запрашивать ответ в формате JSONДля Приложения Партнера установлен запрет на прием запросов с http-заголовком Accept со значением application/jose
invalid_grantMissing grant_type parameter valueНе заполнен обязательный параметр grant_type
invalid_grantOne of the params (code, refresh_token) is required at requestНе заполнен один из обязательных параметров code или refresh_token
unsupported_grant_typeGrant type '{0}' is not supported"В параметре grant_type указано значение отличное от authorization_code или refresh_token
invalid_requestMissing parameters: codeВ параметре grant_type указано значение authorization_code, но отсутствует значение в параметре code
invalid_grantFailed to extract shoulder ID from {0}В параметре code указано некорректное значение
invalid_requestMissing parameters: refresh_tokenВ параметре grant_type указано значение refresh_token, но отсутствует значение в параметре refresh_token
invalid_grantFailed to extract shoulder ID from {0}В параметре refresh_token указано некорректное значение
unauthorized_clientUnknown client_id = '{0}'Переданный client_id не зарегистрирован
invalid_grantUnknown code = '{0}'Не найдено переданное значение code. Например, потому что срок действия кода истек или по данному коду уже осуществлялся вызов.
invalid_grantUnknown refresh token = '{0}' Не найдено переданное значение refresh_token. Например, потому что срок действия токена истек или по данному токену уже был осуществлен обмен на access_token.
invalid_grantExt service for authz code '{0}' is blockedПриложение Партнера зарегистрированное по указанному client_id - заблокировано.
unauthorized_clientClient '{0}' is blockedПриложение Партнера зарегистрированное по указанному client_id - заблокировано.
invalid_grantInvalid credentials for authz code '{0}'При запросе access_token по коду авторизации указан неверный client_secret`
invalid_grantInvalid credentials for refresh_token '{0}'При запросе access_token по refresh_token указан неверный client_secret
invalid_requestMissing parameters: {0}Отсутствует параметр redirect_uri
invalid_grantRedirect uri '{0}' is invalidПереданный параметр redirect_uri не совпадает со значением полученным ранее при запросе кода авторизации
invalid_requestclient secret expiredИстек срок действия client_secret
invalid_requestCode verifier requiredПри запросе кода авторизации был указан code_challenge, но в параметрах запроса токена отсутствует параметр code_verifier
invalid_requestInvalid code verifierЗначение code_verifier не отвечает параметрам протокола PKCE
invalid_grantFailed to verify code verifierХешированное значение code_challenge, полученное в запросе /authorize не совпадает со значением полученным в параметре code_verifier

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

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

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

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

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

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
issURL сервиса, сформировавшего ID Token
nonceЗначение параметра nonce, полученного при запросе авторизации
subУникальный идентификатор пользователя
Электронная подпись (Signature)
Массив байт электронной подписиПроверка электронной подписи, полученной в ID Token (содержимое ответа ID Tokena после второй точки), выполняется, используя алгоритм, указанный в параметре заголовка JWT alg. Приложению Партнера необходимо проверить подпись сертификатом Банка

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

ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.