Сбер ID
Документация

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

Ниже описано 4 сценария:

1. Аутентификация на веб-странице Партнера (Web to Web)

2. Аутентификация на веб-странице Партнера через мобильное приложение Сбербанк Онлайн (mWeb to App)

3. Аутентификация на веб-странице Партнера  внутри мобильного приложения Сбербанк Онлайн (App to webview)

4. Бесшовный переход из веб Сбербанк Онлайн на сайт Партнера (Web to Web SSO)

1. Аутентификация на веб-странице Партнера (Web to Web)

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

Страницу входа по Сбер ID можно открывать и в popup-окне. Рекомендуемый размер окна - 600х600 пикселей.

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

GET  /CSAFront/oidc/authorize.do
Host: online.sberbank.ru
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 HTTP/1.1

Важно!

Для сценариев, в которых присутствует риск перехвата 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 в браузере, встроенном в приложение, будет отображена страница-заглушка, сообщающая клиенту о небезопасности входа.

Таблица 2. Описание полей запроса кода авторизации

п/п

Наименование заголовка/поля

Описание

Обязательность поля

Пример

1

response_type

Указывается равным code

Да

code

2

client_type

Указывается равным PRIVATE

Нет

PRIVATE

3

scope

Наименование групп данных, на которые подписана система партнера (выдается при регистрации системы в банке).

Значение openid является обязательным и располагается на первой позиции. Разделитель – "+".

Да

openid+name+maindoc+email+mobile

4

client_id

Идентификатор системы партнера, полученный партнером в личном кабинете после регистрации приложения.

Да

DA5278AC-A07F-C01A-B2D3-C231DBB2E20F

5

state

Значение, включенное в запрос, которое также возвращается в ответе. Может быть строка любого контента. Для предотвращения подделки межсайтовых запросов используется генерируемое случайным образом уникальное значение.

Да

af0ifjsldkj

6

nonce

Значение, сгенерированное внешней АС для предотвращения атак повторения.

Это значение обычно представляет собой случайную уникальную строку или глобальный уникальный идентификатор, которые можно использовать для определения источника запроса. Ограничение по длине значения составляет 64 символа.

Да

n-0S6_WzA2Mj

7

redirect_uri

Адрес страницы партнера, на которую будет перенаправлен клиент после успешной аутентификации в системе банка. Временное ограничение: недопустимы символы “;” и “=“.

Да

https://clientresource.ru/cb

8

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 ).

Нет

E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM

9

code_challenge_method

Метод преобразования секретного кода code_verifier партнера. Допустимым значением является S256.

Нет

S256

2. Аутентификация на веб-странице Партнера через мобильное приложение Сбербанк Онлайн (mWeb to App)

Протокол взаимодействия поддерживает функционал универсальных ссылок. Если на устройстве пользователя установлено мобильное приложение Сбербанк Онлайн, то операционная система направит запрос авторизации в мобильное приложение, иначе страница аутентификации откроется во внешнем браузере.

Для поддержки сценария Партнеру необходимо:

  1. Встроить скрипт, формирующий универсальную ссылку
  2. Реализовать экран ошибки входа при несовпадении параметра state

Для минимизации риска перехвата AuthCode в данном сценарии рекомендуется использовать метод защиты PKCE.

Важно!

При вызове универсальной ссылки из браузера сценарий входа по Сбер ID через мобильное приложение в некоторых случаях может завершиться ошибкой - параметр state запросе и ответе не будут совпадать, т.к. сценарий начался и закончился в разных браузерах или нет возможности сохранить state локально (пример: приватный режим браузера; in-app браузер; все браузеры на iOS, кроме Safari).

Скрипт Сбер ID формирует универсальную ссылку в зависимости от браузера и режима просмотра с целью минимизации ошибочных сценариев описанных выше.

При обратном редиректе из МП СБОЛ (по redirect_uri) в браузере открывается новая вкладка. Для корректного продолжения сценария пользователя на сайте Партнера следует сохранять контекст сессии (например, в cookie) при нажатии кнопки "Войти по Сбер ID" и восстанавливать его при обратном редиректе.

Скрипт можно скачать здесь, в разделе "Скрипт для формирования универсальной ссылки".

Пример встраивания скрипта:

<body>
<div class="navigator"></div>
<div class="result">
<a href="https://online.sberbank.ru/CSAFront/oidc/authorize.do?response_type=code&scope=openid+gender+snils&client_id=AAAABBBB-XXXX-YYYY-ZZZZ-A12A618A4C3C&state=7bQfJTePBhlW&nonce=w9H8bh2yN4mQ&redirect_uri=https://example.com/external_login">Войти по Сбер ID</a>
</div>
<!-- Начало скрипта -->
<script
src = "dist/sberid-deeplink.min.js"> </script>
<script>
(function () {
function mySberidUniversallink(result) {
console.log(result);
/*{
"isPrivate": true,
"isUniversalLink": false,
"os": "windows",
"browser": "chrome",
"link": "https://online.sberbank.ru/CSAFront/oidc/authorize.do?response_type=code&scope=openid+gender+snils&client_id=AAAABBBB-XXXX-YYYY-ZZZZ-4C3C&state=7bQfJTePBhlW&nonce=w9H8bh2yN4mQ&redirect_uri=https://example.com/external_login",
"deeplink": "sberbankidlogin://sberbankid/sso?response_type=code&scope=openid+gender+snils&client_id=AAAABBBB-XXXX-YYYY-ZZZZ-4C3C&state=7bQfJTePBhlW&nonce=w9H8bh2yN4mQ&redirect_uri=https://example.com/external_login",
"universalLinkUrl: "https://online.sberbank.ru/CSAFront/oidc/sberbank_id/authorize.do",
"defaultLinkUrl": "https://online.sberbank.ru/CSAFront/oidc/authorize.do",
"deeplinkUrl": "sberbankidlogin://sberbankid/sso",
oidc: {
response_type: "code",
client_type: "PRIVATE",
client_id: "AAAABBBB-XXXX-YYYY-ZZZZ-A12A618A4C3C",
state: "7bQfJTePBhlW",
redirect_uri: "https://example.com/external_login",
scope: "openid+gender+snils",
nonce: "w9H8bh2yN4mQ",
display: "popup",
ext_redirect_uri: "googlechrome://example.com/external_login"
}
}*/
}
try {
var sberidUniversallink = new SberidUniversallink({
params: 'response_type=code&scope=openid+gender+snils&client_id=AAAABBBB-XXXX-YYYY-ZZZZ-4C3C&state=7bQfJTePBhlW&nonce=w9H8bh2yN4mQ&redirect_uri=https://example.com/external_login',
callback: mySberidUniversallink,
});
} catch (error) {
console.log(error);
}
})();
</script>
<!-- Конец скрипта -->
</body>

В результате выполнения скрипта:

  1. Обычная ссылка заменяется на универсальную в элементах, указанных в параметре selector, подставляется универсальная ссылка, сформированная из параметров params
  2. В функцию обратного вызова передаются данные, позволяющие сформировать универсальную ссылку самостоятельно

Таблица 3. Описание параметров скрипта

п/п

Наименование параметра

Описание

Обязательность

1

params

Параметры запроса кода авторизации

Нет

2

selector

HTML-элемент (id, стиль или вид), в котором нужно заменить ссылку запроса кода авторизации

Нет

3

callback

Функция обратного вызова, в которой Партнер может реализовать свою логику формирования универсальной ссылки. Актуально, если Партнер формирует ссылку на сервере.

Нет

Таблица 4. Описание объекта response

п/п

Наименование параметра

Описание

Пример

1

isPrivate

Режим браузера.

true - приватный

false - обычный

false

2

isUniversalLink

true - из данного браузера можно запускать универсальную ссылку

false - универсальную ссылку запускать нельзя, т.к. это может привести к ошибке на стороне Партнера

true

3

os

Операционная система

ios

4

browser

Браузер

safari

5

link

Полная ссылка запроса кода авторизации

https://online.sberbank.ru/CSAFront/oidc/sberbank_id/authorize.do?

response_type=code&scope=openid+gender+snils&

client_id=AAAABBBB-XXXX-YYYY-ZZZZ-A12A618A4C3C&state=7bQfJTePBhlW&

nonce=w9H8bh2yN4mQ&redirect_uri=https://example.com/external_login

6

deeplink

Deeplink без параметров (для вызова МП СБОЛ в сценарии App2Webview)

sberbankidlogin://sberbankid/sso

7

universalLinkUrl

Универсальная ссылка без параметров

https://online.sberbank.ru/CSAFront/oidc/sberbank_id/authorize.do

8

defaultLinkUrl

Обычная ссылка без параметров

https://online.sberbank.ru/CSAFront/oidc/authorize.do

9

deepLinkUrl

Полный deeplink (для вызова МП СБОЛ в сценарии App2Webview)

sberbankidlogin://sberbankid/sso?

response_type=code&scope=openid+gender+snils&client_id=AAAABBBB-XXXX-YYYY-ZZZZ-4C3C&state=7bQfJTePBhlW&nonce=w9H8bh2yN4mQ&redirect_uri=https://example.com/external_login

10

oidc

Объект. Содержит oidc параметры, переданные в скрипт при вызове.

11

ext_redirect_uri

Параметр, вложенный в объект oidc.

Deeplink для вызова браузера в котором находился клиент при нажатии на кнопку "Войти по Сбер ID" и открытия в нем ссылки, указанной в redirect_uri.

Указывается только если os=ios

googlechrome://example.com/external_login

12

package

Параметр, вложенный в объект oidc.

Deeplink для вызова браузера в котором находился клиент при нажатии на кнопку "Войти по Сбер ID" и открытия в нем ссылки, указанной в redirect_uri.

Указывается только если os=android

googlechrome://example.com/external_login


Пример экрана ошибки (на стороне Партнера), в случае несовпадения параметра state:

Кнопка "Войти по Сбер ID" в этом случае должна вести строго на стандартный сценарий входа в веб (Web to Web).

3. Аутентификация на веб-странице Партнера внутри мобильного приложения Сбербанк Онлайн (App to webview)

Внутри мобильного приложения Сбербанк Онлайн есть возможность открывать сайт Партнера во встроенном браузере ( Safari View Controller/Google Chrome Custom Tabs ) по клику на различные баннеры.

Для того, чтобы клиент мог бесшовно (без ввода логина и пароля) войти по Сбер ID на сайт Партнера необходимо вызвать сценарий входа по Сбер ID по deeplink.

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

Если вызвать его из стороннего браузера, то вход по Сбер ID завершится ошибкой.

Для открытия веб-страницы Сбер ID в браузере внутри мобильного приложения Сбербанк Онлайн следует вызывать обычную ссылку, а не универсальную (см. сценарий mWeb to App).

Есть два сценария запуска входа по Сбер ID:

  1. Клиент самостоятельно нажимает на кнопку "Войти по Сбер ID"
  2. Сайт Партнера автоматически запускает сценарий входа по Сбер ID

Сайту Партнера рекомендуется реализовать сервис, который будет формировать страницу не с обычной веб-ссылкой на кнопке Сбер ID, а с deeplink.

Сценарий:

  1. Клиент внутри мобильного приложения Сбербанк Онлайн нажимает на какой-либо баннер (сториз, каталог, ссылка в чате и т.д.)
  2. В результате в Safari View Controller/Google Chrome Custom Tabs вызывается сервис Партнера вида https://partner.ru/auth?type=deeplink&source=catalogbanner_partnername
  3. Сервис Партнера по входным параметрам понимает, что на кнопку Сбер ID нужно поставить не обычную ссылку, а deeplink и добавить к ней параметр source:
Пример запроса
sberbankidlogin://sberbankidsso?
response_type=code
&scope=openid+phones+place_of_birth+gender
&client_id=AAAABBBB-XXXX-YYYY-ZZZZ-A12A618A4C3C
&state=UhdlDQS6vG4m&nonce=TGfhfBxr5ak1
&redirect_uri=https://exapmle.com/external_login
&source=catalogbanner_partnername

,где source – любая строка (пример: Story_Insurance, SmartBanner_Okko, CatalogBanner_Zvuk). Опциональный параметр, в который передается точка входа в МП СБОЛ из которой был открыт Safari View Controller/Google Chrome Custom Tabs.

Остальные параметры являются стандартными для любого входа по Сбер ID и описаны выше в таблице 2.

Рекомендуем воспользоваться SberID JS SDK или скриптом для формирования универсальной ссылки, который возвращает уже сформированный deeplink в объекте oidc.

Параметр source можно указать при инициализации скрипта в params.

Пример работы со скриптом представлен выше в описании сценария mWeb to App.

4. Бесшовный переход из веб Сбербанк Онлайн на сайт Партнера (Web to Web SSO)

Внутри веб Сбербанк Онлайн есть возможность разместить баннер (или ссылку), ведущую на сайт Партнера.

Для того, чтобы клиент при переходе мог бесшовно (без ввода логина и пароля) войти по Сбер ID на сайт Партнера необходимо вызвать сценарий входа по Сбер ID в веб (Web to Web). Пример формирования запроса описан выше в сценарии (Web to Web).

Партнеру рекомендуется реализовать сервис, который будет автоматически формировать и вызывать запрос кода авторизации.

Сценарий:

  1. Клиент внутри веб Сбербанк Онлайн нажимает на какой-либо баннер (или ссылку)
  2. В результате клиент перенаправляется на сервис Партнера вида https://partner.ru/auth?type=auto&utm_source=websbol&utm_medium=sso&utm_campaign=catalog_banner&to=cabinet, где utm_source, utm_medium, utm_campaign и to - дополнительные параметры, по которым сервис Партнера определяет откуда пришел клиент и куда его нужно перенаправить после успешного входа (то есть какой адрес указать в параметре redirect_uri в запросе кода авторизации). Параметры type и to Сбер ID никак не использует и они не участвуют в запросе кода авторизации. Пример значений utm-меток: utm_source=websbol или sber; utm_medium=sso; utm_campaign=catalog_banner или sber_lk или sber_main_page.
  3. Сервис Партнера по входным параметрам (type=auto) определяет, что нужно сформировать и вызвать запрос кода авторизации
  4. Сервис Партнера запрашивает код авторизации (перенаправляет клиента на страницу Сбер ID) и добавляет в запрос параметры utm_source, utm_medium, utm_campaign, которые пришли на шаге 2
  5. Клиент автоматически аутентифицируется в Сбер ID (по уже активной сессии), подтверждает вход и согласие (если оно не активно)
  6. В результате успешного входа Сбер ID перенаправляет клиента на сервис Партнера по адресу, указанному в параметре redirect_uri