Авторизация пользователя

Схема авторизации

Контуры для авторизации пользователей

Для авторизации (/v2/oauth/authorize) смс пользователя необходимо отправлять запрос на:

  • тестовый контур https://edupir.testsbi.sberbank.ru:9443
  • промышленный контур https://sbi.sberbank.ru:9443

Для авторизации (/v2/oauth/authorize) токен пользователя необходимо отправлять запрос на:

  • тестовый контур http://localhost:28016
  • промышленный контур http://localhost:28016

Для обращения к ресурсам /v2/oauth/token, /v1/oauth/user-info, /v1/change-client-secret необходимо отправлять запрос на:

  • тестовый контур https://edupirfintech.sberbank.ru:9443
  • промышленный контур https://fintech.sberbank.ru:9443

Алгоритм авторизации пользователя

1. Для работы токен пользователей, на тестовом стенде, необходимо получить VPNKeyTLS-токен у своего менеджера или написать на fintech_API@sberbank.ru .

2. Авторизация в токене происходит после запуска .exe файла в токене и ввода ПИН-кода. Список ПИН-кодов направляется клиенту после передачи токена в электронном виде.

3. После авторизации в интерфейсе токена необходимо выбрать БС EDUPIR (бизнес система тестового стенда EDUPIR) и авторизоваться в СББОЛ.

4. Для возможности подписывать документы необходимо выпустить сертификат ЭП:

4.1. Через интерфейс СББОЛ по документации Как выпустить сертификат электронной подписи без визита в банк .
4.2. Через SberBusiness API по документации Криптографические ресурсы .

5. После создания запроса необходимо отправить информацию в поддержку supportdbo2@sberbank.ru, для регистрации сертификата в УЦ Банка, в формате:

  • Стенд:EDUPIR;
  • ClientId и логин тестового пользователя;
  • BicryptID (КУЦ + номер сертификата);
  • Логин владельца сертификата или название организации;
  • Дата отправки запроса на сертификат;
  • Текст/Комментарий: (при необходимости).

6. После регистрации в УЦ поступит ответ от supportdbo2@sberbank.ru о готовности сертификата.

7. Необходимо активировать сертификат:

7.1. Через интерфейс СББОЛ по документации Как выпустить сертификат электронной подписи без визита в банк.

7.2. Через SberBusiness API по документации Криптографические ресурсы.

8. Cертификат активирован и готов к работе.

Запрос на авторизацию

Для получения возможности работы пользователя через ваш сервис необходимо получить разрешение на выполнение операции от имени пользователя СББОЛ - пройти авторизацию. Для этого необходимо перенаправить пользователя на oauth-сервер SberBusiness ID через запрос /v2/oauth/authorize.

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

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

Наименование Описание
scope Должен содержать обязательный параметр «openid» и через пробел перечисляются scope-ы доступных claim и сервисов, полученных от менеджера партнера при регистрации приложения (обязательный параметр при обращении к ресурсу)
response_type Тип запроса (значение должно быть всегда «code» согласно требованию по обеспечению безопасности, разрешающее использовать исключительно Auth Code Flow (обязательный параметр))
client_id Банковский идентификатор сервиса полученный от менеджера при регистрации приложения (обязательный параметр)
state Параметр для предотвращения CSRF-атак (обязательный параметр)
nonce Значение используется для защиты от атак с повторением токенов (указанное в запросе значение должно соответствовать nonce-значению, возвращаемому в ответе, при этом значение nonce должно быть уникальным в сеансе пользователя и сложным для угадывания (обязательный параметр))
redirect_uri Ссылка на страницу сервиса, на которую необходимо перенаправить пользователя после успешной авторизации (обязательный параметр, должен быть одинаковым в запросе /authorize и /token)
code_challenge Код вызова, полученный из кода проверки (code_verifier) путем применения метода преобразования code_challenge_method (необязательный параметр)
code_challenge_method Метод преобразования, который был применен к коду проверки (code_verifier), для получения значения кода вызова (code_challenge) (необязательный параметр)
location (read only) Значение redirect_uri для client_id, указанного в запросе авторизации. Если в запросе авторизации указан неверный client_id или redirect_uri, то произойдет переадресация на форму авторизации
сode (read only) Значение кода авторизации. Значение кода авторизации формируется произвольно в формате UUID (случайное значение) плюс «1» или «2» через дефис, например, CD6A56FD-A9C7-4152-AA1D-FA57E550F6AC-2

Формирование параметра State

Параметр служит для защиты от CSRF-атак. Для каждого сервиса в банке указывается ссылка на страницу сервиса, на которую необходимо перенаправить пользователя из банка после успешной авторизации (redirect_uri). При поступлении на redirect_uri запроса с кодом авторизации сервис должен проверять, что обмен данными происходит в рамках инициированного им самим взаимодействия. Значение State должно быть защищено от подбора и храниться таким образом, чтобы его не мог изменить никто, кроме сервиса. Рекомендуется использовать идентификатор сессии в сервисе или один из его производных (например, хэш этого идентификатора), при этом может использоваться любой другой механизм генерации случайного значения достаточной длины для предотвращения подбора. В общем случае оптимально использовать строку длиной не менее 36 символов с проверкой регистра.

Формирование параметра Nonce

Параметр служит для защиты от replay-атак, то есть для предотвращения обработки одного и того же запроса несколько раз. Значение Nonce должно быть защищено от подбора и храниться таким образом, чтобы его не мог изменить никто, кроме сервиса. Рекомендуется использовать случайное значение, сохраняемое в сессии пользователя в сервисе. Для повторного запроса это значение должно заменяться новым. В общем случае оптимально использовать строку длиной не менее 10 символов с проверкой регистра.

Формирование хоста для отправки запроса Authorization Code

В зависимости от типа пользователя алгоритм формирования хоста для запросов авторизации должен быть различным:

Указанные выше значения хостов приведены для примера. Реальные значения сообщаются по не автоматизируемым каналам.

Оферта

Для взаимодействия с сервисами пользователю необходимо подписать оферту, в которой указано к каким данным и на какой срок предоставлен доступ сервису. При подписании Оферты, пользователь в явном виде указывает доступность счетов. После получения банком запросов со стороны сервиса, касающихся пользовательских данных, выполняется проверка наличия между сервисом и пользователь активной оферты, а при её отсутствии или истечения срока действия сервису возвращается сообщение об ошибке доступа к данным пользователя. Для возобновления работы с данными пользователя необходимо переадресовать пользователя на форму авторизации с запросом /authorize.

При отправке запроса необходимо экранировать специальные символы, если сформированная ссылка открывается напрямую в браузере, экранирования не требуется. Время жизни авторизационного кода 120 секунд.

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

Пример запроса Пример ответа
GET https://edupir.testsbi.sberbank.ru:9443 /ic/sso/api/v2/oauth/authorize?scope=openid PAY_DOC_RU inn email&response_type=code&client_id=74617&state=af0ifjsldkj&nonce=n-0S6_WzA2Mj&redirect_uri=https%3A%2F%2example.ru HTTP/1.1 302 Found https://example.ru/?code=f710576d-7263-4ec6-a01b-8404aca2850d-1&state=af0ifjsldkj&nonce=n-0S6_WzA2Mj

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

Пример запроса Пример ответа
GET https://edupir.testsbi.sberbank.ru:9443 /ic/sso/api/v2/oauth/authorize?scope=openid PAY_DOC_RU inn email&response_type=code&client_id=74617&state=af0ifjsldkj&nonce=n-0S6_WzA2Mj&redirect_uri=https://example.ru HTTP/1.1 302 Found https://example.ru/?code=f710576d-7263-4ec6-a01b-8404aca2850d-1&state=af0ifjsldkj&nonce=n-0S6_WzA2Mj

В случае обнаружения ошибок client_id и redirect_uri банк сформирует ответ HTTP 400 с ошибкой invalid_grant и описанием:

  • Redirect uri https://example.ru is invalid - неверный redirect_uri
  • Invalid client secret for authz code 'хххххххх-хххх-хххх-хххх-хххххххххххх-х'

В случае если банк вернёт ответ с ошибкой авторизации, сервис должен корректно его обработать. Так как первый шаг взаимодействия (аутентификация) осуществляется через браузер пользователя, банк вернёт HTTP ответ 302 Found. Это необходимо для того, чтобы сервис имел возможность обработать ошибку и отобразить пользователю необходимую ему страницу, например, страницу авторизации (рекомендовано).

Список доступных claim

Наименование Описание
active Признак активности пользователя
sid2 Идентификатор сессии токена
sbbol Признак использования «Дизайн СББОЛ 3.0»
sub Хэш идентификатора пользователя
iss URL СББОЛ
aud Идентификатор внешнего сервиса
dboContracts Договоры обслуживания организации
name Фамилия Имя Отчество
inn ИНН организации
email Адрес электронной почты
phone_number Номер телефона
HashOrgId Хэш от идентификатор организации (orgId)
orgId Идентификатор организации в СББОЛ
orgGuid Глобальный идентификатор организации
orgKpp КПП
orgFullName Название компании
OrgName Наименование организации
orgOgrn ОГРН компании
orgOkpo ОКПО организации
orgOktmo Общероссийский классификатор территорий муниципальных образований
orgActualAddress Фактический адрес компании
orgJuridicalAddress Юридический адрес компании
accounts Счет, БИК, Кор. счет компании.
Примечание: не заполняется при запросе Партнером информации о пользователе своей организации
terBank Полное наименование подразделения кредитной организации
offerExpirationDate Дата окончания оферты
userPosition Должность
userRoles Список роли пользователя
userSignatureType Тип подписи
userGuid Идентификатор пользователя клиента, который обратился к сервису
userId Внутренний идентификатор пользователя
userGroups Группы пользователя
sbbol3 Признак использования клиентом нового дизайна СББОЛ 3.0
userCryptoType Тип криптопрофиля
tbIdentCode Код территориального банка
individualExecutiveAgency Признак Единоличный Исполнительный Орган
inquiryOrder Признак доступности у пользователя функциональности получения справок
isIdentified Признак идентификации пользователя
offerSmartCredit Предодобренные предложения по смарт кредитам
shortName Сокращенное название компании
summOfferSmartCredit Сумма предодобренного предложения по смарт-кредитам
resident Признак является организация резидент/нерезидент
orgBusinessSegment Бизнес сегмент. Возможные значения: 02-Микро бизнес (микро), 03-Малый бизнес, 04-Средний бизнес, 05-Крупный бизнес, 06-Крупнейший бизнес, 07-Клиенты машиностроения (ОПК), 08-Рег. госсектор, 09-БМО, 10-Фин. институты, 999-Не найдено сегмента в CRM Корпоративном
buyOnCreditMmb Признак возможности покупки в кредит на сайте партнера
orgLawFormShort Организационно-правовая форма (принятое сокращение)
branch Сокращенные наименования подразделений, адреса подразделений, номера подразделений
orgIndustryInfo Отрасль организации
orgRegDateINN Дата регистрации ИНН
orgRegDateOGRN Дата регистрации ОГРН
orgKindActivityInfo Информация о виде деятельности организации
orgBusinessSegmentName Наименование бизнес-сегмента

Список доступных сервисов

Наименование операции Описание
PAY_DOC_RU_INVOICE Выставление счета на оплату по фиксированным реквизитам
GET_CLIENT_ACCOUNTS Получение информации о счетах подключенного клиента
GET_STATEMENT_ACCOUNT Получение выписки по счету клиента
GET_STATEMENT_TRANSACTION Получение печатной формы выписки по одной операции
PAY_DOC_RU Рублёвое платежное поручение
PAYROLL Зарплатная ведомость
FILES Выгрузка/загрузка файлов
CARD_ISSUE Электронный реестр на открытие счетов и выпуск карт
SALARY_AGREEMENT Зарплатный договор
DICT Справочник
SALARY_AGREEMENT_REQUEST Заявка на удаленное подключение Зарплатного проекта
PAYMENTS_REGISTRY Реестр платежей
DEBT_REGISTRY Реестр задолженности
CURRENCY_OPERATION_DETAILS Сведения о валютной операции
PAY_DOC_CUR Валютное платежное поручение
CURR_CONTROL_MESSAGE_TO_BANK Письмо для целей ВК (в банк)
GENERIC_LETTER_TO_BANK Письмо свободного формата (в банк)
CONFIRMATORY_DOCUMENTS_INQUIRY Справка о подтверждающих документах
PAYMENT_REQUEST_OUT Исходящее платежное требование
GET_ADVANCE_ACCEPTANCES Получение сведений о клиентах, подключенных к подпискам и пакетам услуг
GET_PARTNER_OFFERS Получение информации об офертах с внешним сервисом
GET_CRYPTO_INFO Получение криптографической информации
CERTIFICATE_REQUEST Запрос на сертификат
PAY_DOC_RU_INVOICE_ANY Выставление счёта на оплату по свободным реквизитам
CLIENT_TARIFF Актуализация тарифа по подключенным сервисам
GENERIC_LETTER_FROM_BANK Письмо свободного формата (из банка)
CURR_CONTROL_MESSAGE_FROM_BANK Письмо для целей ВК (из банка)
GET_CUSTOMER_INFO Получение информации по клиенту (реквизиты организации и пользователей)
GET_CRYPTO_INFO_EIO Получение сертификатов открытых ключей электронной подписи пользователей организации (ЕИО)
GET_CLIENTS_CHANGES Получение списка клиентов, по которым произошли изменения
EI_FLAG_MASTER_CONNECT Запрос на изменение признака регистрации пользователя в E-Invoicing
EI_DOC_COUNT Уведомление об актуальном количестве документов в E-Invocing
GET_CLIENTS_ADDED Получение списка клиентов, подключенных в ВСП
GET_STATEMENT_RUR_ID Получение рублевой операции по выписке
ORDER_MANDATORY_SALE Распоряжение на перевод с транзитного счета
CURRENCY_NOTICES Уведомление о поступлении денежных средств на транзитный валютный счет
BANK_CONTROL_STATEMENT Ведомость банковского контроля (ВБК в банк)
CURR_BUY Покупка и конверсия валюты
CURR_SELL Продажа валюты
EI_CLOSING_DOCUMENTS Наличие закрывающих документов по платежному поручению
CASH_HOLD Сервисы холдирования денежных средств на расчетном счете клиента
BANK_CONTROL_STATEMENT_CHANGE_APPLICATION Заявление о внесении изменений в I раздел ВБК
CRYPTO_CERT_REQUEST_EIO Запрос на выпуск сертификата для ЕИО
CLIENT_ACCRUAL Начисление платы за пользование сервисом
ENCASH_DOCUMENTS Получение и передача информации по документам инкассации
CONTRACT_CLOSE_APPLICATION Заявление о снятии с учёта контракта (кредитного договора)
PAYMENT_REQUEST_IN Входящее платёжное требование
COLLECTION_ORDERS Рублевое инкассовое поручение
ACCEPTANCE_LETTER Заявление об акцепте (отказе от акцепта)
GET_CORRESPONDENTS Получение списка контрагентов
WEBHOOK Заявка на получение уведомлений о событии
SELF_ENCASHER_NEW_PASSWORD Генерация нового пароля вносителя самоинкассации
SELF_ENCASHER_BLOCK Блокировка вносителя самоинкассации
SELF_ENCASHER_REQUEST Заявления на создание нового вносителя самоинкассации
GET_TARIFF_PLANS Получение списка тарифных планов пользователя организации
GET_TARIFF_PLANS_LIST_AVAILABLE Получение списка тарифных планов, доступных партнерскому сервису
CREDIT_REQUEST Запрос на создание заявок на кредит
CORRESPONDENT_CUR_ADDITIONAL Дополнительная информация по валютному контрагенту (бенефициару)
TARIFF_PLAN_MANAGEMENT Запрос на подключение/отключение тарифного плана организации в формате JSON
TARIFF_PLAN_MANAGEMENT_JWS Запрос на подключение/отключение тарифного плана организации в формате JWS
EXTERNAL_SYSTEM_AUTH_PROFILE Авторизационные данные пользователя во внешних системах
GET_REQUEST_STATISTICS Запрос на получение статистики по количеству запросов в API
NOTIFY_MESSAGES Запрос на отправку уведомления клиенту
PAY_DOC_RU_INVOICE_BUDGET Рублёвое платежное поручение с бюджетным реквизитами, легкая форма
PAYMENT_SUBSCRIPTION Списание средств по подписке
GET_CLIENTS_ADDED_VSP Получение списка клиентов, подключенных в ВСП за период
SBERRATING_VALUES Запрос на изменение параметров услуги «Внутренние источники»
SBERRATING_VALUES_GET Детальная информация по CберРейтинг
GET_CREDIT_OFFERS Получение информации по кредитным предложениям
CORPORATE_CARD_REQUEST Создание заявления на открытие бизнес-карты
CORPORATE_CARDS Получение информации по бизнес-картам

Получение авторизационного токена

После получения кода авторизации и проверки корректности успешного ответа необходимо запросить авторизационный токен Access Token, который требуется для доступа к своим счетам. Для этого необходимо использовать запрос /v2/oauth/token. Авторизационный ключ Access Token возвращается вместе с ID Token, содержащим пользовательские идентификационные данные, и ключом Refresh Token.

Шаги:

  1. Получить код авторизации
  2. Отправить запрос
  3. Декодировать ID Token
  4. Актуализация авторизационного токена
  5. Проверить подпись Банка

Обмен кода авторизации на Access Token происходит через меж серверные каналы (REST-сервис), поэтому значение хоста не зависит от типа пользователя (userType). В случае возникновения ошибки при попытке получить AccessToken по коду авторизации по каким-либо причинам (например, неправильно передан client_secret) код авторизации удаляется и все дальнейшие попытки получить по нему AccessToken (даже с корректными параметрами) будут приводить к ошибке с текстом "Unknown code = <код_авторизации>". Запрос должен производиться только методом POST с типом данных application/x-www-form-urlencoded.

Модель запроса и ответа

Наименование Описание
grant_type Значение должно быть "authorization_code" (обязательный параметр)
code Значение кода авторизации (обязательный параметр)
client_id Банковский идентификатор сервиса полученный от менеджера при регистрации приложения (обязательный параметр )
client_secret Авторизационный ключ сервиса (обязательный параметр).
Генерируется банком в момент заведения сервиса и передается оффлайн. После получения требуется, в обязательном порядке, сменить client_secret методом /v1/change-client-secret или в Личном кабинете SberBusinessAPI (FintechAPI). В дальнейшем, требуется менять client_secret до истечения срока жизни, составляющий 40 дней
redirect_uri Ссылка на страницу сервиса, на которую необходимо перенаправить пользователя после успешной авторизации (обязательный параметр, должен быть одинаковым в запросе /authorize и /token)
code_verifier Код проверки, на основе которого получили код вызова (code_challenge) путем применения метода преобразования code_challenge_method (необязательный параметр)
access_token Авторизационный токен к данным организации
refresh_token Токен обмена
token_type Всегда равен «Bearer»
expires_in Время жизни access_token в секундах
id_token Закодированный в Base64URL набор атрибутов пользователя, необходимых для идентификации пользователя. Атрибуты разделены символами «.», каждый необходимо декодировать отдельно
scope Должен содержать обязательный параметр «openid» и через пробел перечисляются scope-ы доступных claim и сервисов, полученных от менеджера партнера при регистрации приложения (обязательный параметр при обращении к ресурсу)

При отправке запроса необходимо экранировать специальные символы, если сформированная ссылка открывается напрямую в браузере, экранирования не требуется. Время жизни авторизационного токена 60 минут.

Пример запроса
POST /ic/sso/api/v2/oauth/token

https://edupirfintech.sberbank.ru:9443

Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code

&code= CD6A56FD-A9C7-4152-AA1D-FA57E550F6AC-2

&client_id=1001

&client_secret=Ac03df04fff8

&redirect_uri=https%3A%2F%2Fclient.example.ru%2Fcb
Пример ответа
HTTP/1.1 200 OK

Content-Type: application/json

Cache-Control: no-store

Pragma: no-cache

{

"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": "eyJhbGciOiJnb3N0MzQtMTAuMjAxMiJ9.eyJzdWIiOiIwZDYxNTI3NDRlNDhkMTU4Y2UwMWQ3ZDQwZTdjNzUwYmZhMT

VmMWVhY2NkOTQ3YmYwYTU0NzRhNDkwMGMyZTdjIiwiaXNzIjoiaXNzLWRlZmF1bHQtdmFsdWUiLCJhdWQiOiIxMTQzIiwiZXhwIjox

NTE4NzAxMDcxLCJpYXQiOjE1MTg3MDA3NzEsImF1dGhfdGltZSI6MTUxODcwMDc1NiwiYWNyIjoibG9hLTMiLCJhbXIiOiJ7cHdkLCBtY2

EsIG1mYSwgb3RwLCBzbXN9IiwiYXpwIjoiMTE0MyIsIm5vbmNlIjoiN2JlNjZhYzktZDA3Yy00OTY3LWFkZWQtY2EyNzBhMjdlOWU4In0=.

EdiC77+9bO+/vRzvv71677+977+977+9eAXvv73vv73vv71E77+977+977+977+9Re+/ve+/vTNbbdm0Bu+/vRY/eO+/vRvvv70q77+

977+9LO+/vU4iZO+/vSNF0oFy77+977+977+9GQnvv73vv70v77+9QO+/vXk="

}

В случае обнаружения ошибок client_id и redirect_uri банк сформирует ответ HTTP 400 с ошибкой invalid_grant и описанием:

  • Redirect uri https://example.ru is invalid - неверный redirect_uri
  • Invalid client secret for authz code 'хххххххх-хххх-хххх-хххх-хххххххххххх-х'

В случае если банк вернёт ответ с ошибкой авторизации, сервис должен корректно его обработать. Так как первый шаг взаимодействия (аутентификация) осуществляется через браузер пользователя, банк вернёт HTTP ответ 302 Found. Это необходимо для того, чтобы сервис имел возможность обработать ошибку и отобразить пользователю необходимую ему страницу, например, страницу авторизации (рекомендовано).

При получении ответа сервис должен проверить его корректность в соответствии со спецификацией. Рекомендации по проверке ответа на запрос Access Token описаны в спецификациях:

Декодирование ID Token

При необходимости декодировать ID Token следует воспользоваться алгоритмом Base64URL Encoding. Согласно спецификации JSON Web Token (JWT) ID Token должен быть представлен структурой вида:

  • Алгоритм подписи (по сертификату технологического криптопрофиля Банка, который можно получить запросом /crypto), Header(Заголовок)
  • ID_token, Payload (Полезная нагрузка)
  • Электронная подпись

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

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

eyJhbGciOiJnb3N0MzQtMTAuMjAxMiJ9.eyJzdWIiOiJ

hMWNhOGYyMTQ4MDc1M2IyMzI1MTZiYzk4NmNiZ

mM4Yjc5MjNiYWI3ODczODQzZWM0ZjQ1MTA4MmI

0YTg3NjFjIiwiaXNzIjoiaHR0cDovL3NidC1vYWZzLTYz

ODo5MDgwL2ljZGsiLCJhdWQiOiIyMDg1IiwiZXhwIjox

NTE4Njg2MDI1LCJpYXQiOjE1MTg2ODU3MjUsImF1d

GhfdGltZSI6MTUxODY4NTM4NSwiYWNyIjoibG9hLT

MiLCJhbXIiOiJ7cHdkLCBtY2EsIG1mYSwgb3RwLCBz

bXN9IiwiYXpwIjoiMjA4NSIsIm5vbmNlIjoiOTc2MjgwY

2ZmZTg5In0=.AGnvv73vv73vv71iFGM977+9We+/vU

vvv73vv704Re+/ve+/vWnvv73vv71y77+9dQh+77+9

GR1377+9Ml8T77+9ae+/vTbvv73Gle+/vU1t77+977+

977+977+97LKk77+9XyQRPFEl77+977+9

Пример декодированного ответа

{
   {
      "typ":"JWT",
      "alg":"gost34.10-2012"
   },
   {
      "sub":"a1ca8f21480753b232516bc986cbfc8b7923bab7873843ec4f451082b4a8761c",
      "iss":"https://edupirfintech.sberbank.ru:9443",
      "aud":"2085",
      "exp":1518686025,
      "iat":1518685725,
      "auth_time":1518685385,
      "acr":"loa-3",
      "amr":"{pwd, mca, mfa, otp, sms}",
      "azp":"2085",
      "nonce":"976280cffe89"
   }
}

AGnvv73vv73vv71iFGM977+9We+/vUvvv73vv704Re+/ve+/vWnvv73vv71y77+9dQh+77+9

GR1377+9Ml8T77+9ae+/vTbvv73Gle+/vU1t77+977+

977+977+97LKk77+9XyQRPFEl77+977+9
Наименование Описание
iss URL сервиса, сформировавшего ID Token
sid2 Идентификатор сессии устройства защиты
sub Хэш банковского идентификатора пользователя
aud Идентификатор сервиса, для которого формируется ID Token
nonce Значение параметра nonce из запроса кода авторизации
exp Время, после которого ID Token не принимается для обработки. Формат поля Unix time
iat Время формирования ID Token. Формат поля Unix time
auth_time Время банковской аутентификации пользователя. Формат поля Unix time
acr Уровень аутентификации пользователя: acr=loa-2 (пользователь аутентифицируется с помощью устройства защиты) acr=loa-3 (пользователь использует подтверждение по одноразовому SMS-паролю для аутентификации)
amr Методы аутентификации: Amr=pwd — пользователь аутентифицируется с помощью устройства защиты; amr= {pwd, mca, mfa, otp, sms} — пользователь использует подтверждение по одноразовому SMS-паролю для аутентификации
azp Идентификатор сервиса (рекомендуется проверить идентификатор сервиса, для которого был сформирован полученный ID Token)
HashOrgId Хэш от идентификатора организации, с которой связан пользователь

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

Согласно стандарту OpenID Connect проверка электронной подписи, полученной в ID Token (содержимое ответа ID Tokena после второй точки), выполняется, используя алгоритм, указанный в параметре заголовка JWT alg. Партнеру необходимо проверить подпись сертификатом Банка.

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

Ключ Refresh Token предназначен для получения нового Access Token и Refresh Token в случае компрометации или истечения времени жизни Access Token. Время жизни токена обмена 180 дней.

Модель запроса и ответа

Наименование Описание
grant_type Значение должно быть "refresh_token" (обязательный параметр)
client_id Банковский идентификатор сервиса полученный от менеджера при регистрации приложения (обязательный параметр )
client_secret Авторизационный ключ сервиса (обязательный параметр). Генерируется банком в момент заведения сервиса и передается оффлайн. После получения требуется, в обязательном порядке, сменить client_secret методом /v1/change-client-secret или в Личном кабинете SberBusinessAPI (Fintech API)
refresh_token Токен обмена (обязательный параметр)
scope Должен содержать обязательный параметр "openid" и через пробел перечисляются scope-ы доступных claim и сервисов, полученных от менеджера партнера при регистрации приложения (обязательный параметр при обращении к ресурсу)
Пример запроса
POST /ic/sso/api/v2/oauth/token

Host: edupirfintech.sberbank.ru:9443

grant_type=refresh_token

&refresh_token= 668c708e-865a-42b1-8fe9-846b92b8b14e-1

&client_id=1001

&client_secret=Ac03df04fff8
Пример ответа
Content-Type: application/json

Cache-Control: no-store

Pragma: no-cache

{

"scope": "openid PAYROLL name",

"access_token": "6e55338d-7a7a-4b66-bc78-248d52eeb1dc-1",

"token_type": "Bearer",

"expires_in": 3600,

"refresh_token": "668c708e-865a-42b1-8fe9-846b92b8b14e-1"

}

Рекомендуется обновлять ключи доступа (Access Token/Refresh Token) как минимум один раз за время жизни Refresh Token. В случае если Refresh Token потеряет актуальность (не будет обновлен до истечения времени жизни), сервис сможет получить актуальные ключи доступа только после повторной авторизации пользователя в сервисе через СББОЛ.

Если при обновлении ключей доступа по Refresh Token не был получен ответ из банка, то рекомендуется повторно отправить запрос на актуализацию ключей в течение 1 часа от момента отправки первой попытки, используя тот же Refresh Token. Успешное формирование ответа на стороне банка с новой парой ключей (Access Token/Refresh Token) переводит использованный раннее Refresh Token в статус резервного. Срок жизни резервного Refresh Token составляет 2 часа с момента выпуска новой пары ключей (Access Token/Refresh Token). Для последующих обновлений ключей доступа необходимо использовать Refresh Token из новой пары ключей (Access Token/Refresh Token).

Получение данных о сервисе

Ресурс /v1/oauth/user-info позволяет получать данные о подключенном сервисе (если пользователь "разрешил" сервису доступ к своим данным), которые могут включать в себя информацию об организации пользователя, например:

  • идентификатор организации пользователя (hashOrgId)
  • Наименование организации (orgName)

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

Шаги:

  1. Получить код авторизации
  2. Получить токен авторизации
  3. Отправить запрос

Запрос User Info должен производиться методом GET с использованием заголовка Authorization и передаваемых в нем значения Bearer (всегда должно соответствовать ответу в параметре token_type=) и значения из access_token. При запросе сервисом информации о пользователе своей организации не заполняется claim "accounts".

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

Наименование Описание
Параметры заголовка
Authorization String Access token полученный через SSO. Пример: Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1
Пример запроса
GET/ic/sso/api/v1/oauth/user-info HTTP/1.1

Host: edupirfintech.sberbank.ru:9443

Authorization: Bearer CD6A56FD-A9C7-4152-AA1D-FA57E550F6AC-2

Каждая часть ответа, разделенная точкой, должна декодироваться отдельно.

Пример ответа
HTTP/1.1 200 OK
Content-Type: application/jwt

eyJ0eXAiOiJKV1QiLCJhbGciOiJnb3N0MzQuMTAtMjAxMiJ9.eyJzdWIiOiJkOTI0M2I4NTI2ND

Q5OTZiNjNlNWMyN2Y0ZmI5NTBjMzAyNGIzZGRkZjVjZWFmZmY4MDVlZjhiZmNlNzQwYTJl

IiwiZWtzRXBrSWQiOjAsImlzcyI6Imh0dHA6Ly9zYnQtb2Fmcy02Mzg6OTA4MC9pY2RrIiwiT3

JnTmFtZSI6ItCe0J7QniBcItCf0J7QndCi0JjQpFwiIiwib3JnSWQiOjIyODMzODksImluZGl2aWR

1YWxFeGVjdXRpdmVBZ2VuY3kiOjAsInVzZXJTaWduYXR1cmVUeXBlIjoi0JXQtNC40L3RgdG

C0LLQtdC90L3QsNGPINC_0L7QtNC_0LjRgdGMIiwic3VtbU9mZmVyU21hcnRDcmVkaXQiOj

AsIkhhc2hPcmdJZCI6ImMxOTQ0YTNmOGIzMTMwMjc3MjExZmEyZTZjNmY5YjcyNDdlZTk4

NjU1ZjIyZTRlYjAzNWRiNzk2NjAzODJmOGEiLCJpc0lkZW50aWZpZWQiOmZhbHNlLCJub25

DbGllbnQiOmZhbHNlLCJ1c2VyUG9zaXRpb24iOiIyMjIiLCJkYm9Db250cmFjdHMiOlt7Im51bW

JlciI6IjIyNzM0OTI1MSIsImRhdGUiOiIyMDIwLTA3LTAyIiwiZmluYW5jZUJsb2NrIjpmYWxzZX1dL

CJyZXNpZGVudCI6dHJ1ZSwib2ZmZXJFeHBpcmF0aW9uRGF0ZSI6IjIwMjEtMDktMDZUMTM

6MzY6MzYrMDMwMCIsIm9yZ0d1aWQiOiI5ZTE0MjA2My0xYWFiLTRhNmUtYjkyZS0yZDUxZT

kyNjQ0N2MiLCJpbm4iOiI3NzM1MDkxMjIyIiwib3JnSnVyaWRpY2FsQWRkcmVzcyI6ItCg0J7Qo

dCh0JjQmdCh0JrQkNCvINCk0JXQlNCV0KDQkNCm0JjQrywgMTIzNDU2LCDQsy7QnNC-0Y

HQutCy0LAsINCc0L7RgdC60L7QstGB0LrQuNC5INGALdC-0L0sINGD0LsuINCi0LXRgdGC0L

7QstCw0Y8gMTAxOTgzLCDQtNC-0LwgMSwg0YHRgtGALiAyIiwiYWN0aXZlIjoxLCJvcmdGdW

xsTmFtZSI6ItCe0LHRidC10YHRgtCy0L4g0YEg0L7Qs9GA0LDQvdC40YfQtdC90L3QvtC5INC-

0YLQstC10YLRgdGC0LLQtdC90L3QvtGB0YLRjNGOIiwidGJJZGVudENvZGUiOiIzOCIsInVzZXJ

HdWlkIjoiOTlkNjY0N2YtYjI0Yi00ODg3LTg2NDgtZjViOTBjZmQ1MTc2IiwidXNlcklkIjoxNjYxMTA5

LCJ0ZXJCYW5rIjoi0JzQvtGB0LrQvtCy0YHQutC40Lkg0JHQsNC90Log0KHQsdC10YDQsdCw

0L3QutCwINCg0KQiLCJvcmdVbmNvbmZpcm1lZCI6ZmFsc2UsImF1ZCI6Ijc2NzA0IiwidXNlclJv

bGVzIjpbImJhbmtDbGllbnQiXSwidXNlckNyeXB0b1R5cGUiOiJTTVMiLCJ1c2VyR3JvdXBzIjoi0K

DRg9C60L7QstC-0LTQuNGC0LXQu9GMIiwic2Jib2wzIjp0cnVlLCJvZmZlclNtYXJ0Q3JlZGl0Ijp

mYWxzZSwibmFtZSI6ItCf0L7QvdGC0LjRhNC-0LIg0KfQtdGC0YvRgNC1INCf0L7QvdGC0LjRhNC-

0LLQuNGHIiwiaW5xdWlyeU9yZGVyIjp0cnVlLCJwaG9uZV9udW1iZXIiOiI3OTY0NTYxNjU1NiIsImFj

Y291bnRzIjpbeyJjb3JyQWNjb3VudE51bWJlciI6IjMwMTAxODEwNDAwMDAwMDAwMjI1IiwiYWNjb3

VudE51bWJlciI6IjQwNzAyODEwMTU0OTg0NjUxNTk2IiwiYmljIjoiMDQ0NTI1MjI1In0seyJjb3JyQWNj

b3VudE51bWJlciI6IjMwMTAxODEwNDAwMDAwMDAwMjI1IiwiYWNjb3VudE51bWJlciI6IjQwNzAyOD

EwNTM4MDAwMDAxMDk5IiwiYmljIjoiMDQ0NTI1MjI1In0seyJjb3JyQWNjb3VudE51bWJlciI6IjMwMT

AxODEwNDAwMDAwMDAwMjI1IiwiYWNjb3VudE51bWJlciI6IjQwNzAyODEwODc4OTQ2NTQ4OTQ5

IiwiYmljIjoiMDQ0NTI1MjI1In0seyJjb3JyQWNjb3VudE51bWJlciI6IjMwMTAxODEwNDAwMDAwMDAw

MjI1IiwiYWNjb3VudE51bWJlciI6IjQyMTAxODEwNzQ3NDg5NDU2MjE1IiwiYmljIjoiMDQ0NTI1MjI1In1dfQ.

GO59WE1mtVcz0XYkwh0IhIZWVoABoAcWAyI5SxGLhwZxUK0uImRzYCuP9kdx8Br5lqgLjWN7xiAd9txncI-7Rg
Пример декодированного ответа
{
   "typ":"JWT",
   "alg":"gost34.10-2012"
}{
   "sub":"d9243b852644996b63e5c27f4fb950c3024b3dddf5ceafff805ef8bfce740a2e",
   "eksEpkId":0,
   "iss":"http://edupirfintech.sberbank.ru:9443",
   "OrgName":"ООО \"ПОНТИФ\"",
   "orgId":2283389,
   "individualExecutiveAgency":0,
   "userSignatureType":"Единственная подпись",
   "summOfferSmartCredit":0,
   "HashOrgId":"c1944a3f8b3130277211fa2e6c6f9b7247ee98655f22e4eb035db79660382f8a",
   "isIdentified":false,
   "nonClient":false,
   "userPosition":"222",
   "dboContracts":[
      {
         "number":"227349251",
         "date":"2020-07-02",
         "financeBlock":false
      }
   ],
   "resident":true,
   "offerExpirationDate":"2021-09-06T13:36:36+0300",
   "orgGuid":"9e142063-1aab-4a6e-b92e-2d51e926447c",
   "inn":"7735091222",
   "orgJuridicalAddress":"РОССИЙСКАЯ ФЕДЕРАЦИЯ, 123456, г.Москва, Московскийр-он, ул. Тестовая 101983, дом 1, стр. 2",
   "active":1,
   "orgFullName":"Общество с ограниченной ответственностью",
   "tbIdentCode":"38",
   "userGuid":"99d6647f-b24b-4887-8648-f5b90cfd5176",
   "userId":1661109,
   "terBank":"Московский Банк Сбербанка РФ",
   "orgUnconfirmed":false,
   "aud":"76704",
   "userRoles":[
      "bankClient"
   ],
   "userCryptoType":"SMS",
   "userGroups":"Руководитель",
   "sbbol3":true,
   "offerSmartCredit":false,
   "name":"Понтифов Четыре Понтифович",
   "inquiryOrder":true,
   "phone_number":"79645616556",
   "accounts":[
      {
         "corrAccountNumber":"30101810400000000225",
         "accountNumber":"40702810154984651596",
         "bic":"044525225"
      },
      {
         "corrAccountNumber":"30101810400000000225",
         "accountNumber":"40702810538000001099",
         "bic":"044525225"
      },
      {
         "corrAccountNumber":"30101810400000000225",
         "accountNumber":"40702810878946548949",
         "bic":"044525225"
      },
      {
         "corrAccountNumber":"30101810400000000225",
         "accountNumber":"42101810747489456215",
         "bic":"044525225"
      }
   ]
}

Согласно спецификации JSON Web Token (JWT) User Info должен быть представлен структурой вида:

  • Алгоритм подписи (Определяется по сертификату технологического криптопрофиля Банка, который можно получить запросом /crypto), Header (Заголовок);
  • User-info, Payload (Полезная нагрузка);
  • Электронная подпись.

При получении ответа сервис должен его декодировать и опционально проверить электронную подпись ответа. Система отправит ответ HTTP 200 OK с типом данных jwt. User-info необходимо декодировать c помощью алгоритма base64url Encoding (по спецификации JWT). Преобразование BASE64URL, отличается от BASE64. Условно алгоритм можно представить следующим образом: Base64Url(x) := Base64(x).Split(‘=’)[0].Replace(‘+’, ’-’).Replace(‘/’, ’_’). Здесь функция Split(x), разбивает строку на части ([i] означает взятие i–ой части), используя символ разделитель x, функция Replace(x,y) заменяет все вхождения символа x на символ y. В user-info включаются обязательные системные и дополнительные атрибуты пользователя для сервиса. Обязательные системные атрибуты: sub, iss, aud. Проверка электронной подписи (3-я часть ответа) является опциональной и может выполняться сервисом при необходимости проверки неизменности данных user-info.

Список доступных параметров User-info:

Наименование Описание
sid2 Идентификатор сессии токена
sub Хэш идентификатора пользователя
iss URL СББОЛ
aud Идентификатор внешнего сервиса
name Фамилия Имя Отчество
inn ИНН организации
email Адрес электронной почты
phone_number Номер телефона
HashOrgId Хэш от идентификатор организации (orgId)
orgId Идентификатор организации в СББОЛ
orgKpp КПП
orgFullName Название компании
OrgName Наименование организации
orgOgrn ОГРН компании
orgOkpo ОКПО организации
orgOktmo Общероссийский классификатор территорий муниципальных образований
orgActualAddress Фактический адрес компании
orgJuridicalAddress Юридический адрес компании
accounts Счет, БИК, Кор. счет компании. Примечание: не заполняется при запросе Партнером информации о пользователе своей организации
terBank Полное наименование подразделения кредитной организации
offerExpirationDate Дата окончания оферты
userPosition Должность
userRoles Список роли пользователя
userSignatureType Тип подписи
userGuid Идентификатор пользователя клиента, который обратился к сервису
userId Внутренний идентификатор пользователя
userGroups Группы пользователя
sbbol3 Признак использования клиентом нового дизайна СББОЛ 3.0
userCryptoType Тип криптопрофиля
tbIdentCode Код территориального банка
individualExecutiveAgency Признак Единоличный Исполнительный Орган
inquiryOrder Признак доступности у пользователя функциональности получения справок
isIdentified Признак идентификации пользователя
offerSmartCredit Предодобренные предложения по смарт кредитам
summOfferSmartCredit Сумма предодобренного предложения по смарт-кредитам
resident Признак является организация резидент/нерезидент
orgBusinessSegment Бизнес сегмент. Возможные значения: 02-Микро бизнес (микро), 03-Малый бизнес, 04-Средний бизнес, 05-Крупный бизнес, 06-Крупнейший бизнес, 07-Клиенты машиностроения (ОПК), 08-Рег. госсектор, 09-БМО, 10-Фин. институты, 999-Не найдено сегмента в CRM Корпоративном.
buyOnCreditMmb Признак возможности покупки в кредит на сайте партнера
orgLawFormShort Организационно-правовая форма (принятое сокращение)
isСorpCardHolder Наличие у клиента активной бизнес-карты
creditLineAvailableSum Сумма остатка действующей кредитной линии
hasActiveCreditLine Наличие активной кредитной линии у клиента

Изменение Client secret

Client_secret можно сменить в Личном кабинете SberBusinessAPI (FintechAPI) или через /v1/change-client-secret.
Смена client-secret должна выполняться не реже 40 дней, иначе он заблокируется, и SberBusinessAPI будет недоступен. Разблокировать client_secret можно через отделение банка, менеджера или Личный кабинет SberBusinessAPI.

Начальное значение client_secret генерируется Банком и передается вместе со значением client_id при первичной регистрации. После получения требуется сменить client_secret.

Шаги:

  1. Получить AccessToken
  2. Отправить запрос

Для смены client_secret необходимо отправить POST-запрос (/v1/change-client-secret). В запросе необходимо передать авторизационный токен к собственным данным (Access Token), старое значение client_secret, новое значение new_client_secret и идентификатор сервиса client_id.

Модель запроса

Наименование Описание
Authorization String Access token собственной организации, полученный через SSO. Пример: Bearer daf9a14c-821d-4bde-9c10-0e56e63d54a0-1
client_secret String Старое значение ClientSecret (client_secret >= 8 символов и <= 256 символов
new_client_secret String Новое значение ClientSecret (client_secret >= 8 символов и <= 256 символов
client_id String Идентификатор сервиса
Пример запроса
curl -X POST --header 'Content-Type : application/x-www-form-urlencoded' --header 'Accept: application/x-www-form-urlencoded'

'https://edupirfintech.sberbank.ru:9443/ic/sso/api/v1/change-client-secret?

access_token=daf9a14c-821d-4bde-9c100e56e63d54a0-1

&client_secret=987654322&new_client_secret=987654321&client_id=8213'
Модель ответа
clientSecretExpiration Number Период (в днях) действия Client Secret = 40

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

Код возврата Описание Причина возникновения
200 ОК
Успешный код возврата
302 invalid_grant
Unknown code = хххххххх-хххх-хххх-хххх-хххххххххххх-х Указан неверный код авторизации: а) несуществующий код авторизации; б) код авторизации, время жизни которого истекло; в) код авторизации, ранее использованный для получения access_token
Invalid client secret for authz code 'хххххххх-хххх-хххх-хххх-хххххххххххх-х Указан неверный client_secret или client_id или client_secret и client_id
Redirect uri 'https://.ru' is invalid Неверный redirect_uri
Unknown refresh token = хххххххх-хххх-хххх-хххх-хххххххххххх-х Указан неверный refresh_token:
а) несуществующий refresh_token;
б) refresh_token, время жизни которого истекло;
в) refresh_token, ранее использованный для получения нового access_token и refresh_token
Invalid client secret for refresh token хххххххх-хххх-хххх-хххх-хххххххххххх-х Указан неверный client_secret (Запрос на получение новых access_token и refresh_token по действующему refresh_token)
Ext service for authz code хххххххх-хххх-хххх-хххх-хххххххххххх-х is blocked Внешний сервис заблокирован в системе (запрос на получение access_token и refresh_token по коду авторизации).
Неверно указан адрес sso для подключения
unsupported_grant_type
Grant type 'authorization_code1' is not supported Указан неверный тип кода авторизации (должен быть authorization_code)
Grant type 'refresh_token1' is not supported Указан неверный тип refresh_token (должен быть refresh_token)
unauthorized_client
Unknown client_id = 'ХХХХ' Указан неверный client_id или client_id и client_secret (запрос на получение новых access_token и refresh_token по действующему refresh_token)
Client 'ХХХХ' is blocked Внешний сервис заблокирован в системе (запрос на новых получение access_token и refresh_token по refresh_token)
400 invalid_request
Invalid code verifier Указан неверный код проверки
bad_request
Неверный формат client_secret Длина client_secret меньше 8 или больше 256 символов.
Значение new_client_secret совпадает с client_secret
unsupported_token_type
Тип токена не поддерживается Указан неверный тип токена
401 unauthorized
Неверный формат access_token Указан некорректный или просроченный access_token.
Access_token выдан пользователю не принадлежащий к организации предоставляющий сервис
406 not_acceptable
В соответствии с текущими настройками сервиса с clientId=" + clientId + " необходимо запрашивать ответ в формате JWE Compact Serialization В запросе был передан http-заголовок Accept со значением application/json, но в настройках сервиса установлен признак шифрования
В соответствии с текущими настройками сервиса с clientId=" + clientId + " необходимо запрашивать ответ в формате JSON В запросе был передан http-заголовок Accept со значением application/jose, но в настройках сервиса не установлен признак шифрования
500 unknown_exception
Внутренняя ошибка сервера
503 service_unavailable
Сервис временно недоступен Технологическое окно

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

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