Авторизация пользователей
Access Token
Все запросы в Sber API выполняются от имени конкретного пользователя СберБизнес. Для этого необходимо получить право доступа (Access Token) от такого пользователя на получение и работу с его данными по следующей схеме:
- Сформируйте ссылку авторизации в соответствии с правилами,
- Отправьте запрос на получение кода авторизации,
- В случае, если запрос направляется не по своей организации, то пользователь подписывает согласие на передачу данных,
- Обменяйте полученный код авторизации на токен доступа,
- Передавайте токен доступа (access_token) пользователя в заголовке Header в параметре Authorization при каждом запросе,
- Обновляйте токены доступа для последующих запросов в канале API.
Refresh Token
Refresh Token – это токен обновления. Access_token имеет временный характер действия (60 минут с момента получения). Для обновления токена доступа необходимо использовать refresh_token. С момента получения refresh token действителен 180 дней. Refresh_token вы получаете одновременно с access_token при обмене кода авторизации на токен доступа.
ID token
ID Token — это токен в формате JWS (JSON Web Token), который подтверждает факт аутентификации пользователя и содержит информацию о том, как и когда эта аутентификация произошла.
Для чего нужен id_token?
- Подтвердить личность пользователя: с помощью уникальных идентификаторов можете связать сессию с учетной записью пользователя
- Получить контекст входа: вы можете узнать все о том, как произошла аутентификация
- Обеспечить безопасность входа: параметры id_token позволяют провалидировать подлинность иных передаваемых вам токенов из Банка
Какая информация содержится в ID Token:
Информация, которая позволяет идентифицировать (не на уровне натуральных значений) пользователя и узнать о его аутентификации.
| Наименование атрибута | Описание |
|---|---|
| acr | Контекст класса аутентификации |
| amr | Методы аутентификации |
| aud | Аудитория, для которой ID Token был выпущен |
| auth_time | Время, когда произошла аутентификация конечного пользователя |
| azp | Идентификатор стороны, для которой выпущен id_token |
| exp | Время истечения срока действия id_token |
| iat | Время, когда JWT был выпущен |
| iss | Идентификатор эмитента |
| nonce | Строковое значение, используемое для связи сеанса клиента с id_token и для предотвращения атак с повторным воспроизведением |
| sid2 | Идентификатор сессии токена |
| sub | Внешний идентификатор учетной записи пользователя компании |
Структура ID token
ID Token представлен в виде строки, состоящей из трех частей, разделенных точками (.): header.payload.signature.
Части ответа:
- Header (заголовок): содержит информацию, такую как алгоритм подписи и тип токена
- Payload (полезная нагрузка): содержит информацию (атрибуты) о пользователе и его аутентификации
- Signature (электронная подпись): проверка подписи позволяет убедиться в подлинности токена
Как работать с ID token?
- Извлеките id_token из ответа ресурса
/ic/sso/api/v2/oauth/token - Декодируйте ответ: каждая часть ответа должна декодироваться отдельно. Для декодирования следует воспользоваться алгоритмом Base64URL Encoding.
- Проверьте подпись (рекомендуется): необходимо вычислить подпись публичным ключом Банка, декодировав блок Header и Payload. Далее сравнить полученное значение c блоком Signature.
- Проверьте ключевые атрибуты
Правила авторизации
- Соблюдайте требования спецификаций OAuth 2.0 , OpenID Connect ;
- В ссылку авторизации включайте операции и claims в соответствии с доступным вам scope.
Получить токен можно двумя способами:
- В Личном кабинете Sber API по инструкции;
- Сформируйте ссылку авторизации и получите токен по схеме выше.
Выполните следующие шаги:
- Сформируйте ссылки авторизации для каждой из дочерних организаций;
- Направьте соответствующие ссылки авторизации дочерним органи зациями, получите access_token и refresh_token после подписания ими согласий;
- Направьте запрос по каналу Sber API от имени головой компании с access_token соответствующей дочерней организации.
Выполните следующие шаги:
- Реализуйте механизм авторизации на базе сервиса СберБизнес ID;
- Направьте запрос по каналу Sber API с access_token соответствующей организации.
Полный перечень claims
Claim — это отдельная единица информации (атрибут) о пользователе или организации, которая возвращается в ID Token или может быть запрошена у API. Это утверждение о субъекте (например, имя, email, ИНН компании).
Проще говоря: Claim — это информация о том, кто пользователь и какими свойствами обладает его организация.
- Назначение: Предоставление идентификационных и атрибутивных данных.
- Примеры claims:
name(ФИО),email,inn(ИНН),orgName(название организации),userPosition(должность). - Использование: Могут автоматически включаться в payload ID Token (в зависимости от наличия в scope) или запрашиваться отдельно. Используются приложе нием для идентификации пользователя, персонализации интерфейса и бизнес-логики.
| Наименование атрибута (claim) | Описание |
|---|---|
| Стандартный набор | |
| Адрес электронной почты | |
| individualExecutiveAgency | Признак ЕИО (Единоличный исполнительный орган) |
| inn | ИНН |
| name | Фамилия Имя Отчество |
| orgFullName | Полное наименование компании |
| orgJuridicalAddress | Юридический адрес компании |
| orgKpp | КПП |
| orgLawForm | Организационно-правовая форма (полное наименование) |
| orgLawFormShort | Организационно-правовая форма (принятое сокращение) |
| OrgName | Сокращенное наименование организации |
| orgOgrn | ОГРН |
| orgOktmo | ОКТМО |
| offerExpirationDate | Дата окончания срока действия согласия (оферты) |
| phone_number | Номер телефона |
| terBank | Территориальный банк |
| userPosition | Должность |
| HashOrgId | Хэш идентификатора организации (orgId) |
| sub | Внешний идентификатор учетной записи пол ьзователя компании |
| userCryptoType | Тип криптографии |
| userSignatureType | Тип подписи |
| firstName | Имя владельца учетной записи |
| middleName | Отчество владельца учетной записи |
| lastName | Фамилия владельца учетной записи |
| В отдельных сервисах | |
| accounts | Информация о счетах |
| buyOnCreditMmb (Кредит в корзине) | Признак возможности покупки в кредит на сайте партнера (Малый и Микро Бизнес) |
| creditLineAvailableSum (Кредит в корзине) | Сумма действующей ВКЛ (Возобновляемой кредитной линией) |
| hasActiveCreditLine (Кредит в корзине) | Признак наличия у клиента действующей ВКЛ (Возобновляемой кредитной линией) |
| Дополнительные клэймы | |
| orgRegDateINN | Дата регистрации ИНН |
| orgRegDateOGRN | Дата регистрации ОГРН |
| accounts | Счет, БИК, корреспондентский счет компании |
| orgOkpo | ОКПО |
| resident | Признак 'резидент / нерезидент' |
| active | Признак активности пользователя |
| branch | Информация о подразделении |
| dboContracts | Договоры обслуживания организации |
| nonClient | Признак "Неклиент" Неклиент — неверифицированный пользователь, у которого не подтверждены учетные данные, отсутствуют расчетный счет и право подписи документов |
| orgBusinessSegment | Бизнес-сегмент |
| orgUnconfirmed | Признак "Неподтвержденная организация" |
| isCorpCardHolder | Признак наличия у клиента бизнес-карты |
| isIdentified | Признак идентификации пользователя |
| tbIdentCode | Код территориального банка |
| userRoles | Роли пользователя |
| userGroups | Группы пользователя |
Полный перечень операций
Scope — это набор операций (прав доступа), который определяет, к каким конкретным действиям и данным в Sber API партнер запрашивает разрешение у пользователя. Это перечень функций API, которые приложение намерено использовать от имени пользователя.
Проще говоря: Scope — это список того, что можно делать в системе (например, получать выписки, создавать платежи, запрашивать данные о счетах).
- Назначение: Контроль доступа на уровне функциональности.
- Примеры операций в scope:
GET_STATEMENT_ACCOUNT(получить выписку),PAY_DOC_RU(создать рублевый платеж),GET_CREDIT_OFFERS(получить кредитные предложения). - Использование: Указывается в ссылке авторизации. Пользователь видит этот список и соглашается предоставить права на эти операции. Полученный Access Token будет действителен только для операций, указанных в этом scope.
| Код операции для включения в scope | Описание |
|---|---|
| ACCEPTANCE_ADVANCE | Заявление на заранее данный акцепт (ЗДА) |
| BANK_CONTROL_STATEMENT | Ведомость банковского контроля (ВБК в банк) |
| BANK_CONTROL_STATEMENT_CHANGE_APPLICATION | Заявление о внесении изменений в I раздел ВБК |
| BUSINESS_CARDS_TRANSFER | Перевод по бизнес-картам |
| CARD_ISSUE | Электронный реестр на открытие счетов и выпуск карт |
| CERTIFICATE_REQUEST | Запрос на сертификат |
| CONFIRMATORY_DOCUMENTS_INQUIRY | Справка о подтверждающих документах |
| CORPORATE_CARDS | Бизнес-карты |
| CORRESPONDENT_CUR_ADDITIONAL | Дополнительная информация по валютному контрагенту (бенефициару) |
| CREDIT_REQUEST | Запрос на создание заявок на кредит |
| CRYPTO_CERT_REQUEST_EIO | Запрос на выпуск сертификата для ЕИО |
| CURR_CONTROL_MESSAGE_FROM_BANK | Письмо для целей ВК (из банка) |
| CURR_CONTROL_MESSAGE_TO_BANK | Письмо для целей ВК (в банк) |
| CURRENCY_OPERATION_detailsS | Сведения о валютной операции |
| DEPOSIT_REQUEST | Депозиты |
| DICT | Справочники |
| FILES | Выгрузка/загрузка файлов |
| GENERIC_LETTER_FROM_BANK | Письмо свободного формата (из банка) |
| GENERIC_LETTER_TO_BANK | Письмо свободного формата (в банк) |
| GET_ADVANCE_ACCEPTANCES | Получение сведений о клиентах, подключенных к подпискам и пакетам услуг |
| GET_CLIENT_ACCOUNTS | Получение информации о счетах подключенного клиента |
| GET_CORRESPONDENTS | Получение списка контрагентов |
| GET_CREDIT_OFFERS | Получение информации по кредитным предложениям |
| GET_CRYPTO_INFO | Получение криптоинформации (КУЦ, криптопрофили и т.д.) |
| GET_CRYPTO_INFO_EIO | Получение сертификатов открытых ключей электронной подписи пользователей организации (ЕИО) |
| GET_STATEMENT_ACCOUNT | Получение выписки по счету клиента |
| GET_STATEMENT_TRANSACTION | Получение операции по выписке |
| MINIMUMBALANCE_REQUEST | Неснижаемый остаток |
| NOMINAL_ACCOUNTS | Безопасные сделки |
| PAY_DOC_CUR | Валютное платежное поручение |
| PAY_DOC_RU | Рублевое платежное поручение |
| PAY_DOC_RU_INVOICE_ANY | Выставление счета на оплату по свободным реквизитам |
| PAY_DOC_RU_INVOICE_BUDGET | Рублевое платежное поручение с бюджетным реквизитами, легкая форма |
| PAYMENT_REQUEST_IN | Входящее платежное требование |
| PAYMENT_REQUEST_OUT | Исходящее платежное требование |
| PAYMENTS_REGISTRY | Реестр платежей |
| PAYROLL | Зарплатная ведомость |
| SALARY_AGREEMENT | Зарплатный договор |
| SALARY_AGREEMENT_TRANSPORT_PACKAGE | Транспортные пакеты |
Согласие на передачу данных
Согласие на передачу данных - это документ, который Банк запрашивает у клиента и подтверждающий право Банка на передачу информации о клиенте третьему лицу (вам, как Партнеру Банка), выполнению оп ераций третьим лицом (вами, как Партнером Банка) от лица Клиента. Согласие содержит информацию о том к каким данным, операциям и на какой срок предоставлен доступ Партнеру.
Согласие запрашивается при обращении к сервису авторизации СберБизнес ID:
- При первичном обращении пользователя к Платформе Партнера через сервис СберБизнес ID;
- При повторном обращении, в случае если:
- Истек срок действия предыдущего согласия;
- Предыдущее согласие было отозвано пользователем;
- Состав запрашиваемого согласия (scope) расширился относительно принятого ранее согласия.
Согласие на передачу данных не требуется, если Платформа использует получение и отправку документов только по своей организации. Если пользователь отзывает согласие, то все выданные токены (Access Token, Refresh Token) деактивируются.