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

Содержание

Введение
Как это работает
Подключение
Быстрый старт
Настройки
Callback-и
Silent-авторизация
Безопасность
Пример полной страницы

Введение

RegosOAuthSDK — это готовая JavaScript-библиотека для кнопки "Войти через REGOS". Она нужна, если вы хотите быстро добавить вход пользователя на сайт и не писать весь OAuth-процесс вручную.

SDK открывает авторизацию REGOS, получает authorization code, обменивает его на токены через PKCE, запрашивает профиль пользователя и сообщает вашему сайту результат через callback. После успешного входа кнопка заменяется аватаром пользователя с меню.

Клиентский секрет для SDK не нужен и не должен использоваться в браузере. Для виджета достаточно clientId и зарегистрированного redirectUri.

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

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

Меню после входа:

Как это работает

Пользователь нажимает кнопку входа. SDK создает PKCE-защиту и открывает страницу REGOS. На desktop обычно используется popup, а на мобильных устройствах и в PWA SDK переходит на redirect-flow. Если popup заблокирован браузером, SDK также использует redirect.

После входа REGOS возвращает пользователя на ваш redirectUri. На этой странице подключается небольшой обработчик regos-redirect.js: он передает результат обратно основному окну или сохраняет его для redirect-flow. Затем SDK получает токены и вызывает onData(user, access_token).

SDK хранит токены в браузере, чтобы пользователь не входил заново при каждом обновлении страницы. Профиль пользователя кэшируется только на короткое время в памяти страницы и при необходимости запрашивается снова.

Подключение

Подключите SDK на странице, где должна появиться кнопка:

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

Добавьте контейнер. По умолчанию SDK ищет элемент с id regos-login.

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

Создайте страницу возврата, например https://your.app/oauth/redirect.html. Этот адрес должен быть зарегистрирован для вашего клиента в REGOS. Внутри страницы достаточно подключить redirect-обработчик:

<!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>

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

После подключения скрипта вызовите RegosOAuthSDK.initialize. Минимально нужны clientId, redirectUri и callback onData.

RegosOAuthSDK.initialize({
    clientId: 'your_client_id',
    redirectUri: 'https://your.app/oauth/redirect.html',
    language: 'ru',
    buttonSize: 'm',
    buttonTheme: 'light',
    buttonType: 'text',
    buttonTextType: 'full',
    silent: false,
    onData: (user, accessToken) => {
        if (user) {
            console.log('Пользователь вошел:', user);
            console.log('Access token:', accessToken);
        } else {
            console.log('Пользователь не авторизован');
        }
    },
    onLogout: () => {
        console.log('Локальный выход выполнен');
    },
    onError: (error) => {
        console.error('Ошибка REGOS:', error.message);
    }
});

Если токены уже сохранены и еще действуют, SDK сразу покажет профиль и вызовет onData. Если токены недействительны, будет показана кнопка входа.

Настройки

Большую часть настроек можно оставить по умолчанию. Ниже перечислены параметры, которые чаще всего нужны при подключении.

Параметр	Обязательный	Описание
`clientId`	Да	Идентификатор приложения, выданный REGOS.
`redirectUri`	Да	Страница возврата. Должна быть зарегистрирована в REGOS.
`containerId`	Нет	ID контейнера. По умолчанию `regos-login`.
`buttonSize`	Нет	Размер кнопки: `s`, `m`, `l`. По умолчанию `m`.
`buttonTheme`	Нет	Тема: `light` или `dark`. По умолчанию `light`.
`buttonType`	Нет	Вид кнопки: `text`, `icon-text`, `icon`. По умолчанию `text`.
`buttonTextType`	Нет	Длина текста: `full` или `short`. По умолчанию `full`.
`buttonBorderRadius`	Нет	Радиус скругления в пикселях. По умолчанию `4`.
`language`	Нет	Язык интерфейса SDK: `ru`, `en`, `uz`.
`flow`	Нет	`auto` или `redirect`. По умолчанию `auto`.
`silent`	Нет	Попытаться войти без показа окна авторизации, если у пользователя уже есть сессия REGOS. По умолчанию `false`.
`debug`	Нет	Писать диагностические сообщения в консоль. По умолчанию `false`.

Callback-и

onData(user, accessToken) — главный callback. Он вызывается после входа, после успешного обновления токена и после потери авторизации. Если пользователь авторизован, user содержит данные профиля, а accessToken можно использовать для запросов к вашему API. Если авторизация потеряна, оба значения будут пустыми.

onLogout() вызывается после локального выхода через меню SDK. Локальный выход очищает токены в браузере и возвращает кнопку. Если вам нужен полный выход из REGOS, используйте отдельный переход на logout REGOS или настройте серверный сценарий выхода.

onError(error) вызывается при сетевой ошибке, ошибке токена, закрытом popup, неуспешной silent-авторизации или другой проблеме. Для пользователя лучше показывать короткое понятное сообщение, а подробности писать в диагностику только при включенном debug.

Silent-авторизация

Silent-авторизация пытается войти без popup и redirect, если у пользователя уже есть активная сессия REGOS. SDK открывает скрытый iframe с prompt=none. Если REGOS может подтвердить пользователя без экрана входа, SDK получает токены и вызывает onData.

RegosOAuthSDK.initialize({
    clientId: 'your_client_id',
    redirectUri: 'https://your.app/oauth/redirect.html',
    silent: true,
    onData: (user, token) => {
        console.log(user ? 'Silent-вход успешен' : 'Пользователь не вошел');
    }
});

Silent-авторизация не гарантирована. Некоторые браузеры блокируют cross-site cookies или iframe-сценарии. Если silent-вход не удался, SDK покажет обычную кнопку входа.

Безопасность

Используйте HTTPS для сайта и redirect-страницы. Проверяйте, что redirectUri совпадает с зарегистрированным адресом. Не добавляйте client_secret в JavaScript и не храните его в браузере. Обрабатывайте состояние "не авторизован" так же явно, как успешный вход.

Если ваш сайт отправляет access_token на backend, передавайте его только по HTTPS и проверяйте токен на сервере перед выполнением защищенных действий.

Пример полной страницы

<!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: 'https://your.app/oauth/redirect.html',
            buttonSize: 'm',
            buttonTheme: 'light',
            buttonType: 'icon-text',
            buttonTextType: 'short',
            language: 'ru',
            flow: 'auto',
            silent: false,
            onData: (user, accessToken) => {
                console.log(user, accessToken);
            },
            onError: (error) => {
                console.error(error.message);
            }
        });
    </script>
</body>
</html>