Javascript SDK для Партнеров Сбер ID, упрощающая подключение Сбер ID на сайте.
- @sberid/js-sdk
- Оглавление
- Общие сведения
- Установка
- Подключение на сайте
- Пример
- Описание параметров
- Параметры для инициализации SDK (params)
- Параметры для инициализации OIDC (params.oidc)
- Параметры для генерации универсальных ссылок (params.universalLink)
- Параметры для отправки Sberbank Analytics (params.sa)
- Параметры для отправки Sberbank Analytics (params.buttonProps)
- Параметры для функции обратного вызова
- Параметры для персонализированного баннера (params.notification)
- Параметры для быстрого входа (params.fastLogin)
- Описание кодов ошибки
- Копирайт
Javascript SDK для Партнеров Сбер ID, упрощающая получение кода авторизации (AuthCode).
Для получения access token и данных клиента рекомендуется воспользоваться Java SDK или Python SDK.
SDK позволяет:
- генерировать стилизованную кнопку «Войти по Сбер ID»;
- выбирать способ отображения страницы авторизации Сбер ID (модальное окно, обычный переход);
- включить режим формирования универсальных ссылок для авторизации в мобильной версии браузера через мобильное приложение Сбербанк Онлайн;
- включить генерацию и проверку state в процессе аутентификации;
- отравлять в Sberbank Analytics события по показу кнопки, нажатию на кнопку и успешном/не успешном входе по Сбер ID.
- быстрый вход без необходимости перехода на страницу OIDC
- персонализированная кнопка входа
Для выполнения успешных запросов Вам необходимо зарегистрировать Ваше приложение в банке и подписать договор. Заявку можно оставить по ссылке
Используя npm:
npm i --save @sberid/js-sdk
Используя yarn:
yarn add @sberid/js-sdk
Подключите продуктовую версию (sberid-sdk.production.js) или добавить (index.esm.js) в проект для импорта небходимых зависимостей. Подключить файл стилей (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);
Примечание: функции обратного вызова onSuccessCallback и onErrorCallback будут вызваны после успешной авторизации если страница Сбер ID была открыта в модальном окне
Ниже будут приведены параметры для настройки отображение кнопок и режима работы SDK
- oidc (Object) - параметры OIDC
- container (String | HTMLDivElement) - селектор DOM-элемента или HTMLElement в котором будет размещена кнопка Войти по Сбер ID
- display (String) - режим отображения страницы авторизации по Сбер ID (popup - высплывающе окно, page - в текущем окне)
- mweb2app (Boolean) - включить возможность формирования универсальных ссылок. Подробнее
- generateState (Boolean) - включить генерацию и проверку state
- personalization (Boolean) - использовать ли персонализированную кнопку
- notification (Object) - настройки персонализированного баннера
- changeUser (Boolean) - настройки включения функционала смены пользователя
- fastLogin (Object) - настройки быстрого входа
- bottonProps (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 и список доменов, с которых будет выполняться запрос на получение данных для персонализации кнопки. Адрес домена не должен заканчиваться символом "/". Сотрудник банка добавит домен в список разрешенных. Примечание: Работы персонализированной кнопки не гарантируется в браузере Safari при включенной настройке Конфиденциальность -> Предотвращать перекрестное отслеживание
Подробнее про параметры 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)))).
*Примечание: Если данные запрашиваются асинхронно с сервера, то после получения ответа от сервера обновить параметры можно вызвав метод setOIDCParams(oidc)*
Примечание: Для регистрации приложения в системе Сбер ID и получения своего client_id воспользуйтесь инструкцией на сайте
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) - Включить формирования адреса дополнительного редиректа у универсальных ссылках для возврата в браузер из которого начался сценарий авторизации.
Подробнее про универсальные ссылки можно почитать на странице.
- 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 была открыта в модальном окне, то после редиректа по адресу, указанному в параметре oidc.redirect_uri, будет вызвана функция onSuccessCallback принимающая в качестве аргумента объект, содержащий следующие значения:
- code (String) - код авторизации для получение authToken'a
- state (String) - значение, включенное в запрос, которое было передано на страницу авторизации по Сбер ID.
Примечание: полученные данные необходимо отправить на endpoint авторизации Вашего сайта, для получения информации о пользователе.
function onSuccessCallback(result) {
fetch('/login?' + new URLSearchParams(result))
.then((response) => response.json())
.then((params) => {
console.log(params);
});
}
Если страница авторизации по Сбер ID была открыта в модальном окне и во время процесса авторизации произошла ошибка, то после редиректа по адресу, указанному в параметре oidc.redirect_uri, будет вызвана функция onErrorCallback принимающая в качестве аргумента объект, содержащий следующие значения:
- code (String) - код ошибки
- error (String) - значение, включенное в запрос, которое было передано на страницу авторизации по Сбер ID.
- description (String) - текстовое описание ошибки Примечание: в зависимости от кода ошибки можно показать пользователю уведомление с возможной причиной ошибки
- 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
Автор: Сбер ID Сайт: https://www.sberbank.ru/ru/person/dist_services/sberbankid/forbusiness