ym88659208ym87991671
Получение кода авторизации | Документация для разработчиков

Получение кода авторизации

Обновлено 29 ноября 2024
Компаниям
Холдингам
Платформам

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

Alt text /ic/sso/api/v2/oauth/authorize

Запрос позволяет открыть страницу аутентификации в СберБизнес. Ваша Платформа формирует запрос в формате ссылки, устанавливая все параметры, и передает ее браузеру пользователя (Клиента) для прохождения аутентификации. При успешной аутентификации СберБизнес ID вернет браузер пользователя на Redirect_uri вместе с кодом авторизации (authorization code).

Для обращения к ресурсу необходимо отправлять запрос на:

  • Тестовый контур https://efs-sbbol-ift-web.testsbi.sberbank.ru:9443
  • Промышленный контур https://sbi.sberbank.ru:9443

Для клиентов, работающих через устройство VPNkey-TLS1:

  • http://localhost:28016

1 Подробнее о типе аутентификации при помощи токена см. в разделе SSO под катом "Аутентификация и авторизация в СберБизнес".

Если тип пользователя не может быть определен, то вызов должен осуществляться на основной host.

Request

/ic/sso/api/v2/oauth/authorize

НаименованиеТипФорматRegexpОбязательностьОписание
QUERRY PARAMETERS
scopestringstring^[a-zA-Z0-9._ -]$requiredНабор атрибутов (claim) и операций, которые будут доступны платформе после авторизации клиента. Должен содержать обязательный параметр openid
response_typestringstring^code$requiredВсегда должен содержать значение code. Авторизация по СберБизнес ID поддерживает только authorization code flow протокола OAuth 2.0
client_idstringstring^[a-zA-Z0-9]+$requiredУникальный идентификатор Платформы, полученный при подключении к Sber API
redirect_uristringURL^(https?:\/\/)?(www.)?([a-z0-9-.]+.[a-z]{2,3})(:[0-9]{1,5})?\/?.*$requiredСсылка на ресурс (конечную точку) Платформы, на которую будет передан код авторизации и перенаправлен браузер пользователя после успешной авторизации. Значение переданное в параметре redirect_uri сравнивается по маске со значением, полученным при подключении к Sber API

Пример:
При подключении вы указали маску для redirect_uri https://example.ru/auth/login
Если при запросе кода авторизации будет указан адрес:
- https://example.ru, то такое значение не пройдет проверку, т.к. отсутствует часть обязательных path-параметров указанных при регистрации;
- https://example.ru/auth/login/register, то такое значение пройдет проверку, т.к. совпадает с зарегистрированным. При этом расширение path-параметров не влияет на проверку
statestringstring^[a-zA-Z0-9]{36,}$requiredПараметр для предотвращения CSRF-атак. Значение State должно быть защищено от подбора и храниться таким образом, чтобы его не мог изменить никто, кроме платформы. Рекомендуется использовать идентификатор сессии клиента в платформе или один из его производных (например, хэш этого идентификатора), при этом может использоваться любой другой механизм генерации случайного значения достаточной длины для предотвращения подбора. В общем случае оптимально использовать строку длиной не менее 36 символов с проверкой регистра, без использования специальных символов. Полные требования к значению state см. в спецификации rfc6749. Для повторного запроса это значение должно заменяться новым.
noncestringstring^[a-zA-Z0-9]{10,}$optionalПараметр служит для защиты от replay-атак, то есть для предотвращения обработки одного и того же запроса несколько раз. Значение Nonce должно быть защищено от подбора и храниться таким образом, чтобы его не мог изменить никто, кроме платформы. Рекомендуется использовать случайное значение, сохраняемое в сессии клиента в платформе. Для повторного запроса это значение должно заменяться новым. В общем случае оптимально использовать строку длиной не менее 10 символов с проверкой регистра, без использования специальных символов. Полные требования к значению nonce см. в спецификации Open ID Connect
code_challengestringstring^[a-zA-Z0-9]$optionalПараметр в соответствии с надстройкой PKCE над протоколом OAuth 2.0. Должен быть уникальным для каждого вызова /v2/oauth/authorize. См. правила формирования параметра в PKCE. Подключение настройки согласуется с менеджером при регистрации платформы. Рекомендуется к использованию, т.к увеличивает безопасность подключения
code_challenge_methodstringstring^S256$optionalСвязанный с code_challenge параметр. Заполняется в соответствии со спецификацией PKCE. Если указан, то всегда должен содержать значение S256. Параметр «plain» не поддерживается.

Если передан параметр code_challenge, то параметр code_challenge_method должен обязательно присутствовать

Responses

При успешной аутентификации СберБизнес ID вернет браузер пользователя на Redirect_uri вместе с кодом авторизации (code) и значением параметра state, который был указан в ссылке аутентификации.

302 (OK)

ПараметрТипОписание
codeQueryЗначение кода авторизации. Формируется в произвольном формате из букв латинского алфавита и цифр длиной 38 символов

Срок жизни кода авторизации составляет 120 секунд
stateQueryЗначение параметра state, полученного при вызове ресурса /v2/oauth/authorize. Полученный параметр state должен быть проверен платформой на соответствие значению, указанному при вызове ресурса /v2/oauth/authorize. Если значения не совпадают, обработка должна быть немедленно прекращена

При наличии ошибок в ссылке аутентификации СберБизнес ID вернет браузер пользователя на Redirect_uri вместе с параметрами ошибки.

302 (Error)

Errorerror_descriptionОписание
unsupported_response_typeResponsetype {значение responsetype} not supportedВ параметрах запроса кода авторизации указан неправильный response_type. Должно быть указано code.
invalid_requestMissing parameters: {не указанные поля через пробел}В параметрах запроса кода авторизации отсутствует хотя бы один из обязательных параметров: response_type, state, scope и др. Смотрите модель запроса /v2/oauth/authorize выше.
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_requestCode challenge requiredВ параметрах запроса кода авторизации должны быть указаны параметры code_challenge и code_challenge_method
invalid_scopeScope 'openid' is requiredВ параметре scope отсутствует обязательный параметр openid
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.
invalid_scopeScope PAYMENT_SUBSCRIPTION is forbiddenПараметре scope не может содержать параметр payment_subscription.

В ряде случаев СберБизнес ID не сможет вернуть пользователя на Redirect_uri. При переходе по некорректному URL аутентификации в адресной стороке пользователя будет информация, которая поможет диагностировать ошибку.

302 (Found)

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 не совпадает со значением указанным при регистрации платформы


ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.