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

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

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

• Административный доступ к серверу HandyCafe.
• Учетная запись Google Cloud Console (для Google OAuth) или эквивалентный доступ к порталу разработчиков для других провайдеров.
• Сервер HandyCafe, работающий и доступный в вашей сети.
• По крайней мере один подключенный клиентский ПК для тестирования процесса входа.

Как работает поток OAuth Device Flow в 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. Перейдите в API и сервисы > Экран согласия OAuth.
4. Выберите Внешний как тип пользователя (если у вас нет организации Google Workspace и вы не хотите использовать только внутренний).
5. Заполните обязательные поля: Название приложения ("Название вашего кафе"), Электронная почта поддержки пользователей и Электронная почта для связи с разработчиком.
6. Нажмите Сохранить и продолжить в разделах Области и Тестовые пользователи. Вам не нужно добавлять специальные области. Достаточно стандартных областей email и profile.
7. Перейдите в API и сервисы > Учетные данные.
8. Нажмите Создать учетные данные > Идентификатор клиента OAuth.
9. Для типа приложения выберите Телевизоры и устройства с ограниченным вводом. Это критично. HandyCafe использует поток авторизации устройства, который требует именно этот тип клиента.
10. Введите название для клиента (например, "HandyCafe Device Flow").
11. Нажмите Создать.
12. Скопируйте Идентификатор клиента и Секрет клиента из диалогового окна подтверждения. Храните их в безопасности. Вам понадобятся оба значения в следующем разделе.

Часть B: Настройка сервера HandyCafe

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

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

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

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

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

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

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

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

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

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

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

1. Откройте портал разработчиков Facebook по адресу https://developers.facebook.com .
2. Создайте новое приложение. Выберите тип приложения Потребитель.
3. Перейдите на страницу Настройки > Основные приложения. Обратите внимание на ID приложения и Секрет приложения.
4. Перейдите в Добавить продукт и добавьте Facebook Login для устройств.
5. В настройках Facebook Login для устройств добавьте ваши URI перенаправления, если это требуется порталом.
6. Откройте сервер HandyCafe и перейдите в Настройки > OAuth.
7. Найдите строку провайдера Facebook.
8. Включите переключатель Facebook.
9. Вставьте ID приложения в поле Идентификатор клиента.
10. Вставьте Секрет приложения в поле Секрет клиента.
11. Нажмите Сохранить.

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

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

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

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

Как разрешить вход без кредита

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

1. Перейдите в Настройки > OAuth.
2. Найдите переключатель Разрешить вход без кредита.
3. Если включено (по умолчанию), клиенты, аутентифицированные через OAuth, могут входить в систему независимо от их баланса. Кассир может начать для них сессию с оплатой после использования.
4. Если отключено, клиенты должны иметь либо баланс на кошельке, либо время, чтобы войти в систему. Клиенты с нулевым балансом увидят сообщение с просьбой обратиться к кассиру для пополнения.
5. Нажмите Сохранить после изменения переключателя.

Ожидаемый результат: Поведение вступает в силу немедленно для новых запросов на вход. Существующие сессии не затрагиваются.

Как связать идентичность OAuth с существующим участником

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

1. Когда запрос на вход через OAuth поступает на страницу Запросов, проверьте, совпадает ли электронная почта с существующим участником.
2. Если система обнаруживает совпадение, диалог одобрения предложит связать идентичность OAuth с существующим участником вместо создания новой учетной записи.
3. Одобрите запрос с выбранной опцией связывания.

Ожидаемый результат: Существующая учетная запись участника получает ссылку на OAuth. Будущие входы от этого провайдера будут обходить шаг одобрения и напрямую входить в систему (после первого одобрения).

Общие ошибки, которых следует избегать

• Использование неправильного типа клиента OAuth в Google Cloud Console. Вы должны выбрать "Телевизоры и устройства с ограниченным вводом" при создании идентификатора клиента OAuth. Если вы выберете "Веб-приложение" или "Настольное приложение", поток авторизации устройства не будет работать, и клиент не сможет получить код устройства.
• Забывание включить глобальный переключатель OAuth. Включение отдельных провайдеров недостаточно. Главный переключатель OAuth в верхней части страницы настроек OAuth также должен быть включен.
• Неодобрение запросов на вход. Входы через OAuth требуют явного одобрения с сервера. Если никто не следит за страницей Запросов, клиенты будут бесконечно ждать на неактивном экране. Рассмотрите возможность назначения кассира для мониторинга запросов в часы пик.
• Истечение срока действия кодов устройства. Коды устройства имеют ограниченный срок действия (обычно 5-10 минут). Если клиент слишком долго сканирует QR-код и аутентифицируется, код истекает, и ему нужно начинать заново. Советуй клиентам сканировать быстро.
• Вставка учетных данных с лишними пробелами. При копировании идентификатора клиента или секрета клиента из консоли провайдера убедитесь, что нет начальных или конечных пробелов. Лишние пробелы приведут к сбоям аутентификации.
• Забывание опубликовать приложение Google OAuth. Приложения Google в режиме "Тестирование" позволяют только ограниченное количество тестовых пользователей. Чтобы любой клиент мог войти, вы должны опубликовать приложение через страницу экрана согласия OAuth и завершить все необходимые шаги проверки.
• Путаница между идентификатором клиента и секретом клиента. Это два разных значения. Идентификатор клиента является общедоступным. Секрет клиента должен оставаться конфиденциальным. Их путаница приведет к сбоям аутентификации.
• Не настройка названия кафе. Название кафе из ваших настроек HandyCafe отображается на неактивном экране клиента во время потока OAuth. Пустое или стандартное название выглядит непрофессионально. Установите название вашего кафе в Настройки > Общие перед включением OAuth.