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

JavaScript SDK

Общие сведения

Javascript SDK для Партнеров Сбер ID, упрощающая подключение получение кода авторизации (AuthCode).

Для получения access token и данных клиента рекомендуется воспользоваться Java SDK или Python SDK.

SDK позволяет:

  • генерировать стилизованную кнопку «Войти по Сбер ID»;
  • включать режим "Быстрый вход";
  • выбирать способ отображение страницы авторизации Сбер ID (модальное окно, обычный переход);
  • включить режим формирования универсальных ссылок, для авторизации в мобильной версии браузера через мобильное приложение Сбербанк Онлайн;
  • включить генерацию и проверку state в процессе аутентификации;
  • отравлять в SberVisor события по показу кнопки, нажатию на кнопку и успешном/не успешном входе по Сбер ID.

Подключение

Подключите продуктовую версию (sberid-sdk.min.js), версию для разработки (sberid-sdk.js) или версию со встроенной отправкой аналитики (sberid-sdk.sa.js) в коде страницы вашего сайта.

<script src="js/libs/sberid-sdk/sberid-sdk.min.js"></script>

После загрузки страницы для инициализации приложения необходимо создать новый экземпляр SberidSDK. Функция создания принимает следующие параметры:

  • params (Object) - параметры для инициализации SDK
  • onSuccessCallback (Function) - функция обратного вызова при успешной авторизации
  • onErrorCallback (Function) - функция обратного вызова при возникновении ошибок во время авторизации

Полный пример подключения библиотеки (example\index.html) и страницы обратного редиректа (example\success.html) размещен в архиве библиотеки .

Пример

const oidcParams = {
response_type: 'code',
client_type: 'PRIVATE',
client_id: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX',
redirect_uri: 'https://example.con/oidc/success',
scope: 'openid name',
nonce: 'NfZscgwxPY7v0kYvuPfnFHA57bqHxQc3lV51Oiaxlo4'
};
 
const style = {
theme: 'default',
text: 'default',
size: 'default',
type: 'default',
custom: {
borderRadius: 4,
height: 44,
'font-family': 'Roboto',
'font-weight': 400,
'box-shadow': 'none'
}
}
 
const sa = {
enable: true,
init: 'auto',
clientId: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX',
clientName: 'ООО Ромашка'
};
 
const params = {
oidc: oidcParams,
container: 'preview',
display: 'popup',
mweb2app: false,
generateState: true,
style: style,
sa: sa,
personalization: true,
notification: {
enable: false,
onNotificationBannerClose: () => {
console.log('Баннер закрыт');
},
onNotificationBannerOpen: () => {
console.log('Баннер открыт');
},
animation: true,
position: 'right',
},
fastLogin: {
enable: false,
timeout: 1000,
mode: 'default',
},
}
 
function onSuccessCallback(result) {
console.log('Вы успешно вошли: ', result)
}
function onErrorCallback(result) {
console.log('Что-то пошло не так: ', result)
}
var sbSDK = new SberidSDK(params, onSuccessCallback, onErrorCallback);

Примечание: функции обратного вызова onSuccessCallback и onErrorCallback будут вызваны после успешной авторизации если страница Сбер ID была открыта в модальном окне.

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

Ниже будут приведены параметры для настройки отображение кнопок и режима работы SDK.

Параметры для инициализации SDK (params)

  • oidc (Object) - параметры OIDC
  • container (String) - класс DOM-элемента, в котором будет размещена кнопка Войти через Сбер ID (не указывается если передан параметр selector)
  • selector (String) - класс DOM-элемента с готовой кнопкой Войти через Сбер ID (не указывается если передан параметр container)
  • display (String) - режим отображения страницы авторизации через Сбер ID (popup - всплывающие окно, page - в текущем окне)
  • mweb2app (Boolean) - включить возможность формирования универсальных ссылок. Подробнее
  • style (Object) - параметры стилизации кнопок
  • personalization (Boolean) - включение персонализированной кнопки
  • notification (Object) - настройки персонализированного баннера
  • fastLogin (Object) - настройки быстрого входа
  • generateState (Boolean) - включить генерацию и проверку state
  • universallink (Object) - параметры для генерации универсальных ссылок
  • sa (Object) - параметры для отправки в SberVisor

Для браузера Internet Explorer параметру display будет присвоено значение page по умолчанию.

Информация

Для работы персонализированной кнопки необходимо направить запрос на support@ecom.sberbank.ru для добавления ваших доменов в список доверенных. В запросе указывается client_id и список доменов, с которых будет выполняться запрос на получение данных для персонализации кнопки. Адрес домена не должен заканчиваться символом "/". Сотрудник банка добавит домен в список разрешенных.

Примечание

Работы персонализированной кнопки не гарантируется в браузере Safari при включенной настройке Конфиденциальность -> Предотвращать перекрестное отслеживание

Параметры для инициализации OIDC (params.oidc)

Подробнее про параметры OIDC можно прочитать здесь

  • client_id (String) - идентификатор системы Партнера, выданный Партнеру при регистрации его системы в Банке
  • scope (String) - наименование групп данных, на которые подписана система Партнера (выдается при регистрации системы в Банке). Значение openid является обязательным и располагается на первой позиции. Разделитель – пробел.
  • redirect_uri (String) - адрес страницы Партнера, на которую будет перенаправлен клиент после успешной аутентификации в системе Банка. Временное ограничение: недопустимы символы “;” и “=“.
  • state (String) - значение, включенное в запрос, которое также возвращается в ответе. Может быть строка любого контента. Для предотвращения подделки межсайтовых запросов используется генерируемое случайным образом уникальное значение. Не добавляется, если generateState равно true.
  • nonce (String) - значение, сгенерированное Партнером для предотвращения атак повторения. Это значение обычно представляет собой случайную уникальную строку или глобальный уникальный идентификатор, которые можно использовать для определения источника запроса. Ограничение по длине значения составляет 64 символа.

Примечание: Если данные запрашиваются асинхронно с сервера, то после получения ответа от сервера обновить параметры можно вызвав метод setOIDCParams(oidc).

Для регистрации приложения в системе Сбер ID и получения своего client_id воспользуйтесь инструкцией на сайте.

const sbSDK = new SberidSDK({
container: 'preview',
display: 'popup'
}, onSuccessCallback, onErrorCallback);
 
fetch('/params')
.then(response => response.json())
.then(params => {
sbSDK.setOIDCParams(params);
});

Параметры для стилизации кнопок (params.style)

  • theme (String) - Цвет кнопки Войти через Сбер ID. Возможные значения:
    • default - зеленая кнопка (по умолчанию)
    • white - белая кнопка
  • type (String) - Тип кнопки Войти через Сбер ID. Возможные значения:
    • default - прямоугольная кнопка (по умолчанию)
    • circle - круглая кнопка
  • text (String) - Текст на кнопке Войти через Сбер ID. Возможные значения:
    • default - Войти по Сбер ID (по умолчанию)
    • resume - Продолжить со Сбер ID
    • login - Войти
    • fill - Заполнить со Сбер ID
  • size (String) - Размер кнопки Войти через Сбер ID. Возможные значения:
    • default - Отступы от логотипа и текста 40px (по умолчанию)
    • small - Отступы от логотипа и текста 12px
    • long - Кнопка растянута на всю ширину блока
  • custom (Object) - дополнительные стили для кнопки:
    • borderRadius (Number) - радиус скругления кнопки (по умолчанию 4)
    • height (Number) - высота кнопки от 40 до 72 пикселей (по умолчанию 44)
    • font-family (String) - Шрифт (по умолчанию 'Roboto')
    • font-weight (Number|String) - Насыщенность шрифта (по умолчанию 400). Значение устанавливается от 100 до 900 с шагом 100.
    • box-shadow (String) - Параметры тени (по умолчанию 'none'). Значение устанавливается в виде none | <тень> [,<тень>]* где <тень>: inset <сдвиг по x> <сдвиг по y> <радиус размытия> <растяжение> <цвет>.

Примечание: с версии 2.0.0 значение circle в параметре type не поддерживается.

Примечание: параметр style может быть пустым, тогда кнопка будет создана с параметрами по умолчанию.

Примеры кнопок

Параметры

Внешний вид

Внешний вид 2.0.0

Тема: по умолчанию

Текст: по умолчанию

Размер: по умолчанию

Тип: по умолчанию

Тема: белая

Текст: по умолчанию

Размер: по умолчанию

Тип: по умолчанию

Тема: по умолчанию

Текст: по умолчанию

Размер: по умолчанию

Тип: круглая

Не поддерживается

Тема: по умолчанию

Текст: по умолчанию

Размер: по умолчанию

Тип: по умолчанию

Дополнительно: Радиус скругления 22

Для удобства генерации кнопок в архиве с библиотекой (example\button-generator\index.html) был размещен генератор кнопок.

Параметры для генерации универсальных ссылок (params.universallink)

  • baseUrl (String) - Базовый адрес адрес для формирования ссылки входа по Сбер ID. Адрес по умолчанию https://online.sberbank.ru/CSAFront/oidc/authorize.do. Если вы используйте тестовый режим, укажите адрес тестовой страницы без параметров.
  • universalLinkUrl (String) - Базовый адрес адрес для формирования универсальной ссылки входа по Сбер ID. Адрес по умолчанию https://online.sberbank.ru/CSAFront/oidc/sberbank_id/authorize.do. Если вы используйте тестовый режим, укажите адрес тестовой страницы без параметров
  • needAdditionalRedirect (Boolean) - Включить формирования адреса дополнительного редиректа у универсальных ссылках для возврата в браузер из которого начался сценарий авторизации.

Подробнее про универсальные ссылки можно почитать на странице.

Параметры для отправки SberVisor (params.sa)

Подробнее про SberVisor можно прочитать здесь (добавить ссылку на портал SberVisor)

  • enable (Boolean) - включение отправки метрик в SberVisor
  • init (String) - способ инициализации скрипта SberVisor: auto - скрипт инициализируется автоматически при создании SDK с параметрами по умолчанию, none - скрипт инициализируется Партнером.
  • clientId (String) - идентификатор системы Партнера, выданный Партнеру при регистрации его системы в Банке. Если параметр не задан, то значение будет взято из параметра params.oidc.client_id.
  • clientName (String) - название системы Партнера. Если параметр не задан, то значение будет взято из html элемента title страницы, на которой отображается кнопка.

Отправка данных в SberVisor доступна только при подключении файла sberid-sdk.sa.js или sberid-sdk.sa.min.js. Если на вашем сайте SberVisor подключается отдельно, то параметр init должен быть в значение none.

Инициализация скрипта SberVisor

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>Init SberVisor</title>
</head>
<body>
<script src="../dist/sa.js"></script>
<script>
window.sberbankIdAnalytics = new SberAnalytics({
url: 'https://sa.online.sberbank.ru:8098/metrics/partners',
buffer: 1,
apiKey: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', //выдается при подключении
sberId: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', //уникальный sberId, выдающийся партнёру client_id
subId: '', //оставляем пустым
appId: '' //оставляем пустым
})
</script>
</body>
</html>

События для отправки в SberVisor

Отправляются следующие события:

  1. Показ кнопки
  2. Нажатие на кнопку
  3. Успешный вход по Сбер ID
  4. Не успешный вход по Сбер ID

Пример передаваемых в SberVisor данных

{
    "meta": {
        "platform": "WEB",
        "screenSize": "1920x1080",
        "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.61 Safari/537.36",
        "systemLanguage": "ru-RU",
        "apiKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "sberId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "timeStamp": "YYYY-MM-DDT00:00:00.000+03:00"
    },
    "profile": {
        "appId": "",
        "subId": "",
        "cookie": [{
            "key": "_sa",
            "value": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
        }]
    },
    "data": [{
        "eventCategory": "Login",
        "eventAction": "sberid_Login_Click",
        "eventType": "Click",
        "properties": [{
            "key": "merchUrl",
            "value": "https://example.con/oidc/success"
        }, {
            "key": "merchantTitle",
            "value": "ООО Ромашка"
        }, {
            "key": "sdkVersion",
            "value": "js_1.0.2"
        }],
        "timeStamp": "YYYY-MM-DDT00:00:00.000+03:00"
    }]
}

Параметры для персонализированного баннера (params.notification)

  • enable (Boolean) - включение персонализированного баннера
  • onNotificationBannerClose (Function) - функция обратного вызова при закрытие баннера
  • onNotificationBannerOpen (Function) - функция обратного вызова при открытие баннера
  • animation (Boolean) - включение анимированного появления/исчезновения персонализированного баннера
  • position (String) - расположение баннера (возможные значения bottom-left, bottom-right, top-left, top-right)
  • offset (Object) - отступы от краев страницы
    • left (Number) - отступ слева (по умолчанию 30px)
    • right (Number) - отступ справа (по умолчанию 30px)
    • top (Number) - отступ сверху (по умолчанию 30px)
    • bottom (Number) - отступ снизу (по умолчанию 30px)
  • autoCloseDelay (Number) - задержка до скрытия баннера в мобильной версии в секундах
  • autoClose (Boolean) - включение скрытия баннера в мобильной версии

Старые значения (left и right) для свойства position будут автоматически преобразованы в bottom-left и bottom-right

Для отображения баннера должна быть включена настройка персонализированной кнопки personalization = true. Для работы персонализированной кнопки необходимо направить запрос на support@ecom.sberbank.ru для добавления ваших доменов в список доверенных. В запросе указывается client_id и список доменов, с которых будет выполняться запрос на получение данных для персонализации кнопки. Адрес домена не должен заканчиваться символом "/". Сотрудник банка добавит домен в список разрешенных.

Параметры для быстрого входа (params.fastLogin)

  • enable (Boolean) - включение быстрого входа
  • timeout (Number) - задержка до принудительного завершения быстрого входа при проблемах с создание запроса на сервер
  • mode (String) - режим работы быстрого входа ( auto - автоматический запуск быстрого входа после инициализации SDK, default - запуск быстрого входа по нажатию на кнопку)

Для выполнения быстрого входа должна быть включена настройка персонализированной кнопки personalization = true. Для работы персонализированной кнопки необходимо направить запрос на support@ecom.sberbank.ru для добавления ваших доменов в список доверенных. В запросе указывается client_id и список доменов, с которых будет выполняться запрос на получение данных для персонализации кнопки. Адрес домена не должен заканчиваться символом "/". Сотрудник банка добавит домен в список разрешенных.

Быстрый вход не работает в браузере Safari. Чтобы он заработал пользователю необходимо отключить настройку "Предотвращать перекрестное отслеживание" в настройках конфиденциальности.

Параметры для функции обратного вызова

Если данные окно авторизации через Сбер ID открывалось в модальном окне, то на странице указанной в параметре redirect_uri необходимо вызвать метод successWindowListener()

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>Success</title>
</head>
<body>
<script src="../dist/sberid-sdk.js"></script>
<script>
(function () {
var sbSDK = new SberidSDK({});
 
sbSDK.successWindowListener();
})();
</script>
</body>
</html>

Успешная авторизация по Сбер ID

Если страница авторизации по Сбер ID была открыта в модальном окне, то после редиректа по адресу, указанному в параметре oidc.redirect_uri, будет вызвана функция onSuccessCallback принимающая в качестве аргумента объект, содержащий следующие значения:

  • code (String) - код авторизации для получение access token
  • state (String) - значение, включенное в запрос, которое было передано на страницу авторизации по Сбер ID

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


function onSuccessCallback(result) {
fetch('/login?' + new URLSearchParams(result))
.then(response => response.json())
.then(params => {
console.log(params);
});
}

Ошибка при входе по Сбер ID

Если страница авторизации по Сбер ID была открыта в модальном окне и во время процесса авторизации произошла ошибка, то после редиректа по адресу, указанному в параметре oidc.redirect_uri, будет вызвана функция onErrorCallback принимающая в качестве аргумента объект, содержащий следующие значения:

  • status (String) - статус ошибки
  • code (String) - код ошибки
  • state (String) - значение, включенное в запрос, которое было передано на страницу авторизации по Сбер ID
  • description (String) - текстовое описание ошибки

Примечание: в зависимости от кода ошибки можно показать пользователю уведомление с возможной причиной ошибки

function onErrorCallback(result) {
console.info('Ошибка при авторизации по Сбер ID: ', result);
alert(`Произошла ошибка: <b>${result.description}</b>`);
}

Описание кодов ошибок

  • invalid_request - В запросе отсутствуют обязательные атрибуты
  • unauthorized_client - Партнер не зарегистрирован или заблокирован в Банке, либо значение атрибута client_id не соответствует формату
  • unsupported_response_type - Значение атрибута response_type не равно« code»
  • invalid_scope - Значение атрибута scope не содержит параметр openid в начальной позиции либо запрошенный scope содержит значения, недоступные для Партнера
  • access_denied - Клиент отказался от передачи согласий
  • invalid_state - Значение атрибута state не соответствует изначальному
  • window_closed - Клиент закрыл окно авторизации по Сбер ID

Список изменений

v 2.3.1

  1. Добавлено проксирование параметров authApp и app_redirect_uri в запрос к Сбер ID
  2. Добавлена возможность отключать запуск универсальной ссылки get-параметром is_universal_link
  3. Добавлена подставка в запрос к Сбер ID utm-меток переданных при вызове сайта партнера
  4. Обновлена версия Sberbank Analytics до 1.40
  5. Добавлены новые возможные значения для расположения персонализированного баннера

v 2.3.0

  1. Добавлен быстрый вход
  2. Версия скрипта для формирования универсальных ссылок обновлена до 1.0.7

v 2.2.0

  1. Добавлен персонализированный баннер

v 2.1.0

  1. Добавлен новый параметр personalization для включения функционала персонализированной кнопки

v 2.0.0

  1. Ребрендинг кнопок

v 1.0.4

  1. Убрана лишняя генерация state при возврате на страницу успеха партнера

v 1.0.3

  1. Версия скрипта для формирования универсальных ссылок обновлена до 1.0.5
  2. Исправлена ошибка в successWindowListener при открытии страницы через target="_blank"
  3. Исправлена ошибка с двойным знаком ?? при формировании адреса ссылки

v 1.0.2

  1. Версия скрипта для формирования универсальных ссылок обновлена до 1.0.4
  2. Добавлена поддержка SberVisor
  3. Исправлена работа скрипта в браузере Internet Explorer
  4. Исправлены мелкие баги в работе SDK