Auhorization code

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

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

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

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 токена для тестового контура.

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

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