ym88659208ym87991671
СберБизнес ID | Документация для разработчиков

СберБизнес ID

Обновлено 27 марта 2024

Для интеграции СберБизнес ID необходимо пройти с 1 по 4 пункт в Шаги подключения к Sber API.

Общая информация

Сервис авторизации СберБизнес ID построен на базе протокола OAuth 2.0, с использованием типа авторизации Authorization Code Flow и с дополнительными параметрами и значениями, определенными протоколом OpenID Connect. Авторизация с помощью СберБизнес ID позволяет платформе партнера получить информацию о клиенте банка и выполнять операции от имени клиента банка в системе СберБизнес. Доступ до информации клиента и возможность выполнения действий от его лица предоставляется только с согласия клиента.

Вход через СберБизнес ID позволяет клиентам:

  • Без заполнения дополнительных форм регистрации создать учетную запись на платформе. Данные клиента подлинные и проверены банком.
  • Осуществлять безопасный вход с использованием двухфакторной аутентификации.
  • Использовать сервисы Sber API, позволяющие им выдавать партнерскому приложению право на работу со своими данными и отправку черновиков платежных и других типов документов в свой адрес.

Терминология

  • Клиент / Пользователь – владелец учетной записи СберБизнес ID, представитель юридического лица/ИП, являющийся пользователем системы СберБизнес и выполняющий операции в системе СберБизнес от имени юридического лица/ИП.
  • Партнер – организация, заключившая договор с банком на использование Sber API.
  • Платформа – приложение партнера, осуществляющие взаимодействие с сервисами СберБизнес ID и Sber API.
  • Ресурсная система – система СберБизнес, в которой работает клиент и доступ до ресурсов которой получает партнерское приложение от лица клиента.
  • Код авторизации (authorization code) – код сессии клиента, полученный после аутентификации и подписания им согласия в СберБизнес ID, необходим для получения доступа к токену (Access token), его обновления (Refresh token) и ID token.
  • Scope – набор атрибутов (claim) и операций, которые будут доступны партнерскому приложению после авторизации клиента.
  • Атрибуты (claim) – атрибуты с информацией о клиенте, которые может запрашивать партнерское приложение из ресурсной системы.
  • Операции – это ресурсы API, которые может вызывать партнерское приложение в ресурсной системе, сгруппированные по практическому назначению.

Согласие на передачу данных

Оферта

Согласие на передачу данных (оферта) - это документ, который Банк запрашивает у клиента и подтверждающий право Банка на передачу информации о клиенте третьему лицу (вам, как Партнеру Банка), выполнению операций третьим лицом (вами, как Партнером Банка) от лица Клиента. Согласие (оферта) содержит информацию о том к каким данным, операциям и на какой срок предоставлен доступ Партнеру. При предоставлении Партнеру доступа к данным своих счетов клиент в явном виде указывает каждый счет, к которому предоставляет доступ.

Сценарий выставление счета клиенту

Согласие запрашивается при обращении к сервису авторизации СберБизнес ID:

  • При первичном обращении пользователя к Платформе Партнера через сервис СберБизнес ID;
  • При повторном обращении, в случае если:
    • Истек срок действия предыдущего согласия;
    • Предыдущее согласие было отозвано пользователем;
    • Состав запрашиваемого согласия (scope) изменился относительно принятого ранее согласия.

Согласие на передачу данных не требуется, если Платформа использует получение и отправку документов только по своей организации.

Если пользователь отзывает согласие, то все выданные токены (Access Token, Refresh Token) деактивируются.

Если Приложение Партнера использует устаревшую версию авторизации /v1/oauth/authorize и состав запрашиваемых разрешений в составе scope изменился, то для получения согласия от Пользователя с новыми разрешениями необходимо перейти на вторую версию авторизации /v2/oauth/authorize.

Требования к платформе

Для обеспечения взаимодействия платформы с сервисом СберБизнес ID:

  • Платформа должна выполнять проверки в соответствии с требованием спецификаций: OAuth 2.0, OpenIDConnect.
  • Кнопка входа на платформе через СберБизнес ID должна отвечать требованиям дизайна пользовательского интерфейса.
  • Платформа должно пройти проверку службы безопасности на устойчивость к уязвимостям из перечня OWASP Top 10.
  • В случае возникновения ошибок работы межсервисного взаимодействия для анализа вопроса банк запросит логи обмена со стороны партнера. Рекомендуем реализовать логирование всех взаимодействий с банком с фиксацией отправляемых и (или) получаемых пакетов.

Схема работы сервиса

Участники

  • Клиент - представитель ЮЛ/ИП, который имеет пользовательский профиль в СберБизнес своей компании с правом подписи;
  • Платформа (в схеме разделили на front и back) - любой web-ресурс (интернет-магазин, мобильное приложение и т.д.), который Вы используете в рамках клиентского пути Клиентов;
  • СберБизнес ID - единая учетная запись пользователя ЮЛ/ИП, используемая для регистрации и входа пользователей в продукты и сервисы Банка и партнеров Sber API.

Предусловия

  • Клиент находится на Платформе

Постусловия

  • Клиент находится на Платформе как авторизованный пользователь
Сценарий выставление счета клиенту

Получение кода авторизации (/v2/oauth/authorize)

Работа с сервисами авторизации версии v1 описана в файле.

Alt text https://sbi.sberbank.ru:9443/ic/sso/api/v2/oauth/authorize

Метод /v2/oauth/authorize позволяет открыть страницу аутентификации в СберБизнес. Ваша Платформа формирует запрос в формате ссылки, устанавливая все параметры, и передает ее браузеру пользователя (Клиента) для прохождения аутентификации. При успешной аутентификации СберБизнес ID вернет браузер пользователя на Redirect_uri вместе с кодом авторизации (authorization code).

Для обращения к методу необходимо отправлять запрос на:

  • Тестовый контур https://efs-sbbol-ift-web.testsbi.sberbank.ru:9443/ic/sso/api
  • Промышленный контур https://sbi.sberbank.ru:9443/ic/sso/api

Request

/v2/oauth/authorize

НаименованиеТипФорматRegexpОбязательностьОписание
QUERRY PARAMETERS
scopestringstring^[a-zA-Z0-9._ -]$requiredНабор атрибутов (claim) и операций, которые будут доступны платформе после авторизации клиента. Должен содержать обязательный параметр openid
response_typestringstring^code$requiredВсегда должен содержать значение code. Авторизация по СберБизнес ID поддерживает только authorization code flow протокола OAuth 2.0
client_idstringstring\d{1,10}requiredУникальный идентификатор Платформы, полученный при подключении к Sber API
redirect_uristringURL^[a-zA-Z0-9._ -]$requiredСсылка на ресурс (конечную точку) Платформы, на которую будет передан код авторизации и перенаправлен браузер пользователя после успешной авторизации. Значение переданное в параметре redirect_uri сравнивается по маске со значением, полученным при подключении к Sber API

Пример:
При подключении вы указали маску для redirect_uri https://example.ru/auth/login
Если при запросе кода авторизации будет указан адрес:
- https://example.ru, то такое значение не пройдет проверку, т.к. отсутствует часть обязательных path-параметров указанных при регистрации;
- https://example.ru/auth/login/register, то такое значение пройдет проверку, т.к. совпадает с зарегистрированным. При этом расширение path-параметров не влияет на проверку
statestringstring^[a-zA-Z0-9]{36,}$requiredПараметр для предотвращения CSRF-атак. Значение State должно быть защищено от подбора и храниться таким образом, чтобы его не мог изменить никто, кроме платформы. Рекомендуется использовать идентификатор сессии клиента в платформе или один из его производных (например, хэш этого идентификатора), при этом может использоваться любой другой механизм генерации случайного значения достаточной длины для предотвращения подбора. В общем случае оптимально использовать строку длиной не менее 36 символов с проверкой регистра, без использования специальных символов. Полные требования к значению state см. в спецификации rfc6749. Для повторного запроса это значение должно заменяться новым.
noncestringstring^[a-zA-Z0-9]{10,}$optionalПараметр служит для защиты от replay-атак, то есть для предотвращения обработки одного и того же запроса несколько раз. Значение Nonce должно быть защищено от подбора и храниться таким образом, чтобы его не мог изменить никто, кроме платформы. Рекомендуется использовать случайное значение, сохраняемое в сессии клиента в платформе. Для повторного запроса это значение должно заменяться новым. В общем случае оптимально использовать строку длиной не менее 10 символов с проверкой регистра, без использования специальных символов. Полные требования к значению nonce см. в спецификации Open ID Connect
code_challengestringstring^[a-zA-Z0-9]$optionalПараметр в соответствии с надстройкой PKCE над протоколом OAuth 2.0. Должен быть уникальным для каждого вызова /v2/oauth/authorize. См. правила формирования параметра в PKCE. Подключение настройки согласуется с менеджером при регистрации платформы. Рекомендуется к использованию, т.к увеличивает безопасность подключения
code_challenge_methodstringstring^S256$optionalСвязанный с code_challenge параметр. Заполняется в соответствии со спецификацией PKCE. Если указан, то всегда должен содержать значение S256. Параметр «plain» не поддерживается.

Если передан параметр code_challenge, то параметр code_challenge_method должен обязательно присутствовать

Responses

При успешной аутентификации СберБизнес ID вернет браузер пользователя на Redirect_uri вместе с кодом авторизации (code) и значением параметра state, который был указан в ссылке аутентификации.

302 (OK)

ПараметрТипОписание
codeQueryЗначение кода авторизации. Формируется в произвольном формате из букв латинского алфавита и цифр длиной 38 символов

Срок жизни кода авторизации составляет 120 секунд
stateQueryЗначение параметра state, полученного при вызове ресурса /v2/oauth/authorize. Полученный параметр state должен быть проверен платформой на соответствие значению, указанному при вызове ресурса /v2/oauth/authorize. Если значения не совпадают, обработка должна быть немедленно прекращена

При наличии ошибок в ссылке аутентификации СберБизнес ID вернет браузер пользователя на Redirect_uri вместе с параметрами ошибки.

302 (Error)

Errorerror_descriptionОписание
unsupported_response_typeResponsetype {значение responsetype} not supportedВ параметрах запроса кода авторизации указан неправильный response_type. Должно быть указано code.
invalid_requestMissing parameters: {не указанные поля через пробел}В параметрах запроса кода авторизации отсутствует хотя бы один из обязательных параметров: response_type, state, scope и др. Смотрите модель запроса /v2/oauth/authorize выше.
invalid_requestInvalid code challengeВ параметре code_challenge передано значение не отвечающее требованиям протокола PKCE
invalid_requestTransform algorithm requiredПередан параметр code_challenge, но не указан code_challenge_method
invalid_requestTransform algorithm not supportedВ параметр code_challenge_method указано значение отличное от S256
invalid_requestCode challenge requiredВ параметрах запроса кода авторизации должны быть указаны параметры code_challenge и code_challenge_method
invalid_scopeScope 'openid' is requiredВ параметре scope отсутствует обязательный параметр openid
invalid_scopeToo many scopes requestedВызов осуществлен на ресурс предыдущей версии /v1/oauth/authorize и в параметре scope передано более одного дополнительного значения scope
invalid_scopeInvalid scope param valueВызов осуществлен на ресурс предыдущей версии /v1/oauth/authorize и в параметре scope передано незарегистрированное значение scope
invalid_scopeInvalid scopeВ параметре scope передано незарегистрированное значение scope
invalid_scopeScope PAYMENT_SUBSCRIPTION is requiredВ параметре scope должен присутствовать параметр payment_subscription.
invalid_scopeScope PAYMENT_SUBSCRIPTION is forbiddenПараметре scope не может содержать параметр payment_subscription.

В ряде случаев СберБизнес ID не сможет вернуть пользователя на Redirect_uri. При переходе по некорректному URL аутентификации в адресной стороке пользователя будет информация, которая поможет диагностировать ошибку.

302 (Found)

ErrorОписание
invalid_paramsВ параметрах запроса присутствуют повторяющиеся query параметры
redirect_uri_is_absentВ параметрах запроса отсутствует обязательный параметр redirect_uri
client_id_is_absentВ параметрах запроса отсутствует обязательный параметр client_id
bad_client_idВ параметрах указан незарегистрированный client_id
client_blockedВ параметрах указан заблокированный client_id
invalid_redirect_uriВ параметрах запроса параметр redirect_uri не совпадает со значением указанным при регистрации платформы

Аутентификация и авторизация глазами клиента

Клиентский путь

ШагОписаниеСкриншот
1Нажать на кнопку «Войти по СберБизнес ID» на платформе
Войти по СберБизнес ID
2Окно ввода логина и пароля, и подтверждение входа
Войти по СберБизнес ID

Войти по СберБизнес ID
3После входа отобразится окно согласия на передачу данных
Войти по СберБизнес ID
4Подписание согласия с помощью СМС
Войти по СберБизнес ID

Получение токена доступа (access_token)

Alt text https://fintech.sberbank.ru:9443/ic/sso/api/v2/oauth/token

Метод /v2/oauth/token позволяет обменять код авторизации на токены доступов.
Будет получено три токена: access_token, refresh_token, id_token.

Для обращения к методу необходимо отправлять запрос на:

  • Тестовый контур https://iftfintech.testsbi.sberbank.ru:9443/ic/sso/api/
  • Промышленный контур https://fintech.sberbank.ru:9443/ic/sso/api

Request

/v2/oauth/token

НаименованиеТипФорматRegexpОбязательностьОписание
HEADER
Content-Typestringstring^(application/json|text/plain|application/xml|multipart/form-data|application/x-www-form-urlencoded)$requiredТип данных, которые передаются в теле запроса.
Должен содержать значение application/x-www-form-urlencoded.
Acceptstringstring^(application/json|application/jose)optionalУказывает на формат данных, который вы готовы принять от Банка.
Если ответ не требуется в зашифрованном виде, то может быть не указан или передан со значением application/json.
Если необходимо получить ответ на запрос токена в зашифрованном виде, то необходимо передать параметр со значением application/jose.
BODY
{
grant_typestringstring^(authorization_code|refresh_token)$requiredУказывает тип предоставления, который используется для запроса токена доступа
Значение должно быть authorization_code
codestringstring^([a-zA-Z0-9]){38}$requiredКод авторизации.
В параметре необходимо использовать значение code, полученное на адрес redirect_uri при успешной аутентификации пользователя по URL аутентификации /v2/oauth/authorize.

Каждый code может быть использован только один раз. Например, если при запросе access_token по коду авторизации была допущена ошибка в каком либо из параметров и передано значение code, то повторное использование данного значения code уже будет недопустимо.
client_idstringstring^[a-zA-Z0-9]+$requiredУникальный идентификатор вашей Платформы, полученный при подключении к Sber API
redirect_uristringstring^(https?:\/\/)?(www.)?([a-z0-9-.]+.[a-z]{2,3})(:[0-9]{1,5})?\/?.*$requiredАдрес вашей Платформы, на который СберБизнес ID возвращает пользователя при успешной аутентификации. Должен в точности совпадать со значением, переданным ранее при вызове метода /v2/oauth/authorize

Пример:
Если в redirect_uri было указано https://example.ru/auth/login/register, то точно такое же значение должно быть указано при запросе /v2/oauth/token, даже если зарегистрирован redirect_uri = https://example.ru/auth/login
client_secretstringstring^[a-zA-Z0-9]{8,256}$requiredПароль вашей Платформы. Вы его впервые получаете при подключении к Sber API и в последующем периодически обновляете.
code_verifierstringstring^[a-zA-Z0-9]+$optionalПараметр в соответствии с надстройкой PKCE над протоколом OAuth 2.0. Раскодированное значение code_challenge переданное ранее при вызове ресурса /authorize. См. правила формирования параметра в PKCE.

Становится обязательным, если при регистрации платформы настройка PKCE была подключена или при вызове метода /v2/oauth/authorize параметр code_challenge был передан.
}

Responses

200 (OK)

НаименованиеТипОбязательностьОписание
HEADER
Content-TypestringrequiredЕсли в запросе:
- не был передан заголовок Accept или передан в значении application/json, то в ответе параметр будет содержать значение application/json
- был передан заголовок Accept в значении application/jose, то в ответе будет указано application/jose и полученное тело ответа потребуется расшифровать.
BODY
{
access_tokenstringrequiredАвторизационный токен доступа
token_typestringrequiredТип токена. Всегда возвращается значение Bearer
expires_instringrequiredСрок жизни токена в секундах.
Срок жизни access_token составляет 60 минут.
refresh_tokenstringrequiredТокен обновления. Используется для обновления Access Token. Подробнее про применение значения refresh_token см. в Обновление токена доступа (access_token)
Срок жизни refresh_token составляет 180 дней.
scopestringrequiredНабор атрибутов (claim) и операций, которые будут доступны Платформе после авторизации клиента.
id_tokenstringrequiredЗакодированный в Base64URL набор атрибутов клиента, необходимых для идентификации пользователя. Атрибуты разделены символами «.», каждый необходимо декодировать отдельно.
}

400 (Bad request)

errorerror_descriptionОписание причины
invalid_grantMissing grant_type parameter valueНе заполнен обязательный параметр grant_type
invalid_grantOne of the params (code, refresh_token) is required at requestНе заполнен один из обязательных параметров code или refresh_token
invalid_grantFailed to extract shoulder ID from {0}В параметре code или refresh_token указано некорректное значение
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 - заблокировано.
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_grantRedirect uri '{0}' is invalidПереданный параметр redirect_uri не совпадает со значением полученным ранее при запросе кода авторизации
invalid_grantFailed to verify code verifierХешированное значение code_challenge, полученное в запросе /authorize не совпадает со значением, полученным в параметре code_verifier
invalid_requestMissing parameters: codeВ параметре grant_type указано значение authorization_code, но отсутствует значение в параметре code
invalid_requestMissing parameters: refresh_tokenВ параметре grant_type указано значение refresh_token, но отсутствует значение в параметре refresh_token
invalid_requestMissing parameters: {0}Отсутствует параметр redirect_uri
invalid_requestclient secret expiredИстек срок действия client_secret
invalid_requestCode verifier requiredПри запросе кода авторизации был указан code_challenge, но в параметрах запроса токена отсутствует параметр code_verifier
invalid_requestInvalid code verifierЗначение code_verifier не отвечает параметрам протокола PKCE
unauthorized_clientUnknown client_id = '{0}'Переданный client_id не зарегистрирован
unauthorized_clientClient '{0}' is blockedПлатформа зарегистрированное по указанному client_id - заблокировано.
unsupported_grant_typeGrant type '{0}' is not supported"В параметре grant_type указано значение отличное от authorization_code или refresh_token
НаименованиеТипОбязательностьОписание
{
errorstringrequiredОшибка запроса
error_descriptionstringrequiredОписание ошибки
}

403 (Forbidden)

errorCodeerrorMsgОписание причины
requestForbiddenThe server configuration prohibits executing a request to the endpoint {0}На данном сервере запрещен вызов указанного метода.
Например, вызов метода /v2/oauth/token осуществляется на домен https://efs-sbbol-ift-web.testsbi.sberbank.ru:9443, а должен осуществляться на домен https://iftfintech.testsbi.sberbank.ru:9443
certificateNotFoundThe certificate was not whitelisted for client_id={0}Не пройдена проверка сертификата по белому списку
НаименованиеТипОбязательностьОписание
{
errorCodestringrequiredОшибка запроса
errorMsgstringrequiredОписание ошибки
}

406 (Not acceptable)

errorerror_descriptionОписание причины
SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTIONJSONВ соответствии с текущими настройками платформы необходимо запрашивать ответ в формате JSON
SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTIONJWE Compact SerializationВ соответствии с текущими настройками платформы необходимо запрашивать ответ в формате JWE Compact Serialization
НаименованиеТипОбязательностьОписание
{
errorstringrequiredОшибка запроса
error_descriptionstringrequiredОписание ошибки
}

500 (Internal Server Error)

CauseMessageDescription
UNKNOWN_EXCEPTIONВнутренняя ошибка сервераСделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
НаименованиеТипОбязательностьОписание
Notice {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}

access_token

Это уникальный идентификатор, который позволяет платформе подтвердить Банку, что клиент дал ему разрешение на доступ к его данным. Он необходим для использования других запросов Sber API.
С момента получения токен доступа (access_token) действителен 60 минут.

refresh_token

access_token имеет временный характер действия (60 минут с момента получения). Для обновления токена доступа необходимо использовать токен обновления (refresh_token).
С момента получения токен обновления (refresh token) действителен 180 дней.

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

ID token (/token)

Этот токен используется для подтверждения того, что пользователь успешно прошел процесс авторизации и имеет доступ к запрашиваемым операциям.

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

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

Каждая часть ответа, разделенная точкой, должна декодироваться отдельно. Для декодирования следует воспользоваться алгоритмом Base64URL Encoding.

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

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

Получение информации (/v2/oauth/user-info)

Alt text https://fintech.sberbank.ru:9443/ic/sso/api/v2/oauth/user-info

Метод /v2/oauth/user-info позволяет получить информацию о клиенте в ID token.

Для получения информации необходимо отправить GET-запрос /v2/oauth/user-infoс токеном доступа (access_token) пользователя в параметре Authorization заголовка.

Для обращения к методу необходимо отправлять запрос на:

  • Тестовый контур https://iftfintech.testsbi.sberbank.ru:9443/ic/sso/api/
  • Промышленный контур https://fintech.sberbank.ru:9443/ic/sso/api/

Request

/v2/oauth/user-info

НаименованиеТипФорматRegexpОбязательностьОписание
HEADER
Authorizationstringstring^([a-zA-Z0-9]){38}$requiredAccess token пользователя, полученный через SSO.

Responses

200 (OK)

ПараметрОписание
HEADER
typТип токена
algАлгоритм шифрования
PAYLOAD
audИдентификатор платформы, для которого сформирован ID Token
issURL сервиса, сформировавшего ID Token
subУникальный идентификатор пользователя
Значения атрибутов (claim)которые указали в Scope в ссылке запроса /v2/oauth/token
SIGNATURE
Массив байт электронной подписиПроверка электронной подписи, полученной в ID Token (содержимое ответа ID Tokena после второй точки), выполняется, используя алгоритм, указанный в параметре заголовка JWT alg. Платформе необходимо проверить подпись сертификатом Банка

400 (Bad request)

errorerror_descriptionОписание причины
invalid_requestMissing authorization headerОтсутствует обязательный параметр заголовка Authorization
invalid_requestIncorrect authorization methodВ параметре заголовка Authorization указан некорректный тип (добавить Bearer)
НаименованиеТипОбязательностьОписание
{
errorstringrequiredОшибка запроса
error_descriptionstringrequiredОписание ошибки
}

401 (Unauthorized Error)

errorerror_descriptionОписание причины
invalid_tokenAccess Token <значение полученного токена> not foundПереданный токен не найден. Например, потому что истек срок его действия или пользователь отозвал согласие на передачу данных
НаименованиеТипОбязательностьОписание
{
errorstringrequiredОшибка запроса
error_descriptionstringrequiredОписание ошибки
}

403 (Forbidden)

errorCodeerrorMsgОписание причины
requestForbiddenThe server configuration prohibits executing a request to the endpoint {0}На данном сервере запрещен вызов указанного метода.
Например, вызов метода /v2/oauth/token осуществляется на домен https://efs-sbbol-ift-web.testsbi.sberbank.ru:9443, а должен осуществляться на домен https://iftfintech.testsbi.sberbank.ru:9443
certificateNotFoundThe certificate was not whitelisted for client_id={0}Не пройдена проверка сертификата по белому списку
НаименованиеТипОбязательностьОписание
{
errorCodestringrequiredОшибка запроса
errorMsgstringrequiredОписание ошибки
}

406 (Not acceptable)

errorerror_descriptionОписание причины
SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTIONJSONВ соответствии с текущими настройками платформы необходимо запрашивать ответ в формате JSON
SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTIONJWE Compact SerializationВ соответствии с текущими настройками платформы необходимо запрашивать ответ в формате JWE Compact Serialization
НаименованиеТипОбязательностьОписание
{
errorstringrequiredОшибка запроса
error_descriptionstringrequiredОписание ошибки
}

500 (Internal Server Error)

CauseMessageDescription
UNKNOWN_EXCEPTIONВнутренняя ошибка сервераСделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
НаименованиеТипОбязательностьОписание
Notice {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}

ID token (/user-info)

Этот токен содержит информацию о клиенте, представлен в виде JSON Web Token (JWT) и структурой:

Алгоритм подписи и тип токена (Header); Полезная нагрузка (Payload); Электронная подпись (Signature). Каждая часть ответа, разделенная точкой, должна декодироваться отдельно. Для декодирования следует воспользоваться алгоритмом Base64URL Encoding.

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

Обновление токена доступа (refresh_token)

Cрок действия токена доступа (access_token) 60 минут. Вам необходимо реализовать обновление токена доступа для последующих запросов в канале Sber API.

Обновление токена доступа

Alt text https://fintech.sberbank.ru:9443/ic/sso/api/v2/oauth/token

Метод /v2/oauth/token позволяет получить новый токен доступа (access_token) и новый токен обновления (refresh_token).

Для использования метода необходимо указать значение токена обновления (refresh_token), полученный при последней авторизации по СберБизнес ID или последнего обновления токена доступа.

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

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

Для обращения к методу необходимо отправлять запрос на:

  • Тестовый контур https://iftfintech.testsbi.sberbank.ru:9443/ic/sso/api/
  • Промышленный контур https://fintech.sberbank.ru:9443/ic/sso/api

Request

/v2/oauth/token

НаименованиеТипФорматRegexpОбязательностьОписание
HEADER
Content-Typestringstring^(application/json|text/plain|application/xml|multipart/form-data|application/x-www-form-urlencoded)$requiredТип данных, которые передаются в теле запроса.
Должен содержать значение application/x-www-form-urlencoded.
Acceptstringstring^(application/json|application/jose)optionalУказывает на формат данных, который вы готовы принять от Банка.
Если ответ не требуется в зашифрованном виде, то может быть не указан или передан со значением application/json.
Если необходимо получить ответ на запрос токена в зашифрованном виде, то необходимо передать параметр со значением application/jose.
BODY
{
grant_typestringstring^(authorization_code|refresh_token)$requiredУказывает тип предоставления, который используется для запроса токена доступа
Значение должно быть refresh_token
refresh_tokenstringstring^([a-zA-Z0-9]){38}$requiredЗначение refresh_token полученное при обмене кода авторизации на access_token
client_idstringstring^[a-zA-Z0-9]+$requiredУникальный идентификатор вашей Платформы, полученный при подключении к Sber API
client_secretstringstring^[a-zA-Z0-9]{8,256}$requiredПароль вашей Платформы. Вы его впервые получаете при подключении к Sber API и в последующем периодически обновляете.
}

Responses

200 (OK)

НаименованиеТипОбязательностьОписание
HEADER
Content-TypestringrequiredЕсли в запросе:
- не был передан заголовок Accept или передан в значении application/json, то в ответе параметр будет содержать значение application/json
- был передан заголовок Accept в значении application/jose, то в ответе будет указано application/jose и полученное тело ответа потребуется расшифровать.
BODY
{
access_tokenstringrequiredАвторизационный токен доступа
token_typestringrequiredТип токена. Всегда возвращается значение Bearer
expires_instringrequiredСрок жизни токена в секундах.
Срок жизни access_token составляет 60 минут.
refresh_tokenstringrequiredТокен обновления. Используется для обновления Access Token. Подробнее про применение значения refresh_token см. в Обновление токена доступа (access_token)
Срок жизни refresh_token составляет 180 дней.
scopestringrequiredНабор атрибутов (claim) и операций, которые будут доступны Платформе после авторизации клиента.
id_tokenstringrequiredЗакодированный в Base64URL набор атрибутов клиента, необходимых для идентификации пользователя. Атрибуты разделены символами «.», каждый необходимо декодировать отдельно. Подробнее о декодировании и параметрах id_token см. в ID Token
}

400 (Bad request)

errorerror_descriptionОписание причины
invalid_grantMissing grant_type parameter valueНе заполнен обязательный параметр grant_type
invalid_grantOne of the params (code, refresh_token) is required at requestНе заполнен один из обязательных параметров code или refresh_token
invalid_grantFailed to extract shoulder ID from {0}В параметре code или refresh_token указано некорректное значение
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 - заблокировано.
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_grantRedirect uri '{0}' is invalidПереданный параметр redirect_uri не совпадает со значением полученным ранее при запросе кода авторизации
invalid_grantFailed to verify code verifierХешированное значение code_challenge, полученное в запросе /authorize не совпадает со значением, полученным в параметре code_verifier
invalid_requestMissing parameters: codeВ параметре grant_type указано значение authorization_code, но отсутствует значение в параметре code
invalid_requestMissing parameters: refresh_tokenВ параметре grant_type указано значение refresh_token, но отсутствует значение в параметре refresh_token
invalid_requestMissing parameters: {0}Отсутствует параметр redirect_uri
invalid_requestclient secret expiredИстек срок действия client_secret
invalid_requestCode verifier requiredПри запросе кода авторизации был указан code_challenge, но в параметрах запроса токена отсутствует параметр code_verifier
invalid_requestInvalid code verifierЗначение code_verifier не отвечает параметрам протокола PKCE
unauthorized_clientUnknown client_id = '{0}'Переданный client_id не зарегистрирован
unauthorized_clientClient '{0}' is blockedПлатформа зарегистрированное по указанному client_id - заблокировано.
unsupported_grant_typeGrant type '{0}' is not supported"В параметре grant_type указано значение отличное от authorization_code или refresh_token
НаименованиеТипОбязательностьОписание
{
errorstringrequiredОшибка запроса
error_descriptionstringrequiredОписание ошибки
}

403 (Forbidden)

errorCodeerrorMsgОписание причины
requestForbiddenThe server configuration prohibits executing a request to the endpoint {0}На данном сервере запрещен вызов указанного метода.
Например, вызов метода /v2/oauth/token осуществляется на домен https://efs-sbbol-ift-web.testsbi.sberbank.ru:9443, а должен осуществляться на домен https://iftfintech.testsbi.sberbank.ru:9443
certificateNotFoundThe certificate was not whitelisted for client_id={0}Не пройдена проверка сертификата по белому списку
НаименованиеТипОбязательностьОписание
{
errorCodestringrequiredОшибка запроса
errorMsgstringrequiredОписание ошибки
}

406 (Not acceptable)

errorerror_descriptionОписание причины
SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTIONJSONВ соответствии с текущими настройками платформы необходимо запрашивать ответ в формате JSON
SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTIONJWE Compact SerializationВ соответствии с текущими настройками платформы необходимо запрашивать ответ в формате JWE Compact Serialization
НаименованиеТипОбязательностьОписание
{
errorstringrequiredОшибка запроса
error_descriptionstringrequiredОписание ошибки
}

500 (Internal Server Error)

CauseMessageDescription
UNKNOWN_EXCEPTIONВнутренняя ошибка сервераСделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
НаименованиеТипОбязательностьОписание
Notice {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}

Обновление Client Secret (каждые 40 дней)

client_secret – это пароль от вашей интеграции, который увеличивает безопасность передачи данных.

В процессе заключения договора на Sber API поддержка Банка свяжется с контактным лицом вашей компании по вопросу получения Client Secret.

Обновить client_secret можно вручную в Личном кабинете Sber API или с помощь метода /v1/change-client-secret

Срок действия client_secret составляет 40 дней с даты выпуска. Обновлять Client Secret рекомендуем заранее до истечения срока во избежание блокировки интеграции.

Банк также отправляет уведомления о скором окончании действия client_secret через E-mail контактного лица из Заявления на подключение к Sber API. Уведомление будет направлено за 5 дней до срока окончания действия client secret.

Сценарий выставление счета клиенту

Alt text https://fintech.sberbank.ru:9443/ic/sso/api/v1/change-client-secret

Метод /v1/change-client-secret позволяет обновить client _secret вашей интеграции. В запросе необходимо передавать токен доступа (access_token) Пользователя собственной организации.

Для обращения к методу необходимо отправлять запрос на:

  • Тестовый контур https://iftfintech.testsbi.sberbank.ru:9443/ic/sso/api/
  • Промышленный контур https://fintech.sberbank.ru:9443/ic/sso/api/

Request

/v1/change-client-secret

НаименованиеТипФорматRegexpОбязательностьОписание
QUERRY PARAMETERS
access_tokenstringUUID^([0-9A-Fa-f]{8})-([0-9A-Fa-f]{4})-([0-9A-Za-z]{4})-([0-9A-Fa-f]{12})-(1|2)$requiredAccess token пользователя, полученный через SSO.
client_idstringstring\d{1,10}optionalУказывается идентификатор Платформы (client_id), для которого необходимо изменить client_secret.
Если client_id не указан, то будет изменен client_secret приложения, для которого выдан access_token.
client_secretstringstring^[a-zA-Z0-9]{8,256}$requiredПароль вашей Платформы. Вы его впервые получаете при подключении к Sber API и в последующем периодически обновляете.
new_client_secretstringstring^[a-zA-Z0-9]{8,256}$requiredНовое значение client_secret Плафтормы, для которого необходимо изменить client_secret

Responses

200 (ОК)

НаименованиеТипОбязательностьОписание
clientSecretExpirationnumberoptionalСрок действия нового Client Secret (в днях)

400 (Bad request)

errorerror_descriptionОписание причины
Передано некорректное значение нового client secret: '{0}'Значение нового Client Secret совпадает с текущим или не прошло валидацию на допустимый размер значения
Передано некорректное значение действующего client secret: '{0}'Значение переданное в параметре client_secret не совпадает со значением указанным для client_id
invalid_grantParameter 'access_token' is required at requestВ запросе не был передан access_token пользователя вашей компании
НаименованиеТипОбязательностьОписание
{
errorstringrequiredОшибка запроса
error_descriptionstringoptionalОписание ошибки
}

401 (Unauthorized Error)

errorОписание причины
UNAUTHORIZEDПереданный токен не найден. Например, потому что пользователь отозвал согласие на передачу данных
НаименованиеТипОбязательностьОписание
{
errorstringrequiredОшибка запроса
}

403 (Forbidden)

errorОписание причины
Изменение client secret недоступноДля данного типа Платформы использование ресурса /change-client-secret недоступно
Client secret просроченСрок действия текущего Client Secret истек. Для обновления Client Secret обратитесь воспользуйтесь соответствующей функциональностью Личного кабинета (если есть доступ) или в техническую поддержку Банка.
Попытка изменения client secret при помощи access token, выданного пользователем, не принадлежащим организации, предоставляющей услуги внешнего сервисаAccess Token выдан пользователем, не принадлежащим организации владельцу Платформы
Попытка изменения client secret внешнему сервису, организация которого отличается от организации пользователя, выдавшего access tokenПараметр client_id указан и организация владельца Access Token не совпадает с организацией владельца Платформы, чей client_id указан
НаименованиеТипОбязательностьОписание
{
errorstringrequiredОшибка запроса
}

406 (Not acceptable)

errorОписание причины
SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTIONДля Платформы установлен запрет на прием запросов с http-заголовком Accept со значением application/jose
SSOREQUESTED_FORMAT_NOT_ACCEPTABLE_EXCEPTIONДля Платформы установлен запрет на прием запросов с http-заголовком Accept со значением application/json
НаименованиеТипОбязательностьОписание
{
errorstringrequiredОшибка запроса
}

500 (Internal Server Error)

CauseMessageDescription
UNKNOWN_EXCEPTIONВнутренняя ошибка сервераСделайте повторный запрос. Если ошибка повторится, подготовьте логи запроса и направьте в службу Технической поддержки Банка.
НаименованиеТипОбязательностьОписание
Notice {
causestringoptionalПричина или основание сообщения,
referenceIdstringoptionalУникальный идентификатор ошибки (UUID),
messagestringoptionalСообщение,
}

FAQ

Кто может подписывать согласие на передачу данных при авторизации по СберБизнес ID?

Учетная запись СберБизнес ID с правом подписи:

  • Первая;
  • Вторая;
  • Единственная.
Где посмотреть право подписи и тип подписи?

  1. Необходимо зайти в СберБизнес
  2. В верхнем правом углу нажать на свой профиль
  3. Нажать на СберБизнес ID
  4. На новой странице внизу необходимо найти поле «Полномочия», здесь будет указан тип подписи.
Профиль
Полномочия

Отсутствие поля "Полномочия" в разделе "Мой профиль" говорит об отсутствии права на подпись. Такой пользователь не сможет подписать Согласие на передачу данных от лица компании.

Нет полномочий

Как получить право подписи?

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

Как мне тестировать сервис на тестовом контуре?

После подписания документов на подключение к Sber API, вам направят комплект настроек и данные по организациям и учетными записями для тестирования.

Что делать если истек токен доступа (access_token)?

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

Что будет с токеном обновления (refresh_token) после получения новой пары токена доступа (access_token) и обновления (refresh_token)?

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

Что делать если истек срок действия токена обновления (refresh_token)?

Пользователю необходимо повторно пройти процесс авторизации для получения Платформой новой пары access_token и refresh_token.

Какую информацию по Клиенту я получу?

Вы получите информацию, которую запрашивали в виде атрибутов(claim) в ссылке аутентификации в параметрах scope.

Где я могу ознакомиться со всеми возможными атрибутами (claim)?

На странице Атрибуты (Claims)

Чем отличаются ID token при запросе `/v2/oauth/token` и `/v2/oauth/user-info`?

ID token при запросе /v2/oauth/token содержит информацию об авторизации Пользователя и используется для его валидации.

ID token при запросе /v2/oauth/user-info содержит информацию о Пользователе и организации.

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