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

Обновлено 7 декабря 2023

На Схеме взаимодействия обозначен как «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 не зарегистрировано для данного Партнера, Банк перенаправляет клиента на страницу, информирующую Клиента о недоступности сервиса и на партнера не вернется.