HandyCafe Docs
owner it-admin

Як налаштувати соціальний вхід через OAuth

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

Що вам знадобиться

  • Адміністративний доступ до HandyCafe Server.
  • Обліковий запис Google Cloud Console (для Google OAuth) або еквівалентний доступ до порталу розробника для інших провайдерів.
  • HandyCafe Server, що працює і доступний у вашій мережі.
  • Принаймні один підключений клієнтський ПК для тестування процесу входу.

Як працює 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. Перейдіть до APIs & Services > OAuth consent screen.
  4. Виберіть External як тип користувача (якщо у вас немає організації Google Workspace і ви не хочете використовувати лише внутрішній доступ).
  5. Заповніть необхідні поля: Назва додатку ("Назва вашого кафе"), Електронна пошта підтримки користувачів та Електронна пошта для зв'язку з розробником.
  6. Натисніть Save and Continue через розділи Scopes і Test Users. Вам не потрібно додавати спеціальні області. Достатньо стандартних областей електронної пошти та профілю.
  7. Перейдіть до APIs & Services > Credentials.
  8. Натисніть Create Credentials > OAuth client ID.
  9. Для типу додатку виберіть TVs and Limited Input devices. Це критично важливо. HandyCafe використовує потік авторизації пристрою, який вимагає цього конкретного типу клієнта.
  10. Введіть назву для клієнта (наприклад, "HandyCafe Device Flow").
  11. Натисніть Create.
  12. Скопіюйте Client ID та Client Secret з діалогового вікна підтвердження. Збережіть їх у безпечному місці. Вам знадобляться обидва значення в наступному розділі.

Частина B: Налаштування HandyCafe Server

  1. Відкрийте додаток HandyCafe Server.
  2. Перейдіть до Settings за допомогою значка шестерні в лівій бічній панелі.
  3. Виберіть вкладку OAuth.
  4. Увімкніть перемикач OAuth у верхній частині сторінки. Це глобально активує соціальний вхід на всіх клієнтських ПК.
  5. Знайдіть рядок провайдера Google у списку провайдерів.
  6. Увімкніть перемикач Google, щоб активувати цього провайдера.
  7. Вставте ваш Client ID з кроку 12 у поле Client ID.
  8. Вставте ваш Client Secret з кроку 12 у поле Client Secret.
  9. Натисніть Save, щоб застосувати конфігурацію.

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

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

  1. Перейдіть до підключеного клієнтського ПК. На неактивному екрані тепер має з'явитися розділ соціального входу з кнопкою входу через Google.
  2. Натисніть кнопку Google на неактивному екрані клієнта.
  3. Клієнт відображає QR-код і код користувача (короткий алфавітно-цифровий рядок).
  4. Скануйте QR-код своїм телефоном. Він відкриє сторінку перевірки пристрою Google.
  5. Увійдіть за допомогою облікового запису Google і введіть код користувача, коли буде запропоновано.
  6. Авторизуйте додаток.

Очікуваний результат: На сервері звучить звукове сповіщення і на сторінці Запитів з'являється новий запис. Запит показує ім'я облікового запису Google, електронну адресу та клієнтський ПК, який ініціював вхід.

Як схвалити запит на вхід

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

  1. Коли надходить запит на вхід, на сервері звучить звукове сповіщення і на значку сторінки Запитів у бічній панелі з'являється значок.
  2. Перейдіть на сторінку Запити.
  3. Очікуваний запит показує:
    • Назву провайдера (наприклад, Google).
    • Відображуване ім'я від провайдера (наприклад, "John Smith").
    • Електронну адресу (наприклад, "john@example.com").
    • Клієнтський ПК, який ініціював запит (ім'я хоста або відображуване ім'я).
    • Часову мітку.
  4. Перегляньте деталі запиту. Переконайтеся, що особа на клієнтському ПК відповідає інформації облікового запису.
  5. Натисніть Approve, щоб прийняти запит.

Очікуваний результат: Якщо жоден існуючий обліковий запис учасника не пов'язаний з цією ідентифікацією OAuth, автоматично створюється новий обліковий запис учасника. Використовуються відображуване ім'я та електронна адреса від провайдера. Клієнт входить у систему, і клієнтський ПК переходить з неактивного екрану на сторінку Онлайн. Якщо обліковий запис учасника вже був пов'язаний з цією ідентифікацією OAuth, існуючий учасник входить у систему безпосередньо.

Порада: Якщо запит на вхід виглядає підозріло (наприклад, ПК без нагляду або запит виглядає автоматизованим), натисніть Reject. Клієнт побачить повідомлення "Доступ заборонено" і зможе спробувати ще раз.

Як налаштувати 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 додайте ваші URI перенаправлення, якщо це вимагається порталом.
  6. Відкрийте HandyCafe Server і перейдіть до Settings > OAuth.
  7. Знайдіть рядок провайдера Facebook.
  8. Увімкніть перемикач Facebook.
  9. Вставте App ID у поле Client ID.
  10. Вставте App Secret у поле Client Secret.
  11. Натисніть Save.

Очікуваний результат: 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 і перейдіть до Settings > OAuth.
  6. Знайдіть рядок провайдера Discord (він вимкнений за замовчуванням).
  7. Увімкніть перемикач Discord.
  8. Вставте Client ID у поле Client ID.
  9. Вставте Client Secret у поле Client Secret.
  10. Натисніть Save.

Очікуваний результат: Discord тепер доступний як опція входу на неактивних екранах клієнтів.

Як дозволити вхід без кредиту

За замовчуванням HandyCafe дозволяє клієнтам, автентифікованим через OAuth, входити навіть якщо у них немає балансу на гаманці або кредиту часу. Ви можете змінити цю поведінку.

  1. Перейдіть до Settings > OAuth.
  2. Знайдіть перемикач Allow Login Without Credit.
  3. Якщо увімкнено (за замовчуванням), клієнти, які автентифікуються через OAuth, можуть входити незалежно від їхнього балансу. Касир може розпочати для них постоплатну сесію.
  4. Якщо вимкнено, клієнти повинні мати або баланс на гаманці, або кредит часу для входу. Клієнти з нульовим балансом побачать повідомлення з проханням звернутися до касира для поповнення.
  5. Натисніть Save після зміни перемикача.

Очікуваний результат: Поведінка набирає чинності негайно для нових запитів на вхід. Існуючі сесії не змінюються.

Як зв'язати ідентифікацію OAuth з існуючим учасником

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

  1. Коли запит на вхід через OAuth надходить на сторінку Запитів, перевірте, чи електронна адреса збігається з існуючим учасником.
  2. Якщо система виявляє збіг, діалогове вікно схвалення запропонує зв'язати ідентифікацію OAuth з існуючим учасником замість створення нового облікового запису.
  3. Схваліть запит з вибраним варіантом зв'язку.

Очікуваний результат: Існуючий обліковий запис учасника отримує зв'язок з OAuth. Майбутні входи від цього провайдера будуть обходити крок схвалення і безпосередньо входити в систему (після першого схвалення).

Поширені помилки, яких слід уникати

  • Використання неправильного типу клієнта OAuth у Google Cloud Console. Ви повинні вибрати "TVs and Limited Input devices" при створенні OAuth client ID. Якщо ви виберете "Web application" або "Desktop app", потік авторизації пристрою не працюватиме, і клієнт не зможе отримати код пристрою.
  • Забування увімкнути глобальний перемикач OAuth. Увімкнення окремих провайдерів недостатньо. Головний перемикач OAuth у верхній частині сторінки налаштувань OAuth також повинен бути увімкнений.
  • Не схвалення запитів на вхід. Входи через OAuth вимагають явного схвалення з боку сервера. Якщо ніхто не стежить за сторінкою Запитів, клієнти чекатимуть на неактивному екрані безкінечно. Розгляньте можливість призначення касира для моніторингу запитів під час завантажених годин.
  • Дозволяти кодам пристроїв закінчуватися. Коди пристроїв мають обмежений термін дії (зазвичай 5-10 хвилин). Якщо клієнт занадто довго сканує QR-код і автентифікується, код закінчується, і йому доведеться почати спочатку. Порадьте клієнтам сканувати швидко.
  • Вставка облікових даних з додатковими пробілами. Коли копіюєте Client ID або Client Secret з консолі провайдера, переконайтеся, що немає зайвих пробілів на початку або в кінці. Зайві пробіли спричинять помилки автентифікації.
  • Забування опублікувати додаток Google OAuth. Додатки Google в режимі "Testing" дозволяють лише обмежену кількість тестових користувачів. Щоб дозволити будь-якому клієнту входити, ви повинні опублікувати додаток через сторінку OAuth consent screen і завершити будь-які необхідні кроки перевірки.
  • Плутанина між Client ID і Client Secret. Це два різні значення. Client ID є публічним. Client Secret повинен залишатися конфіденційним. Їх підміна спричинить помилки автентифікації.
  • Не налаштування назви кафе. Назва кафе з ваших налаштувань HandyCafe відображається на неактивному екрані клієнта під час потоку OAuth. Порожня або стандартна назва виглядає непрофесійно. Встановіть назву вашого кафе в Settings > General перед увімкненням OAuth.