Как настроить вход через OAuth

Это руководство проведет вас через настройку социального входа, позволяющего клиентам авторизовываться на клиентских ПК с помощью аккаунтов Google, Facebook, Apple, X или Discord. HandyCafe использует поток Device Authorization Grant (RFC 8628), предназначенный для устройств без полноценного браузера. Клиенты сканируют QR-код телефоном для аутентификации.

Что вам понадобится

• Доступ администратора к HandyCafe Server.
• Аккаунт Google Cloud Console (для Google OAuth) или аналогичный доступ к порталу разработчика другого провайдера.
• HandyCafe Server запущен и доступен в вашей сети.
• Хотя бы один подключенный клиентский ПК для тестирования.

Как работает Device Flow OAuth в HandyCafe

Краткое описание процесса:

1. Клиент на незанятом ПК нажимает кнопку социального входа (например, «Войти через Google»).
2. Клиент отправляет запрос на начало OAuth серверу.
3. Сервер обращается к эндпоинту авторизации устройства провайдера и получает код устройства, пользовательский код и URL для верификации.
4. На экране клиента отображается QR-код и пользовательский код.
5. Клиент сканирует QR-код телефоном и проходит аутентификацию у провайдера.
6. Сервер опрашивает провайдера до завершения аутентификации.
7. Сервер создает запрос на вход OAuth, отображаемый на странице Запросы.
8. Администратор или кассир подтверждает запрос.
9. Создается новый аккаунт участника (или привязывается существующий) и клиент авторизуется.

Как настроить Google OAuth

Google является наиболее распространенным провайдером. Этот раздел охватывает все шаги от создания проекта Google Cloud до тестирования первого входа.

Часть A: создание учетных данных Google Cloud

1. Откройте Google Cloud Console по адресу https://console.cloud.google.com в браузере.
2. Создайте новый проект или выберите существующий. Назовите его, например «HandyCafe OAuth».
3. Перейдите в APIs & Services > OAuth consent screen.
4. Выберите External как тип пользователей (если у вас нет организации Google Workspace для внутреннего использования).
5. Заполните обязательные поля: App name («Название вашего кафе»), User support email, Developer contact email.
6. Нажимайте Save and Continue через разделы Scopes и Test Users. Специальные scopes не нужны. Стандартных email и profile достаточно.
7. Перейдите в APIs & Services > Credentials.
8. Нажмите Create Credentials > OAuth client ID.
9. Для Application type выберите TVs and Limited Input devices. Это критически важно. HandyCafe использует поток device authorization grant, требующий именно этот тип клиента.
10. Введите имя клиента (например, «HandyCafe Device Flow»).
11. Нажмите Create.
12. Скопируйте Client ID и Client Secret из диалога подтверждения. Сохраните их в надежном месте.

Часть B: настройка HandyCafe Server

13. Откройте приложение HandyCafe Server.
14. Перейдите в Настройки через значок шестеренки в боковом меню.
15. Выберите вкладку OAuth.
16. Включите переключатель OAuth вверху страницы. Это глобально активирует социальный вход на всех клиентских ПК.
17. Найдите строку провайдера Google в списке.
18. Включите переключатель Google.
19. Вставьте Client ID из шага 12 в поле Client ID.
20. Вставьте Client Secret из шага 12 в поле Client Secret.
21. Нажмите Сохранить.

Ожидаемый результат: вкладка OAuth показывает Google как включенный провайдер с заполненными учетными данными. Настройки отправляются на все подключенные клиенты.

Часть C: тестирование процесса входа

22. Перейдите к подключенному клиентскому ПК. Экран ожидания должен показывать раздел социального входа с кнопкой Google.
23. Нажмите кнопку Google на экране ожидания клиента.
24. На клиенте отображается QR-код и пользовательский код (короткая буквенно-цифровая строка).
25. Отсканируйте QR-код телефоном. Откроется страница верификации устройства Google.
26. Войдите в аккаунт Google и введите пользовательский код.
27. Авторизуйте приложение.

Ожидаемый результат: на сервере воспроизводится звук уведомления и появляется новая запись на странице Запросов. Запрос показывает имя аккаунта Google, email и клиентский ПК, инициировавший вход.

Как подтвердить запрос на вход

Каждый вход через OAuth генерирует запрос, который должен быть подтвержден до предоставления доступа.

1. При поступлении запроса на сервере воспроизводится звук уведомления и появляется бейдж на иконке страницы Запросов.
2. Перейдите на страницу Запросы.
3. Ожидающий запрос показывает:
   • Имя провайдера (например, Google).
   • Отображаемое имя от провайдера (например, «Иван Петров»).
   • Email (например, «ivan@example.com»).
   • Клиентский ПК, инициировавший запрос.
   • Временную метку.
4. Проверьте данные запроса. Убедитесь, что человек за клиентским ПК соответствует информации аккаунта.
5. Нажмите Подтвердить для принятия запроса.

Ожидаемый результат: если не существует аккаунта участника, привязанного к этому OAuth-идентификатору, новый аккаунт создается автоматически. Используются отображаемое имя и email от провайдера. Клиент авторизуется и ПК переходит с экрана ожидания на рабочий стол.

Совет: при подозрительном запросе (ПК без присмотра, запрос выглядит автоматическим) нажмите Отклонить. Клиент увидит сообщение «Доступ запрещен» и может повторить попытку.

Как настроить Facebook OAuth

1. Откройте Facebook Developer Portal по адресу https://developers.facebook.com .
2. Создайте новое приложение. Выберите тип Consumer.
3. Перейдите в Settings > Basic. Запишите App ID и App Secret.
4. Перейдите в Add Product и добавьте Facebook Login for Devices.
5. В настройках Facebook Login for Devices добавьте redirect URI при необходимости.
6. Откройте HandyCafe Server и перейдите в Настройки > OAuth.
7. Найдите строку провайдера Facebook.
8. Включите переключатель Facebook.
9. Вставьте App ID в поле Client ID.
10. Вставьте App Secret в поле Client Secret.
11. Нажмите Сохранить.

Ожидаемый результат: Facebook отображается как включенный провайдер. На экранах ожидания клиентов появляется кнопка входа через Facebook.

Как настроить Discord OAuth

1. Откройте Discord Developer Portal по адресу https://discord.com/developers/applications .
2. Создайте новое приложение. Назовите его по имени кафе.
3. Перейдите в раздел OAuth2 в боковом меню.
4. Скопируйте Client ID и сгенерируйте Client Secret. Сохраните секрет надежно, Discord показывает его только один раз.
5. Откройте HandyCafe Server и перейдите в Настройки > OAuth.
6. Найдите строку провайдера Discord (по умолчанию отключен).
7. Включите переключатель Discord.
8. Вставьте Client ID в поле Client ID.
9. Вставьте Client Secret в поле Client Secret.
10. Нажмите Сохранить.

Ожидаемый результат: Discord теперь доступен как вариант входа на экранах ожидания клиентов.

Типичные ошибки

• Неверный тип OAuth-клиента в Google Cloud Console. Необходимо выбрать «TVs and Limited Input devices» при создании OAuth client ID. Выбор «Web application» или «Desktop app» не даст работать потоку device authorization, и клиент не получит код устройства.
• Не включен главный переключатель OAuth. Включение отдельных провайдеров недостаточно. Главный переключатель OAuth вверху страницы настроек OAuth тоже должен быть включен.
• Неподтвержденные запросы на вход. Входы через OAuth требуют явного подтверждения с сервера. Если никто не следит за страницей Запросов, клиенты будут ждать бесконечно на экране ожидания. Назначьте кассира для мониторинга запросов в часы пик.
• Истечение срока кодов устройств. Коды устройств имеют ограниченный срок (обычно 5-10 минут). Если клиент медлит со сканированием QR-кода и аутентификацией, код истекает и нужно начать заново. Рекомендуйте клиентам сканировать быстро.
• Лишние пробелы в учетных данных. При копировании Client ID или Client Secret из консоли провайдера убедитесь в отсутствии начальных или конечных пробелов. Лишние пробелы вызовут ошибки аутентификации.
• Не опубликовано OAuth-приложение Google. Приложения Google в режиме «Testing» допускают только ограниченное число тестовых пользователей. Для входа любого клиента опубликуйте приложение через OAuth consent screen.
• Не настроено название кафе. Название из настроек HandyCafe отображается на клиентском экране ожидания в процессе OAuth. Пустое или стандартное название выглядит непрофессионально. Задайте название кафе в Настройки > Общие до включения OAuth.