Введение Единый профиль REGOS Кнопка авторизации

Кнопка авторизации

Содержание

Введение
Установка
Быстрый старт
Конструктор кнопки
Подробное описание опций
Сценарии работы
Тихая авторизация (Silent Authentication)
Интерфейс после авторизации
Обработка ошибок
Примеры интеграции
Обновление токена
Рекомендации

Введение

RegosOAuthSDK — это легковесная JavaScript-библиотека для простой интеграции кнопки "Войти через REGOS" на ваш сайт или приложение с использованием OAuth 2.0 и OpenID Connect. После успешной авторизации пользователя кнопка автоматически заменяется круглым аватаром с выпадающим меню, содержащим информацию о профиле и опции управления.

Библиотека обеспечивает безопасный процесс авторизации, включая проверку существующих токенов при загрузке страницы. Если токены валидны, сразу отображается профиль пользователя без необходимости повторного входа.

Возможности библиотеки

Настраиваемый внешний вид кнопки: Размер (s/m/l), тема (light/dark), тип (text/icon-text/icon), тип текста (full/short), радиус скругления.
Мультиязычность: Поддержка русского (ru), английского (en) и узбекского (uz) языков для текстов кнопки и меню.
Без зависимостей: Работает на чистом JavaScript, автоматически подгружает стили.
Безопасность: Использует Authorization Code Flow с PKCE для защиты от атак.
Автоматическая обработка: Проверка токенов при инициализации, отображение профиля, если пользователь уже авторизован.
Тихая авторизация (silent): Автоматический вход без попапа через iframe, если сессия активна на сервере REGOS.
API на основе Promise: Легкий вызов методов для авторизации, обновления токенов и выхода.
Обработка ошибок: Callbacks для успеха, выхода и ошибок; поддержка debug-режима для логов.
Хранение токенов: В sessionStorage (по умолчанию) или localStorage для персистентности.

Важно: Зарегистрируйте приложение в REGOS для получения clientId. Redirect URI должен совпадать с зарегистрированным.

Сервер использует scopes, указанные при регистрации клиента.

Внешний вид блока авторизации

Пример темной кнопки:

Пример светлой кнопки:

Отображение профиля после успешной авторизации:

Установка

Подключите библиотеку через CDN:

<script src="https://auth.regos.uz/widget/regos-oauth-sdk.js"></script>

Создайте контейнер для кнопки:

Добавьте <div> с уникальным ID (по умолчанию "regos-login").

<div id="regos-login"></div>

Настройте страницу перенаправления (redirect URI):

Создайте файл (например, redirect.html) для обработки ответа в попап/iframe. Эта страница отправляет код авторизации обратно в основное окно и закрывается.

<!DOCTYPE html>
<html lang="ru">
<head>
    <title>REGOS Redirect</title>
</head>
<body>
    <script src="https://auth.regos.uz/widget/regos-redirect.js"></script>
</body>
</html>

Объяснение: regos-redirect.js парсит параметры URL (code, state, error), отправляет их через postMessage в родительское окно (или сохраняет в localStorage для redirect-flow) и перенаправляет на сохранённый returnUrl.

Быстрый старт

Инициализируйте SDK с помощью RegosOAuthSDK.initialize(config). Метод возвращает Promise с объектом { handler, refreshToken, logout }:

handler(): Запускает авторизацию (popup или redirect в зависимости от flow). Не сработает, если пользователь уже авторизован.
refreshToken(): Обновляет access token с помощью refresh token.
logout(): Локально очищает токены и возвращает кнопку входа.

При инициализации автоматически проверяются токены: если валидны, отображается профиль; если silent: true — пытается тихая авторизация.

Пример базовой инициализации:

RegosOAuthSDK.initialize({
    clientId: 'regos_983436cgv2536fqvsac5623d78232dxfs',
    redirectUri: 'https://example.com/oauth/redirect.html',
    language: 'ru',
    buttonSize: 'm',
    buttonTheme: 'light',
    silent: false,
    buttonBorderRadius: 6,
    onLoginSuccess: (user) => {
        console.log(`Пользователь авторизован: ${JSON.stringify(user)}`);
    },
    onLogout: () => {
        console.log('Выход выполнен');
    },
    onError: (err) => {
        console.error(`Ошибка: ${err.message}`);
    },
    tokenStorage: sessionStorage
})
.then(({ handler, refreshToken, logout }) => {
    // Пример обновления токена
    document.getElementById('refresh-btn').addEventListener('click', () => {
        refreshToken()
            .then(tokens => console.log('Обновлено:', tokens))
            .catch(err => console.error('Ошибка:', err));
    });
    // Пример выхода
    document.getElementById('logout-btn').addEventListener('click', () => {
        logout();
    });
})
.catch(err => console.error('Инициализация не удалась:', err));

Объяснение: Если токены уже есть и валидны, профиль отображается сразу. Handler() использует popup на десктопе и redirect на мобильных (автоопределение по UA, touch, screen size), если flow: 'auto'.

Конструктор кнопки

Для удобной визуальной кастомизации кнопки "Войти через REGOS" без написания кода используйте онлайн-конструктор, доступный по адресу: https://docs.regos.uz/ru/sso/sso-button/constructor.

Подробное описание опций

Параметр	Тип	Обязательно	Описание
clientId	string	Да	ID приложения из REGOS.
redirectUri	string	Да	URL страницы перенаправления (должен быть зарегистрирован в REGOS).
containerId	string	Нет	ID контейнера для кнопки/профиля (по умолчанию 'regos-login').
buttonSize	string	Нет	Размер кнопки: 's', 'm' (по умолчанию), 'l'.
buttonTheme	string	Нет	Тема: 'light' (по умолчанию), 'dark'.
buttonBorderRadius	number	Нет	Радиус скругления кнопки (число в пикселях, по умолчанию 4).
buttonType	string	Нет	Тип кнопки: 'text' (только текст), 'icon-text' (иконка + текст, по умолчанию), 'icon' (только иконка).
buttonTextType	string	Нет	Тип текста кнопки: 'full' (полный текст, по умолчанию), 'short' (короткий текст).
language	string	Нет	Язык: 'ru' (по умолчанию), 'en', 'uz'.
flow	string	Нет	Тип потока авторизации: 'auto' (автоопределение popup/redirect, по умолчанию), 'redirect' (всегда redirect).
onLoginSuccess	function	Нет	Callback после входа: получает объект пользователя (user).
onLogout	function	Нет	Callback после выхода.
onError	function	Нет	Callback для ошибок (по умолчанию console.error).
tokenStorage	Storage	Нет	Хранилище: sessionStorage (по умолчанию) или localStorage.
silent	boolean	Нет	Включить тихую авторизацию при инициализации (по умолчанию false).
debug	boolean	Нет	Включить debug-логи в консоль (по умолчанию false).

Сценарии работы

Проверка токенов: При инициализации SDK проверяет наличие и валидность токенов в хранилище (sessionStorage или localStorage).
Если токены валидны: Немедленно отображается профиль (аватар с меню).
Если silent: true: Пытается тихая авторизация через iframe. Успех — профиль; неудача — рендер кнопки.
Иначе: Рендерится кнопка входа.
При нажатии на кнопку: Запускается авторизация: popup или redirect в зависимости от flow ('auto' — автоопределение по устройству).
После успешной авторизации: Кнопка заменяется аватаром (круглое изображение профиля или инициалы). Клик по аватару открывает меню с именем, email и ссылками (profile, edit, logout на auth.regos.uz). Меню закрывается кликом вне области.

Внешний вид кнопки и аватара: Кнопка рендерится с иконкой (опционально), текстом (в зависимости от buttonType и buttonTextType), применяются классы для темы и размера. Аватар — круглый элемент с изображением или инициалами, клик toggles меню.

Тихая авторизация (Silent Authentication)

Тихая авторизация позволяет автоматически войти пользователя без попапа/redirect, если сессия REGOS активна. Реализовано через скрытый iframe с prompt=none.

Включение: Установите silent: true в config. Запускается только при инициализации (ручного вызова нет).
Процесс: Iframe загружает auth URL с prompt=none, получает code через postMessage, обменивает на токены.
Ограничения: Требует активной сессии на сервере; не работает в cross-origin изоляции (Safari). Таймаут: 10 сек.
Отладка: С debug: true логируют попытки и ошибки (e.g., "Silent auth failed: login_required").

Пример с silent:

RegosOAuthSDK.initialize({
    clientId: 'your_client_id',
    redirectUri: 'https://your-site.com/redirect.html',
    silent: true,
    debug: true
})
.then(() => console.log('Инициализация завершена, silent auth выполнен если возможно'))
.catch(err => console.error('Silent auth ошибка:', err));

Интерфейс после авторизации

Кнопка заменяется аватаром.
Клик по аватару: выпадающее меню с данными профиля.
Локальный logout(): очищает токены, возвращает кнопку, вызывает onLogout.

Обработка ошибок

Callbacks: onError для сетевых/авторизационных ошибок (e.g., invalid_token).
Promise rejections: В handler(), refreshToken() — используйте catch для обработки.
Redirect-страница: Отображает ошибки (e.g., "REGOS authorization error: access_denied").
Silent ошибки: Логируются (debug: true), fallback на кнопку.
Общие случаи: Popup закрыт — fallback на redirect; нет crypto API — throw error.

Все ошибки важно обрабатывать в onError и catch блоках.

Пример обработки:

onError: (err) => alert(`Ошибка авторизации: ${err.message}`)

Примеры интеграции

Vanilla JS с кастомизацией

<!DOCTYPE html>
<html lang="ru">
<head>
    <title>REGOS Login</title>
</head>
<body>
    <div id="regos-login"></div>
    <script src="https://auth.regos.uz/widget/regos-oauth-sdk.js"></script>
    <script>
        RegosOAuthSDK.initialize({
            clientId: 'your_client_id',
            redirectUri: 'redirect.html',
            buttonSize: 'l',
            buttonType: 'icon-text',
            buttonTextType: 'short',
            buttonBorderRadius: 14,
            language: 'en',
            flow: 'auto',
            silent: true
        }).then(({ handler }) => handler());
    </script>
</body>
</html>

Интеграция в React

// React example
useEffect(() => {
    RegosOAuthSDK.initialize({ /* config */ })
        .then(({ handler }) => setAuthHandler(handler));
}, []);

Пример с buttonType

buttonType: "icon-text", // варианты: "text", "icon-text", "icon"

Обновление токена

refreshToken() использует refresh_token для получения нового access_token, обновляет хранилище и профиль. При ошибке: logout().

Пример:

refreshToken()
    .then(tokens => console.log('Новые токены:', tokens)) // { access_token, refresh_token, ... }
    .catch(err => console.error('Обновление не удалось:', err));

Объяснение: Вызывайте периодически (e.g., перед API-запросами) для поддержания сессии.