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

Ниже описано 5 сценариев:

  1. Аутентификация на веб-странице Партнера (Web to Web)
  2. Аутентификация на веб-странице Партнера через мобильное приложение Сбербанк Онлайн (mWeb to App)
  3. Аутентификация на веб-странице Партнера внутри мобильного приложения Сбербанк Онлайн (App to webview)
  4. Бесшовный переход из веб Сбербанк Онлайн на сайт Партнера (Web to Web SSO)
  5. Бесшовный переход из App Сбербанк Онлайн на сайт Партнера (App to mWeb SSO)

Аутентификация на веб-странице Партнера (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 в браузере, встроенном в приложение, будет отображена страница-заглушка, сообщающая клиенту о небезопасности входа.
№ п/п Наименование   заголовка/поля Описание Обязательность поля Пример
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

Аутентификация на веб-странице Партнера через мобильное приложение Сбербанк Онлайн (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. В функцию обратного вызова передаются данные, позволяющие сформировать универсальную ссылку самостоятельно
№ п/п Наименование параметра Описание Обязательность
1 params Параметры запроса кода авторизации Нет
2 selector HTML-элемент (id, стиль или вид), в котором нужно заменить ссылку запроса кода авторизации Нет
3 callback Функция обратного вызова, в которой Партнер может реализовать свою логику формирования универсальной ссылки. Актуально, если Партнер формирует ссылку на сервере. Нет
№ п/п Наименование параметра Описание Пример
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).

Аутентификация на веб-странице Партнера внутри мобильного приложения Сбербанк Онлайн (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.

Бесшовный переход из веб Сбербанк Онлайн на сайт Партнера (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_sourceutm_mediumutm_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_sourceutm_mediumutm_campaign, которые пришли на шаге 2
  5. Клиент автоматически аутентифицируется в Сбер ID (по уже активной сессии), подтверждает вход и согласие (если оно не активно)
  6. В результате успешного входа Сбер ID перенаправляет клиента на сервис Партнера по адресу, указанному в параметре redirect_uri

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

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

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

Для реализации сценария необходимо:

  1. Внутри мобильного приложения Сбербанк Онлайн предварительно разместить баннер (или ссылку) с помощью специалистов Сбера
  2. Партнеру внедрить вход по Сбер ID (описан в разделе 1)
  3. Партнеру на своем сайте реализовать сервис, который будет автоматически формировать и вызывать запрос кода авторизации (шаг 2 в сценарии ниже)

Сценарий:

  1. Клиент внутри мобильного приложения Сбербанк Онлайн нажимает на какой-либо баннер (или ссылку)
  2. В результате клиент перенаправляется на сайт Партнера по deeplink (или universal link), например partner://auth?type=auto&source=StoryGD20&to=cabinet, где source и to - дополнительные параметры, по которым сервис Партнера определяет откуда пришел клиент и куда его нужно перенаправить после успешного входа (то есть какой адрес указать в параметре redirect_uri в запросе кода авторизации). Сбер ID эти параметры никак не использует и они не участвуют в запросе кода авторизации.
  3. Сайт Партнера по входным параметрам (type=auto) определяет, что нужно сформировать и вызвать запрос кода авторизации по deeplink.
  4. В составе входных параметров присутствует sberIDRedirect, который вычитывается и декодируется стандартным url decoder (кодировка UTF-8). Партнер генерирует параметры OIDC стандартным образом, добавляет их к значению из параметра sberIDRedirect и запускает полученный диплинк. Пример запроса:

       [scheme://host из sberIDRedirect]?
    
       &scope=openid name phones email
    
       &client_id=7CA84F72-EEA3-D4EC-C535-A12A618A4C3C
    
       &state=UhdlDQS6vG4m&nonce=TGfhfBxr5ak1
    
       &redirect_uri=https%3A%2F%2F<redirect_point>%2Fcas%2Flogin
  5. Сайт Партнера запрашивает код авторизации (перенаправляет клиента в мобильное приложение Сбербанк Онлайн)
  6. Клиент автоматически аутентифицируется в мобильном приложении Сбербанк Онлайн (по уже активной сессии), подтверждает согласие (если оно не активно)
  7. В результате успешного входа мобильное приложение Сбербанк Онлайн перенаправляет клиента на сайт Партнера по адресу, указанному в параметре redirect_uri.

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

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