Authorization code
Ресурс /v2/oauth/authorize
Работа с сервисами авторизации версии v1 описана в файле.
Для получения кода авторизации (authorization code) Приложение партнера должно осуществить вызов ресурса /v2/oauth/authorize.
Также получение пары Access и Refresh Token возможно через swagger: текущий тестовый контур, новый тестовый контур.
Host и полный url для вызова ресурса на тестовом и промышленном контурах см. в разделе URL для вызова API СберБизнес ID.
Направления взаимодействия, описанные в разделе, выделены на схеме красным.
Параметры запроса
При запросе ресурса /v2/oauth/authorize используются параметры, полученные при регистрации приложения Партнера.
| Параметр | Тип | Описание |
|---|---|---|
scope | Query | Обязательный параметр. Область сведений (разрешения), до которых требуется получить доступ Приложению Партнера. Должен содержать обязательный параметр «openid». Через пробел должны быть указаны атрибуты (claim) и ресурсы, полученные при регистрации приложения. Значения переданные в параметре scope сравниваются со значениями согласованными при регистрации приложения |
response_type | Query | Обязательный параметр. Всегда должен содержать значение «code». Авторизация по СберБизнес ID поддерживает только authorization code flow протокола OAuth 2.0 |
client_id | Query | Обязательный параметр. Уникальный идентификатор Приложения Партнера, полученный при регистрации приложения |
redirect_uri | Query | Обязательный параметр. Ссылка на ресурс (конечную точку) Приложения партнера, на которую будет передан код авторизации и перенаправлен браузер пользователя после успешной авторизации. Значение переданное в параметре redirect_uri сравнивается по маске со значением, полученным при регистрации приложения.Пример: При регистрации приложения указана маска для redirect_uri: https://example.ru/auth/login Если при запросе кода авторизации будет указан адрес: https://example.ru, то такое значение не пройдет проверку, т.к. отсутствует часть обязательных path параметров указанных при регистрации;https://example.ru/auth/login/register, то такое значение пройдет проверку, т.к. совпадает с зарегистрированным. При этом расширение path параметров не влияет на проверку |
state | Query | Обязательный параметр. Параметр для предотвращения CSRF-атак. Значение State должно быть защищено от подбора и храниться таким образом, чтобы его не мог изменить никто, кроме Приложения партнера. Рекомендуется использовать идентификатор сессии клиента в сервисе партнера или один из его производных (например, хэш этого идентификатора), при этом может использоваться любой другой механизм генерации случайного значения достаточной длины для предотвращения подбора. В общем случае оптимально использовать строку длиной не менее 36 символов с проверкой регистра, без использования специальных символов. Полные требования к значению state см. в спецификации rfc6749. Для повторного запроса это значение должно заменяться новым |
nonce | Query | Обязательный параметр. Параметр служит для защиты от replay-атак, то есть для предотвращения обработки одного и того же запроса несколько раз. Значение Nonce должно быть защищено от подбора и храниться таким образом, чтобы его не мог изменить никто, кроме Приложения Партнера. Рекомендуется использовать случайное значение, сохраняемое в сессии клиента в сервисе партнера. Для повторного запроса это значение должно заменяться новым. В общем случае оптимально использовать строку длиной не менее 10 символов с проверкой регистра, без использования специальных символов. Полные требования к значению nonce см. в спецификации Open ID Connect |
code_challenge | Query | Необязательный параметр. Параметр в соответствии с надстройкой PKCE над протоколом OAuth 2.0. Должен быть уникальным для каждого вызова ресурса /authorize. См. правила формирования параметра в PKCE. Подключение настройки согласуется с менеджером при регистрации приложения. Рекомендуется к использованию, т.к. увеличивает безопасность подключения |
code_challenge_method | Query | Необязательный параметр. Связанный с code_challenge параметр. Заполняется в соответствии со спецификацией PKCE. Если указан, то всегда должен содержать значение «S256». Параметр «plain» не поддерживается. Если передан параметр code_challenge, то параметр code_challenge_method должен обязательно присутствовать |
Вызов ресурса должен осуществляться только с использованием экранирования специальных символов.
Пример запроса без экранирования
Request URL: https://edupir.testsbi.sberbank.ru:9443/ic/sso/api/v2/oauth/authorize?scope=openid PAY_DOC_RU inn email&response_type=code&client_id=999999&state=a18821dc752640c0a1dda57a17c122fb&nonce=02e5d3d2-b2a8-4a87-be43-af7ffb8649f2&redirect_uri=https://example.ru
Request Method: GET
Пример запроса с экранированием
Request URL: https://edupir.testsbi.sberbank.ru:9443/ic/sso/api/v2/oauth/authorize?scope=openid%20PAY_DOC_RU%20inn%20email&response_type=code&client_id=999999&state=a18821dc752640c0a1dda57a17c122fb&nonce=02e5d3d2-b2a8-4a87-be43-af7ffb8649f2&redirect_uri=https%3A%2F%2Fexample.ru
Request Method: GET
Параметры ответа
После успешной авторизации пользователя, СберБизнес ID перенаправит (http-code = 302) браузер пользователя на адрес, который был указан в параметре redirect_uri и добавит следующие query параметры:
| Параметр | Тип | Описание |
|---|---|---|
code | Query | Значение кода авторизации. Формируется произвольно в формате UUID (случайное значение) плюс "1" или "2" через дефис, например, CD6A56FD-A9C7-4152-AA1D-FA57E550F6AC-2. Срок жизни кода авторизации составляет 120 секунд |
state | Query | Значение параметра state, полученного при вызове ресурса /v2/oauth/authorize. Полученный параметр state должен быть проверен Приложением Партнера на соответствие значению, указанному при вызове ресурса /oauth/authorize. Если значения не совпадают, обработка должна быть немедленно прекращена |
Пример ответа
HTTP/1.1 302 Found
Location: https://example.ru?code=f710576d-7263-4ec6-a01b-8404aca2850d-1&state=a18821dc752640c0a1dda57a17c122fb
Коды возврата
Если запрос на ресурс /oauth/authorize был выполнен некорректно и допущены ошибки при формировании параметров, то в зависимости от типа допущенной ошибки пользователю будет показана страница ошибки СберБизнес ID или браузер пользователя будет перенаправлен (http-code = 302) на адрес, который был указан в параметре redirect_uri с добавлением следующих query параметров:
| Параметр | Тип | Описание |
|---|---|---|
error | Query | Код возникшей ошибки |
error_description | Query | Описание возникшей ошибки |
state | Query | Значение параметра state, полученного при вызове ресурса /v2/oauth/authorize. По значению параметра state и коду полученной ошибки Приложение Партнера может понять, какой вызов был осуществлен некорректно |
Приложение Партнера должно обработать полученные параметры и уведомить пользователя о действиях, которые ему необходимо выполнить.
Перечень исключений, сообщения о которых передаются на адрес Приложения Партнера:
| Значение параметра error | Значение параметра error_description | Описание причины возникновения |
|---|---|---|
invalid_request | Missing parameters: {не указанные поля через пробел} | В параметрах запроса кода авторизации отсутствует хотя бы один из обязательных параметров: response_type, state, scope |
unsupported_response_type | Response_type {значение response_type} not supported | В параметрах запроса кода авторизации указан неправильный response_type |
invalid_scope | Scope 'openid' is required | В параметре scope отсутствует обязательный параметр openid |
invalid_request | Invalid code challenge | В параметре code_challenge передано значение не отвечающее требованиям протокола PKCE |
invalid_request | Transform algorithm required | Передан параметр code_challenge, но не указан code_challenge_method |
invalid_request | Transform algorithm not supported | В параметр code_challenge_method указано значение отличное от S256 |
invalid_scope | Too many scopes requested | Вызов осуществлен на ресурс предыдущей версии (/v1/oauth/authorize) и в параметре scope передано более одного дополнительного значения scope |
invalid_scope | Invalid scope param value | Вызов осуществлен на ресурс предыдущей версии (/v1/oauth/authorize) и в параметре scope передано незарегистрированное значение scope |
invalid_scope | Invalid scope | В параметре scope передано незарегистрированное значение scope |
invalid_scope | Scope PAYMENT_SUBSCRIPTION is required | В параметре scope должен присутствовать параметр payment_subscription. Особенности использования параметра payment_subscription, см. в Подключение подписки |
invalid_scope | Scope PAYMENT_SUBSCRIPTION is forbidden | Параметре scope не может содержать параметр payment_subscription. Особенности использования параметра payment_subscription, см. в Подключение подписки |
invalid_request | Code challenge required | В параметрах запроса кода авторизации должны быть указаны параметры code_challenge и code_challenge_method |
Для части возникающих исключений невозможно осуществить перенаправление пользователя обратно на сайт Приложения Партнера.
В таких случаях пользователю будет показана форма сообщения об ошибке:
Для дополнительной диагностики в url адреса страницы будет добавлен параметр error, в котором будет указана причина возникшей ошибки.
Следующие причины и коды могут приводить к перенаправлению на страницы ошибки:
| Код причины | Описание причины |
|---|---|
invalid_params | В параметрах запроса присутствуют повторяющиеся query параметры |
redirect_uri_is_absent | В параметрах запроса отсутствует обязательный параметр redirect_uri |
client_id_is_absent | В параметрах запроса отсутствует обязательный параметр client_id |
bad_client_id | В параметрах указан незарегистрированный client_id |
client_blocked | В параметрах указан заблокированный client_id |
invalid_redirect_uri | В параметрах запроса параметр redirect_uri не совпадает со значением указанным при регистрации приложения |
Подключение Подписки
Если Приложение Партнера зарегистрировано как сервис, работающий по подписочной модели, то при запросе кода авторизации через ресурс /v2/oauth/authorize необходимо учитывать следующие правила и условия.
Существует две модели работы сервиса по подписке:
без пробного периода;
с пробным периодом.
Если Приложение Партнера зарегистрировано по модели:
без пробного периода, то при запросе кода авторизации
/v2/oauth/authorizeв параметре scope обязательно должен быть указан атрибутPAYMENT_SUBSCRIPTION;с пробным периодом, то при запросе кода авторизации
/v2/oauth/authorize, если в параметре scope атрибутPAYMENT_SUBSCRIPTIONбудет:- отсутствовать, то у пользователя будет запрошено согласие на подключение сервиса без подписки;
- указан, то у пользователя будет запрошено согласие на подключение сервиса с подпиской, т.е. клиент будет переведен на модель оплаты «по подписке».
Бесшовный переход из СберБизнес в Приложение Партнера
Приложение Партнера может быть зарегистрировано в системе СберБизнес и размещено в разделе Продуктов и Услуг Банка и его Партнеров.
В этом случае пользователи, работающие в системе СберБизнес, могут подключать и/или переходить в приложение Партнера, не вводя дополнительных логинов и паролей.
Для этого при регистрации Приложения Партнера необходимо передать сведения о ресурсе Приложения Партнера, на который будет перенаправлен пользователь.
При вызове ресурса Приложения Партнера в query параметры будут добавлены следующие значения:
| Параметр | Описание |
|---|---|
| loginDCB | В значении true. Признак означает, что пользователь осуществил переход в Приложение Партнера из системы СберБизнес |
| userType | Может принимать значение: |
| WEB — для пользователей, использующих SMS-подтверждение; | |
| Token — для пользователей, осуществляющих аутентификацию с помощью устройства защиты. | |
| callbackPort | Значение порта для пользователей, осуществляющих аутентификацию с помощью устройства защиты. |
Эти параметры необходимы для корректного формирования хоста для запроса Authorization Code и существенного упрощения пользовательского опыта в части перехода в сервис Партнера.
Пример вызова Приложения Партнера и ответного запроса кода авторизации для пользователя использующего СМС подтверждения
СберБизнес осуществит вызов Приложения Партнера с параметрами:
https://example.ru/authorization/sbbid?loginDCB=true&userType=WEB
Если Приложение Партнера получило вызов с указанными параметрами, то вызов ресурса /v2/oauth/authorize должен осуществляться на стандартный хост и домен СберБизнесID соответствующего контура (см. URL для вызова API СберБизнес ID). В примере указан промышленный контур:
https://sbi.sberbank.ru:9443/ic/sso/api/v2/oauth/authorize?scope=openid%20PAY_DOC_RU%20inn%20email&response_type=code&client_id=999999&state=a18821dc752640c0a1dda57a17c122fb&nonce=02e5d3d2-b2a8-4a87-be43-af7ffb8649f2&redirect_uri=https%3A%2F%2Fexample.ru
Пример вызова Приложения Партнера и ответного запроса кода авторизации для пользователя использующего устройство защиты
СберБизнес осуществит вызов Приложения Партнера с параметрами:
https://example.ru/authorization/sbbid?loginDCB=true&userType=Token&callbackPort=28016
Если Приложение Партнера получило вызов с указанными параметрами, то вызов ресурса /v2/oauth/authorize должен осуществляться на http://localhost с указанием порта полученного из параметра callbackPort:
http://localhost:28016/ic/sso/api/v2/oauth/authorize?scope=openid%20PAY_DOC_RU%20inn%20email&response_type=code&client_id=999999&state=a18821dc752640c0a1dda57a17c122fb&nonce=02e5d3d2-b2a8-4a87-be43-af7ffb8649f2&redirect_uri=https%3A%2F%2Fexample.ru
Порядок получения VPNKeyTLS токена для работы на тестовом контуре описан в разделе Получение VPNKeyTLS токена для тестового контура.