@sberid/js-sdk

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)
        • Успешная авторизация по Сбер 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) - функция обратного вызова при возникновении ошибок во время авторизации

Для работы персонализированной кнопки необходимо направить запрос на [email protected] для добавления ваших доменов в список доверенных. В запросе указывается client_id и список доменов, с которых будет выполняться запрос на получение данных для персонализации кнопки. Адрес домена не должен заканчиваться символом "/". Сотрудник банка добавит домен в список разрешенных. Примечание: Работы персонализированной кнопки не гарантируется в браузере Safari при включенной настройке Конфиденциальность -> Предотвращать перекрестное отслеживание

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

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

• client_id (String) - идентификатор системы Партнера, выданный Партнеру при регистрации его системы в Банке (получено в письме от банка с адреса «[email protected]» с темой «Сбербанк Профиль»)
• 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). Для работы персонализированной кнопки необходимо направить запрос на [email protected] для добавления ваших доменов в список доверенных. В запросе указывается client_id и список доменов, с которых будет выполняться запрос на получение данных для персонализации кнопки. Адрес домена не должен заканчиваться символом "/". Сотрудник банка добавит домен в список разрешенных.

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

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

Для выполнения быстрого входа должна быть включена настройка персонализированной кнопки (personalization = true). Для работы персонализированной кнопки необходимо направить запрос на [email protected] для добавления ваших доменов в список доверенных. В запросе указывается 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