ym88659208ym87991671
JavaScript SDK Sber ID | Документация SmartMarket
Skip to main content

JavaScript SDK

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

Javascript SDK для Партнеров Сбер ID, упрощающая получение кода авторизации (AuthCode) Для получения access token и данных клиента рекомендуется воспользоваться Java SDK или Python SDK.

SDK позволяет:

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

Подключение на сайте

Подключите продуктовую версию (../sberid-sdk.production.js) или добавить (../dist/index.esm.js) в проект для импорта небходимых зависимостей. Подключить файл стилей (../dist/styles/common.css) в блок head.

<link href="js/libs/sberid-sdk/styles/common.css" rel="stylesheet">
<script src="js/libs/sberid-sdk/sberid-sdk.production.js"></script>

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

  • params (Object) - параметры для инициализации SDK.

Пример

const oidcParams = {
response_type: 'code',
client_type: 'PRIVATE',
client_id: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX',
redirect_uri: 'https://example.com/oidc/success',
state: 'ut8Ar4MUZEMDPIiD2ko914y37s0Q0VKJgxeCkU0yzTY',
scope: 'openid name',
nonce: 'NfZscgwxPY7v0kYvuPfnFHA57bqHxQc3lV51Oiaxlo4',
};

const sa = {
enable: true,
init: 'auto',
clientId: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX',
clientName: 'ООО Ромашка',
};

const onSuccessCallback = (result) => {
console.log('Вы успешно вошли: ', result);
}
const onErrorCallback = (result) => {
console.log('Что-то пошло не так: ', result);
}

const params = {
oidc: oidcParams,
container: '.preview',
display: 'popup',
mweb2app: false,
generateState: false,
sa: sa,
notification: {
enable: false,
onNotificationBannerClose: () => {
console.log('Баннер закрыт');
},
onNotificationBannerOpen: () => {
console.log('Баннер открыт');
},
animation: true,
position: 'right',
},
personalization: true,
fastLogin: {
enable: true,
timeout: 1000,
mode: 'default',
},
utmProxyDisabled: false,
buttonProps: {
type: 'default',
custom: {
anonymous: 'Вход',
personal: 'Вход как {{userName}}',
},
},
onSuccessCallback,
onErrorCallback,
};

var sbSDK = new SberidSDK(params);
note

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

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

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

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

  • oidc (Object) - параметры OIDC;
  • container (String | HTMLDivElement) - селектор DOM-элемента или HTMLElement в котором будет размещена кнопка Войти по Сбер ID;
  • display (String) - режим отображения страницы авторизации по Сбер ID (popup - высплывающе окно, page - в текущем окне);
  • mweb2app (Boolean) - включить возможность формирования универсальных ссылок. Подробнее;
  • generateState (Boolean) - включить генерацию и проверку state;
  • sa (Object) - параметры для отправки в SberVisor;
  • personalization (Boolean) - использовать ли персонализированную кнопку;
  • notification (Object) - настройки персонализированного баннера;
  • changeUser (Boolean) - настройки включения функционала смены пользователя;
  • fastLogin (Object) - настройки быстрого входа;
  • buttonProps (Object) - настройки для стилизации кнопок;
  • utmProxyDisabled (Boolean) - отключить проксирование переданых в url utm_меток в запрос к Сбер ID (Список меток: utm_source utm_medium utm_campaign utm_term utm_content);
  • onSuccessCallback (Function) - функция обратного вызова при успешной авторизации;
  • onErrorCallback (Function) - функция обратного вызова при возникновении ошибок во время авторизации.

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

note

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

Параметры для инициализации OIDC

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

  • client_id (String) - идентификатор системы Партнера, выданный Партнеру при регистрации его системы в Банке (получено в письме от банка с адреса «support@ecom.sberbank.ru» с темой «Сбербанк Профиль»);
  • scope (String) - наименование групп данных, на которые подписана система Партнера (выдается при регистрации системы в Банке). Значение openid является обязательным и располагается на первой позиции. Разделитель – пробел;
  • redirect_uri (String) - адрес страницы Партнера, на которую будет перенаправлен клиент после успешной аутентификации в системе Банка. Временное ограничение: недопустимы символы “;” и “=“;
  • state (String) - значение, включенное в запрос, которое также возвращается в ответе. Может быть строка любого контента. Для предотвращения подделки межсайтовых запросов используется генерируемое случайным образом уникальное значение;
  • nonce (String) - если этот параметр сохранился на бэке sdk, то Партнер этот параметр не передает, параметр берется с бэка sdk;
  • code_challenge (String) - хешированное значение секретного кода code_verifier Партнера. Хеширование выполняется методом, указанным в code_challenge_method. code_challenge = BASE64URL-ENCODE (SHA256 (ASCII (code_verifier)))).
note

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

const sbSDK = new SberidSDK(
{
container: 'preview',
display: 'popup',
},
);

fetch('/params')
.then((response) => response.json())
.then((params) => {
sbSDK.setOIDCParams(params);
});

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

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

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

Параметры для отправки в SberVisor

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

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

  • type (String) - вариант отображаемого на кнопке текста (возможные значения: 'default' | 'resume' | 'login' | 'fill' | 'custom');
  • loader (Boolean) - отображение лоадера на кнопках;
  • logo (String) - отображение логотипа Сбер ID на кнопке;
  • custom (Object) - тектовки кнопок при выбранном значение type=custom;
    • anonymous (String) - текст для обычной кнопки;
    • personal (String) - текст для персонализированной кнопки;

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

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

Параметры для персонализированного баннера

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

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

Параметры для быстрого входа

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

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

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

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

  • code (String) - код авторизации для получение authToken'a;
  • state (String) - значение, включенное в запрос, которое было передано на страницу авторизации по Сбер ID.
note

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

function onSuccessCallback(result) {
fetch('/login?' + new URLSearchParams(result))
.then((response) => response.json())
.then((params) => {
console.log(params);
});
}
Ошибка при входе по Сбер ID

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

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

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

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

  • 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.
Обновлено 22 июня 2022

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

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