ym88659208ym87991671
Authorization code | Документация SmartMarket
Skip to main content

Authorization code

Ресурс /v2/oauth/authorize

note

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

Для получения кода авторизации (authorization code) Приложение партнера должно осуществить вызов ресурса /v2/oauth/authorize.

Также получение пары Access и Refresh Token возможно через swagger.

danger

Host и полный url для вызова ресурса на тестовом и промышленном контурах см. в разделе URL для вызова API СберБизнес ID.

Направления взаимодействия, описанные в разделе, выделены на схеме красным.

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

При запросе ресурса /v2/oauth/authorize используются параметры, полученные при регистрации приложения Партнера.

ПараметрТипОписание
scopeQueryОбязательный параметр. Область сведений (разрешения), до которых требуется получить доступ Приложению Партнера. Должен содержать обязательный параметр «openid». Через пробел должны быть указаны атрибуты (claim) и ресурсы, полученные при регистрации приложения. Значения переданные в параметре scope сравниваются со значениями согласованными при регистрации приложения
response_typeQueryОбязательный параметр. Всегда должен содержать значение «code». Авторизация по СберБизнес ID поддерживает только authorization code flow протокола OAuth 2.0
client_idQueryОбязательный параметр. Уникальный идентификатор Приложения Партнера, полученный при регистрации приложения
redirect_uriQueryОбязательный параметр. Ссылка на ресурс (конечную точку) Приложения партнера, на которую будет передан код авторизации и перенаправлен браузер пользователя после успешной авторизации. Значение переданное в параметре redirect_uri сравнивается по маске со значением, полученным при регистрации приложения.
Пример:
При регистрации приложения указана маска для redirect_uri: https://example.ru/auth/login
Если при запросе кода авторизации будет указан адрес:
https://example.ru, то такое значение не пройдёт проверку, т.к. отсутствует часть обязательных path параметров указанных при регистрации;
https://example.ru/auth/login/register, то такое значение пройдёт проверку, т.к. совпадает с зарегистрированным. При этом расширение path параметров не влияет на проверку
stateQueryОбязательный параметр. Параметр для предотвращения CSRF-атак. Значение State должно быть защищено от подбора и храниться таким образом, чтобы его не мог изменить никто, кроме Приложения партнёра. Рекомендуется использовать идентификатор сессии клиента в сервисе партнёра или один из его производных (например, хэш этого идентификатора), при этом может использоваться любой другой механизм генерации случайного значения достаточной длины для предотвращения подбора. В общем случае оптимально использовать строку длиной не менее 36 символов с проверкой регистра, без использования специальных символов. Полные требования к значению state см. в спецификации rfc6749. Для повторного запроса это значение должно заменяться новым
nonceQueryОбязательный параметр. Параметр служит для защиты от replay-атак, то есть для предотвращения обработки одного и того же запроса несколько раз. Значение Nonce должно быть защищено от подбора и храниться таким образом, чтобы его не мог изменить никто, кроме Приложения Партнера. Рекомендуется использовать случайное значение, сохраняемое в сессии клиента в сервисе партнера. Для повторного запроса это значение должно заменяться новым. В общем случае оптимально использовать строку длиной не менее 10 символов с проверкой регистра, без использования специальных символов. Полные требования к значению nonce см. в спецификации Open ID Connect
code_challengeQueryНеобязательный параметр. Параметр в соответствии с надстройкой PKCE над протоколом OAuth 2.0. Должен быть уникальным для каждого вызова ресурса /authorize. См. правила формирования параметра в PKCE. Подключение настройки согласуется с менеджером при регистрации приложения. Рекомендуется к использованию, т.к. увеличивает безопасность подключения
code_challenge_methodQueryНеобязательный параметр. Связанный с code_challenge параметр. Заполняется в соответствии со спецификацией PKCE. Если указан, то всегда должен содержать значение «S256». Параметр «plain» не поддерживается.
Если передан параметр code_challenge, то параметр code_challenge_method должен обязательно присутствовать

danger

Вызов ресурса должен осуществляться только с использованием экранирования специальных символов.

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

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 параметры:

ПараметрТипОписание
codeQueryЗначение кода авторизации. Формируется произвольно в формате UUID (случайное значение) плюс "1" или "2" через дефис, например, CD6A56FD-A9C7-4152-AA1D-FA57E550F6AC-2.
Срок жизни кода авторизации составляет 120 секунд
stateQueryЗначение параметра 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 параметров:

ПараметрТипОписание
errorQueryКод возникшей ошибки
error_descriptionQueryОписание возникшей ошибки
stateQueryЗначение параметра state, полученного при вызове ресурса /v2/oauth/authorize. По значению параметра state и коду полученной ошибки Приложение Партнера может понять, какой вызов был осуществлен некорректно

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

Перечень исключений, сообщения о которых передаются на адрес Приложения Партнера:

Значение параметра errorЗначение параметра error_descriptionОписание причины возникновения
invalid_requestMissing parameters: {не указанные поля через пробел}В параметрах запроса кода авторизации отсутствует хотя бы один из обязательных параметров: response_type, state, scope
unsupported_response_typeResponse_type {значение response_type} not supportedВ параметрах запроса кода авторизации указан неправильный response_type
invalid_scopeScope 'openid' is requiredВ параметре scope отсутствует обязательный параметр openid
invalid_requestInvalid code challengeВ параметре code_challenge передано значение не отвечающее требованиям протокола PKCE
invalid_requestTransform algorithm requiredПередан параметр code_challenge, но не указан code_challenge_method
invalid_requestTransform algorithm not supportedВ параметр code_challenge_method указано значение отличное от S256
invalid_scopeToo many scopes requestedВызов осуществлён на ресурс предыдущей версии (/v1/oauth/authorize) и в параметре scope передано более одного дополнительного значения scope
invalid_scopeInvalid scope param valueВызов осуществлён на ресурс предыдущей версии (/v1/oauth/authorize) и в параметре scope передано незарегистрированное значение scope
invalid_scopeInvalid scopeВ параметре scope передано незарегистрированное значение scope
invalid_scopeScope PAYMENT_SUBSCRIPTION is requiredВ параметре scope должен присутствовать параметр payment_subscription. Особенности использования параметра payment_subscription, см. в Подключение подписки
invalid_scopeScope PAYMENT_SUBSCRIPTION is forbiddenПараметре scope не может содержать параметр payment_subscription. Особенности использования параметра payment_subscription, см. в Подключение подписки
invalid_requestCode 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
danger

Порядок получения VPNKeyTLS токена для работы на тестовом контуре описан в разделе Получение VPNKeyTLS токена для тестового контура.

Обновлено 03 июня 2022

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

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