Запрос кода авторизации (auth_code)
На Схеме взаимодействия обозначен как «5. Запрос AuthCode (перенаправление)».
Параметры запроса
Front-end партнера инициирует запрос на front-end банка на получение кода авторизации, направляя GET или POST запрос из браузера клиента.
Страницу входа по Сбер ID можно открывать и в popup-окне. Рекомендуемый размер окна - 600х600 пикселей.
Пример запроса на получение кода авторизации
https://online.sberbank.ru/CSAFront/oidc/authorize.do? response_type=code &client_type=PRIVATE &scope=openid name
&client_id=DA5278AC-A07F-C01A-B2D3-C231DBB2E20F &state=af0ifjsldkj &nonce=n-0S6_WzA2Mj
&redirect_uri=https%3A%2F%2Fclientresource.ru%2Fcb &app=false
Есть вероятность, что пользователи не смогут авторизоваться на вашем ресурсе по Сбер ID в связи с переходом работы Сбер ID на сертификаты безопасности Минцифры. Подробнее на странице Переход работы Сбер ID на сертификаты Минцифры
Описание параметров
| Название параметра | Обязательный | Описание |
|---|---|---|
response_type | да | Тип возвращаемого ответа. Указывается равным code |
scope | да | Наименование групп данных, на которые подписана система партнера (выдается при регистрации системы в банке).Значение openid является обязательным и располагается на первой позиции. Разделитель – " " |
client_id | да | Идентификатор системы партнера, полученный партнером в личном кабинете после регистрации приложения |
state | да | Значение, включенное в запрос, которое также возвращается в ответе. Может быть строка любого контента. Для предотвращения подделки межсайтовых запросов используется генерируемое случайным образом уникальное значение Ограничение по длине значения составляет 96 символов |
nonce | да | Значение, сгенерированное внешней АС для предотвращения атак повторения. Это значение обычно представляет собой случайную уникальную строку или глобальный уникальный идентификатор, которые можно использовать для определения источника запроса. Ограничение по длине значения составляет 64 символа |
redirect_uri | да | Адрес страницы партнера (в формате url encode), на которую будет перенаправлен клиент после успешной аутентификации в системе банка |
client_type | нет | Указывается равным PRIVATE |
code_challenge | нет | Хэшированное значение секретного кода code_verifier партнера (генерацию code_verifier см. выше в блоке «Важно»). Хэширование выполняется методом, указанным в code_challenge_method, в нашем случае – всегда S256, поэтому code_challenge = BASE64URL-ENCODE(SHA256 (ASCII (code_verifier))) (см. https://tools.ietf.org/html/rfc7636#section-4.2 ).Например, для code_verifier = “dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk выполнение хэширования SHA256 этого значения в результате выдаст последовательность байтов [19, 211, 30, 150, 26, 26, 216, 236, 47, 22, 177, 12, 76, 152, 46, 8, 118, 168, 120, 173, 109, 241, 68, 86, 110, 225, 137, 74, 203, 112, 249, 195], преобразование которой через Base64Url дает нам значение code_challenge = “E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM” (см. https://tools.ietf.org/html/rfc7636#appendix-B) |
code_challenge_method | нет | Метод преобразования секретного кода code_verifier партнера. Допустимым значением является S256 |
app | нет | Параметр, значение которого отвечает за отображение кнопки входа через мобильное приложение СбербанкОнлайн. Необходимо указывать данный параметр только в случаях, когда страница открывается во webview партнера на мобильных устройствах для избежания ошибок при возврате после авторизации в МП СБОЛ. |
login_hint | нет | При передаче параметра номер телефона пользователя автоматически будет использован на странице входа по Сбер ID |
Примеры значений параметров
{
"response_type": "code",
"scope": "openid name maindoc email mobile",
"client_id": "DA5278AC-A07F-C01A-B2D3-C231DBB2E20F",
"state": "af0ifjsldkj",
"nonce": "n-0S6_WzA2Mj",
"redirect_uri": "https%3A%2F%2Fclientresource.ru%2Fcb",
"client_type": "PRIVATE",
"code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
"code_challenge_method": "S256",
"app": "false",
"login_hint": "790ХХХХХХХХ"
}
Важно!
Для сценариев, в которых присутствует риск перехвата AuthCode необходимо использовать защиту PKCE (https://tools.ietf.org/html/rfc7636). По рекомендациям RFC 7636 для смягчения атак перехвата кода авторизации используется динамически создаваемое случайное значение - "code verifier". Данное значение должно быть уникальным для каждого запроса кода авторизации.
Требования к генерации значения code_verifier (см. также https://tools.ietf.org/html/rfc7636#section-4.1):
Значение code_verifier - это высокоэнтропийная криптографическая случайная строка;
Строка генерируется с использованием допустимых символов
[AZ] / [az] / [0- 9] / "-" / "." / "_" / "~";Минимальная длина - 43 символа;
Максимальная длина - 128 символов.
Один из возможных алгоритмов:
Партнер, используя подходящий генератор случайных чисел, создает последовательность длиной от 32 до 96 байт, которую затем кодирует способом base64url. Например, для 32-байтной последовательности [116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173, 187, 186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83, 132, 141, 121] кодирование base64url в результате даст
code_verifierв виде“dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk”(см. https://tools.ietf.org/html/rfc7636#appendix-B ).
Важно! Партнер для вызова аутентификации не должен использовать браузер, встроенный в приложение, который предоставляет приложению доступ к cookie, или содержимому веб-страниц.
При открытии веб-страницы Сбер ID в браузере, встроенном в приложение, будет отображена страница-заглушка, сообщающая клиенту о небезопасности входа.
Параметры ответа
В случае успешной обработки запроса front-end партнера получает код авторизации по указаному в redirect_uri адресу.
Тип ответа HTTP 302 Found.
Пример ответа в случае успешного выполнения запроса
HTTP/1.1 302 Found Location: https%3A%2F%2Fclientresource%2Fcb HTTP/1.1 code=FA2154AC-3451-C01A-B2D3-C231DBB2E20F
&state=af0ifjsldkj
Описание параметров ответа
| Название параметра | Описание |
|---|---|
Location(Заголовок) | redirect_uri, указанное в запросе кода авторизации |
code(Поле) | Сгенерированный код авторизации (auth_code) Длина строки 36 символов |
state(Поле) | Значение атрибута state, указанное в запросе кода авторизации |
Примеры значений параметров
{
"code": "FA2154AC-3451-C01A-B2D3-C231DBB2E20F",
"state": "af0ifjsldkj"
}
Параметры ошибок
В случае неуспешной обработки запроса, front-end партнера получает сообщение, в котором содержится тип ошибки, по указаному в redirect_uri адресу.
Тип ответа HTTP 302 Found.
Пример ответа в случае ошибки
HTTP/1.1 302 Found Location: https%3A%2F%2Fclientresource%2Fcb HTTP/1.1 error=invalid_uri &state=af0ifjsldkj
Описание параметров ответа в случае ошибки
| Название параметра | Описание |
|---|---|
error | Наименование ошибки |
state | Значение атрибута state, указанное в запросе кода авторизации |
Примеры значений параметров в случае ошибки
| Тип возвращаемой ошибк | Описание |
|---|---|
| invalid_request | В запросе отсутствуют обязательные атрибуты |
| unauthorized_client | АС-источник запроса не зарегистрирована в Банке |
| unauthorized_client | АС-источник запроса заблокирована в Банке |
| unauthorized_client | Значение атрибута client_id не соответствует формату |
| unsupported_response_type | Значение атрибута response_type не равно «code» |
| invalid_scope | Значение атрибута scope не содержит параметр openid в начальной позиции |
| invalid_scope | Запрошенный scope содержит значения, недоступные для АС-источника запроса |
| access_denied | Клиент отказался от передачи согласий |
| invalid_state | Значение атрибута state не соответствует изначальному |
| window_closed | Клиент закрыл окно авторизации через Сбербанк ID |
В случае отсутствия в запросе атрибута redirect_uri или в случае если значение redirect_uri не зарегистрировано для данного Партнера, Банк перенаправляет клиента на страницу, информирующую Клиента о недоступности сервиса и на партнера не вернется.