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

Запрос кода авторизации (auth_code)

Обновлено 26 января 2023

На Схеме взаимодействия обозначен как «5. Запрос AuthCode (перенаправление)».

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

Front-end партнера инициирует запрос на front-end банка на получение кода авторизации, направляя GET или POST запрос из браузера клиента.

note

Страницу входа по Сбер 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

Описание параметров

Название параметраОбязательныйОписание
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 партнёра на мобильных устройствах для избежания ошибок при возврате после авторизации в МП СБОЛ.

Примеры значений параметров

{
"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"
}
danger

Важно!

Для сценариев, в которых присутствует риск перехвата 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 ).

danger

Важно! Партнер для вызова аутентификации не должен использовать браузер, встроенный в приложение, который предоставляет приложению доступ к 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
danger

В случае отсутствия в запросе атрибута redirect_uri или в случае если значение redirect_uri не зарегистрировано для данного Партнера, Банк перенаправляет клиента на страницу, информирующую Клиента о недоступности сервиса и на партнера не вернется.

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

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