@sberid/js-sdk

Javascript SDK для Партнеров Сбер ID, упрощающая подключение Сбер ID на сайте.

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

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

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

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

*Примечание: Если данные запрашиваются асинхронно с сервера, то после получения ответа от сервера обновить параметры можно вызвав метод 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.universalLink)

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) - Включить формирования адреса дополнительного редиректа у универсальных ссылках для возврата в браузер из которого начался сценарий авторизации.

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

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

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

Параметры для отправки Sberbank Analytics (params.buttonProps)

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

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

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

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

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

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

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

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.

Примечание: полученные данные необходимо отправить на 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) - текстовое описание ошибки Примечание: в зависимости от кода ошибки можно показать пользователю уведомление с возможной причиной ошибки

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

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

@sberid/js-sdk

@sberid/js-sdk

Оглавление

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

Установка

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

Пример

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

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

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

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

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

Параметры для отправки Sberbank Analytics (params.buttonProps)

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

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

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

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

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

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

Копирайт

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

@sberid/js-sdk

@sberid/js-sdk

Оглавление

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

Установка

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

Пример

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

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

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

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

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

Параметры для отправки Sberbank Analytics (params.buttonProps)

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

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

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

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

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

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

Копирайт

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads