Jak skonfigurować logowanie społecznościowe OAuth

Ten przewodnik przeprowadzi Cię przez konfigurację logowania społecznościowego, aby klienci mogli logować się na komputerach klienckich za pomocą kont Google, Facebook, Apple, X lub Discord. HandyCafe używa przepływu Device Authorization Grant (RFC 8628), który jest zaprojektowany dla urządzeń bez pełnej przeglądarki. Klienci skanują kod QR telefonem, aby się uwierzytelnić.

Co będzie potrzebne

• Dostęp administracyjny do serwera HandyCafe.
• Konto Google Cloud Console (dla Google OAuth) lub równoważny dostęp do portalu dewelopera dla innych dostawców.
• Działający i dostępny w sieci serwer HandyCafe.
• Przynajmniej jeden podłączony komputer kliencki do przetestowania procesu logowania.

Jak działa przepływ OAuth Device Flow w HandyCafe

Zanim przejdziemy do konfiguracji, oto podsumowanie przepływu:

1. Klient przy bezczynnej stacji klienckiej klika przycisk logowania społecznościowego (np. "Zaloguj się przez Google").
2. Klient wysyła żądanie rozpoczęcia OAuth do serwera.
3. Serwer kontaktuje się z punktem końcowym autoryzacji urządzenia dostawcy i otrzymuje kod urządzenia, kod użytkownika i adres URL weryfikacji.
4. Klient wyświetla kod QR i kod użytkownika na ekranie bezczynności.
5. Klient skanuje kod QR telefonem i uwierzytelnia się u dostawcy.
6. Serwer cyklicznie sprawdza u dostawcy, aż uwierzytelnienie zostanie zakończone.
7. Serwer tworzy Żądanie Logowania OAuth, które pojawia się na stronie Żądania.
8. Administrator lub kasjer zatwierdza żądanie.
9. Tworzone jest nowe konto członkowskie (lub istniejące konto jest powiązane) i klient jest logowany.

Jak skonfigurować Google OAuth

Google jest najczęściej używanym dostawcą. Ta sekcja obejmuje każdy krok od utworzenia projektu Google Cloud do przetestowania pierwszego logowania.

Część A: Utwórz dane uwierzytelniające Google Cloud

1. Otwórz Google Cloud Console pod adresem https://console.cloud.google.com w przeglądarce.
2. Utwórz nowy projekt lub wybierz istniejący. Nazwij go w sposób rozpoznawalny, np. "HandyCafe OAuth".
3. Przejdź do APIs & Services > OAuth consent screen.
4. Wybierz External jako typ użytkownika (chyba że masz organizację Google Workspace i chcesz tylko wewnętrzne).
5. Wypełnij wymagane pola: Nazwa aplikacji ("Nazwa Twojej Kawiarni"), E-mail wsparcia użytkownika i E-mail kontaktowy dewelopera.
6. Kliknij Save and Continue przez sekcje Scopes i Test Users. Nie musisz dodawać specjalnych zakresów. Domyślne zakresy email i profile są wystarczające.
7. Przejdź do APIs & Services > Credentials.
8. Kliknij Create Credentials > OAuth client ID.
9. Dla typu aplikacji wybierz TVs and Limited Input devices. To jest kluczowe. HandyCafe używa przepływu autoryzacji urządzenia, który wymaga tego konkretnego typu klienta.
10. Wprowadź nazwę dla klienta (np. "HandyCafe Device Flow").
11. Kliknij Create.
12. Skopiuj Client ID i Client Secret z okna potwierdzenia. Przechowuj je bezpiecznie. Obie wartości będą potrzebne w następnej sekcji.

Część B: Skonfiguruj serwer HandyCafe

13. Otwórz aplikację serwera HandyCafe.
14. Przejdź do Settings używając ikony koła zębatego w lewym pasku bocznym.
15. Wybierz zakładkę OAuth.
16. Włącz przełącznik OAuth na górze strony. To globalnie włącza logowanie społecznościowe na wszystkich komputerach klienckich.
17. Znajdź wiersz dostawcy Google na liście dostawców.
18. Włącz przełącznik Google, aby aktywować tego dostawcę.
19. Wklej swój Client ID z kroku 12 do pola Client ID.
20. Wklej swój Client Secret z kroku 12 do pola Client Secret.
21. Kliknij Save, aby zastosować konfigurację.

Oczekiwany rezultat: Zakładka OAuth pokazuje Google jako włączone z wypełnionymi danymi uwierzytelniającymi. Ustawienia są przesyłane do wszystkich podłączonych klientów.

Część C: Przetestuj przepływ logowania

22. Przejdź do podłączonego komputera klienckiego. Ekran bezczynności powinien teraz pokazywać sekcję logowania społecznościowego z przyciskiem logowania Google.
23. Kliknij przycisk logowania Google na ekranie bezczynności klienta.
24. Klient wyświetla kod QR i kod użytkownika (krótki ciąg alfanumeryczny).
25. Zeskanuj kod QR telefonem. Otwiera to stronę weryfikacji urządzenia Google.
26. Zaloguj się na konto Google i wprowadź kod użytkownika, gdy zostaniesz o to poproszony.
27. Autoryzuj aplikację.

Oczekiwany rezultat: Na serwerze odtwarzany jest dźwięk powiadomienia i pojawia się nowy wpis na stronie Żądania. Żądanie pokazuje nazwę konta Google, adres e-mail i komputer kliencki, który zainicjował logowanie.

Jak zatwierdzić żądanie logowania

Każde logowanie OAuth generuje żądanie, które musi zostać zatwierdzone przez administratora lub kasjera, zanim klient uzyska dostęp.

1. Gdy przychodzi żądanie logowania, na serwerze odtwarzany jest dźwięk powiadomienia, a na ikonie strony Żądania w pasku bocznym pojawia się odznaka.
2. Przejdź do strony Requests.
3. Oczekujące żądanie pokazuje:
   • Nazwę dostawcy (np. Google).
   • Nazwę wyświetlaną od dostawcy (np. "Jan Kowalski").
   • Adres e-mail (np. "jan@example.com").
   • Komputer kliencki, który zainicjował żądanie (nazwa hosta lub nazwa wyświetlana).
   • Znacznik czasu.
4. Przejrzyj szczegóły żądania. Zweryfikuj, czy osoba przy komputerze klienckim odpowiada informacjom o koncie.
5. Kliknij Approve, aby zaakceptować żądanie.

Oczekiwany rezultat: Jeśli do tej tożsamości OAuth nie jest powiązane żadne istniejące konto członkowskie, nowe konto członkowskie jest tworzone automatycznie. Używane są nazwa wyświetlana i e-mail od dostawcy. Klient jest logowany, a komputer kliencki przechodzi z ekranu bezczynności do strony Online. Jeśli konto członkowskie było wcześniej powiązane z tą tożsamością OAuth, istniejący członek jest logowany bezpośrednio.

Wskazówka: Jeśli żądanie logowania jest podejrzane (np. komputer jest bez nadzoru lub żądanie wygląda na zautomatyzowane), kliknij Reject. Klient zobaczy komunikat "Odmowa dostępu" i może spróbować ponownie.

Jak skonfigurować Facebook OAuth

1. Otwórz Facebook Developer Portal pod adresem https://developers.facebook.com .
2. Utwórz nową aplikację. Wybierz typ aplikacji Consumer.
3. Przejdź do strony Settings > Basic aplikacji. Zapisz App ID i App Secret.
4. Przejdź do Add Product i dodaj Facebook Login for Devices.
5. W ustawieniach Facebook Login for Devices dodaj swoje URI przekierowania, jeśli wymagane przez portal.
6. Otwórz serwer HandyCafe i przejdź do Settings > OAuth.
7. Znajdź wiersz dostawcy Facebook.
8. Włącz przełącznik Facebook.
9. Wklej App ID do pola Client ID.
10. Wklej App Secret do pola Client Secret.
11. Kliknij Save.

Oczekiwany rezultat: Facebook pojawia się jako włączony dostawca. Ekrany bezczynności klientów pokazują przycisk logowania Facebook obok innych włączonych dostawców.

Jak skonfigurować Discord OAuth

1. Otwórz Discord Developer Portal pod adresem https://discord.com/developers/applications .
2. Utwórz nową aplikację. Nazwij ją po swojej kawiarni.
3. Przejdź do sekcji OAuth2 w lewym pasku bocznym.
4. Skopiuj Client ID i wygeneruj Client Secret. Przechowuj tajemnicę bezpiecznie, ponieważ Discord pokazuje ją tylko raz.
5. Otwórz serwer HandyCafe i przejdź do Settings > OAuth.
6. Znajdź wiersz dostawcy Discord (jest domyślnie wyłączony).
7. Włącz przełącznik Discord.
8. Wklej Client ID do pola Client ID.
9. Wklej Client Secret do pola Client Secret.
10. Kliknij Save.

Oczekiwany rezultat: Discord jest teraz dostępny jako opcja logowania na ekranach bezczynności klientów.

Jak zezwolić na logowanie bez kredytu

Domyślnie HandyCafe pozwala klientom uwierzytelnionym przez OAuth logować się, nawet jeśli nie mają salda portfela ani kredytu czasowego. Możesz zmienić to zachowanie.

1. Przejdź do Settings > OAuth.
2. Znajdź przełącznik Allow Login Without Credit.
3. Jeśli włączony (domyślnie), klienci, którzy uwierzytelnią się przez OAuth, mogą się logować niezależnie od salda. Kasjer może rozpocząć sesję postpaid dla nich.
4. Jeśli wyłączony, klienci muszą mieć saldo portfela lub kredyt czasowy, aby się zalogować. Klienci z zerowym saldem zobaczą komunikat, aby odwiedzić kasjera i doładować konto.
5. Kliknij Save po zmianie przełącznika.

Oczekiwany rezultat: Zachowanie wchodzi w życie natychmiast dla nowych żądań logowania. Istniejące sesje nie są dotknięte.

Jak powiązać tożsamość OAuth z istniejącym członkiem

Jeśli klient ma już konto członkowskie (utworzone ręcznie przez kasjera) i następnie loguje się przez OAuth po raz pierwszy, proces zatwierdzania może powiązać tożsamość OAuth z jego istniejącym kontem.

1. Gdy żądanie logowania OAuth pojawi się na stronie Żądania, sprawdź, czy e-mail pasuje do istniejącego członka.
2. Jeśli system wykryje zgodność, okno dialogowe zatwierdzenia zaoferuje powiązanie tożsamości OAuth z istniejącym członkiem zamiast tworzenia nowego konta.
3. Zatwierdź żądanie z wybraną opcją powiązania.

Oczekiwany rezultat: Istniejące konto członkowskie zyskuje powiązanie OAuth. Przyszłe logowania od tego dostawcy będą pomijać krok zatwierdzania i logować członka bezpośrednio (po pierwszym zatwierdzeniu).

Częste błędy do unikania

• Użycie niewłaściwego typu klienta OAuth w Google Cloud Console. Musisz wybrać "TVs and Limited Input devices" podczas tworzenia identyfikatora klienta OAuth. Jeśli wybierzesz "Web application" lub "Desktop app", przepływ autoryzacji urządzenia nie zadziała i klient nie uzyska kodu urządzenia.
• Zapomnienie o włączeniu globalnego przełącznika OAuth. Włączenie poszczególnych dostawców nie wystarczy. Główny przełącznik OAuth na górze strony ustawień OAuth musi być również włączony.
• Nie zatwierdzanie żądań logowania. Logowania OAuth wymagają wyraźnego zatwierdzenia przez serwer. Jeśli nikt nie monitoruje strony Żądania, klienci będą czekać w nieskończoność na ekranie bezczynności. Rozważ przypisanie kasjera do monitorowania żądań w godzinach szczytu.
• Pozwalanie na wygaśnięcie kodów urządzeń. Kody urządzeń mają ograniczony czas życia (zwykle 5-10 minut). Jeśli klient zbyt długo czeka na zeskanowanie kodu QR i uwierzytelnienie, kod wygasa i musi zacząć od nowa. Doradź klientom, aby skanowali szybko.
• Wklejanie danych uwierzytelniających z dodatkowymi białymi znakami. Podczas kopiowania Client ID lub Client Secret z konsoli dostawcy upewnij się, że nie ma wiodących ani końcowych spacji. Dodatkowe białe znaki spowodują błędy uwierzytelniania.
• Zapomnienie o opublikowaniu aplikacji Google OAuth. Aplikacje Google w trybie "Testing" pozwalają tylko na ograniczoną liczbę użytkowników testowych. Aby umożliwić logowanie się dowolnemu klientowi, musisz opublikować aplikację przez stronę OAuth consent screen i ukończyć wszelkie wymagane kroki weryfikacji.
• Mieszanie Client ID i Client Secret. Są to dwie różne wartości. Client ID jest publiczny. Client Secret musi być poufny. Zamiana ich miejscami spowoduje błędy uwierzytelniania.
• Nie skonfigurowanie nazwy kawiarni. Nazwa kawiarni z ustawień HandyCafe jest wyświetlana na ekranie bezczynności klienta podczas przepływu OAuth. Pusta lub domyślna nazwa wygląda nieprofesjonalnie. Ustaw nazwę kawiarni w Settings > General przed włączeniem OAuth.