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

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

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

Для авторизации (/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 Ссылка на страницу сервиса, на которую необходимо перенаправить пользователя после успешной авторизации (обязательный параметр, должен быть одинаковым, включая все GET параметры, в запросе /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 Предодобренные предложения по смарт кредитам
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.

Для работы с счетами ГО сервису необходимо получить access_token под пользователем ГО. Время жизни авторизационного токена 60 минут.

Шаги

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. В дальнейшем, требуется менять client_secret до истечения срока жизни, составляющего 40 дней.
redirect_uri Ссылка на страницу сервиса, на которую необходимо перенаправить пользователя после успешной авторизации (обязательный параметр, должен быть одинаковым, включая все GET параметры, в запросе /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.eyJzdWIiOiIwZDYxNTI3NDRlNDhkMTU4Y2UwMWQ3ZDQwZTdjNzUwYmZhMTQO+/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 Хэш от идентификатора организации, с которой связан пользователь
Если банку не удаётся предоставить какие-то данные, такой атрибут отсутствует в ответе (не должно быть атрибутов со значением NULL).

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

Согласно стандарту 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.
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"
            }
         ]
      }
   }
}

Структура User Info

Согласно спецификации 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 или через /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 Внешний сервис заблокирован в системе (запрос на новых получение accesstoken и `refreshtokenпо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
Сервис временно недоступен Технологическое окно