So richten Sie die OAuth-Social-Login-Funktion ein

Diese Anleitung führt Sie durch die Konfiguration der Social-Login-Funktion, damit sich Kunden mit ihren Google-, Facebook-, Apple-, X- oder Discord-Konten an Client-PCs anmelden können. HandyCafe verwendet den Device Authorization Grant Flow (RFC 8628), der für Geräte ohne vollständigen Browser konzipiert ist. Kunden scannen einen QR-Code mit ihrem Telefon zur Authentifizierung.

Was Sie benötigen

• Administratorzugang zum HandyCafe-Server.
• Ein Google Cloud Console-Konto (für Google OAuth) oder entsprechenden Zugang zum Entwicklerportal anderer Anbieter.
• Den laufenden und im Netzwerk erreichbaren HandyCafe-Server.
• Mindestens einen verbundenen Client-PC zum Testen des Anmeldevorgangs.

So funktioniert der OAuth-Device-Flow in HandyCafe

Bevor Sie mit der Einrichtung beginnen, eine Zusammenfassung des Ablaufs:

1. Ein Kunde an einem bereitstehenden Client-PC klickt auf die Social-Login-Schaltfläche (z. B. "Mit Google anmelden").
2. Der Client sendet eine OAuth-Startanfrage an den Server.
3. Der Server kontaktiert den Device-Authorization-Endpunkt des Anbieters und erhält einen Gerätecode, einen Benutzercode und eine Verifizierungs-URL.
4. Der Client zeigt einen QR-Code und den Benutzercode auf dem Sperrbildschirm an.
5. Der Kunde scannt den QR-Code mit seinem Telefon und authentifiziert sich beim Anbieter.
6. Der Server fragt den Anbieter ab, bis die Authentifizierung abgeschlossen ist.
7. Der Server erstellt eine OAuth-Anmeldeanfrage, die auf der Anfragenseite erscheint.
8. Ein Administrator oder Kassierer genehmigt die Anfrage.
9. Ein neues Mitgliedskonto wird erstellt (oder ein bestehendes verknüpft) und der Kunde wird angemeldet.

So richten Sie Google OAuth ein

Google ist der am häufigsten verwendete Anbieter. Dieser Abschnitt behandelt jeden Schritt von der Erstellung des Google-Cloud-Projekts bis zum Test der ersten Anmeldung.

Teil A: Google-Cloud-Zugangsdaten erstellen

1. Öffnen Sie die Google Cloud Console unter https://console.cloud.google.com in Ihrem Browser.
2. Erstellen Sie ein neues Projekt oder wählen Sie ein bestehendes aus. Benennen Sie es erkennbar, z. B. "HandyCafe OAuth".
3. Navigieren Sie zu APIs & Dienste > OAuth-Zustimmungsbildschirm.
4. Wählen Sie Extern als Benutzertyp (es sei denn, Sie haben eine Google-Workspace-Organisation und möchten nur interne Nutzer).
5. Füllen Sie die Pflichtfelder aus: App-Name ("Ihr Cafe-Name"), Support-E-Mail und Kontakt-E-Mail des Entwicklers.
6. Klicken Sie bei den Abschnitten Bereiche und Testnutzer jeweils auf Speichern und fortfahren. Sie müssen keine speziellen Bereiche hinzufügen. Die Standard-Bereiche E-Mail und Profil genügen.
7. Navigieren Sie zu APIs & Dienste > Anmeldedaten.
8. Klicken Sie auf Anmeldedaten erstellen > OAuth-Client-ID.
9. Wählen Sie als Anwendungstyp Fernseher und eingeschränkte Eingabegeräte. Dies ist entscheidend. HandyCafe verwendet den Device Authorization Grant Flow, der diesen spezifischen Client-Typ erfordert.
10. Geben Sie einen Namen für den Client ein (z. B. "HandyCafe Device Flow").
11. Klicken Sie auf Erstellen.
12. Kopieren Sie die Client-ID und den Client-Secret aus dem Bestätigungsdialog. Bewahren Sie diese sicher auf. Sie benötigen beide Werte im nächsten Abschnitt.

Teil B: HandyCafe-Server konfigurieren

13. Öffnen Sie die HandyCafe-Server-Anwendung.
14. Navigieren Sie über das Zahnradsymbol in der linken Seitenleiste zu Einstellungen.
15. Wählen Sie den Tab OAuth.
16. Aktivieren Sie den OAuth-Schalter oben auf der Seite. Dies aktiviert die Social-Login-Funktion global auf allen Client-PCs.
17. Suchen Sie die Google-Anbieterzeile in der Anbieterliste.
18. Aktivieren Sie den Google-Schalter, um diesen Anbieter zu aktivieren.
19. Fügen Sie Ihre Client-ID aus Schritt 12 in das Feld Client-ID ein.
20. Fügen Sie Ihren Client-Secret aus Schritt 12 in das Feld Client-Secret ein.
21. Klicken Sie auf Speichern, um die Konfiguration zu übernehmen.

Erwartetes Ergebnis: Der OAuth-Tab zeigt Google als aktiviert mit Ihren eingetragenen Zugangsdaten. Die Einstellungen werden an alle verbundenen Clients übertragen.

Teil C: Anmeldevorgang testen

22. Gehen Sie zu einem verbundenen Client-PC. Der Sperrbildschirm sollte nun einen Social-Login-Bereich mit einer Google-Anmeldeschaltfläche anzeigen.
23. Klicken Sie auf dem Client-Sperrbildschirm auf die Google-Anmeldeschaltfläche.
24. Der Client zeigt einen QR-Code und einen Benutzercode (eine kurze alphanumerische Zeichenkette) an.
25. Scannen Sie den QR-Code mit Ihrem Telefon. Es öffnet sich Googles Geräteverifizierungsseite.
26. Melden Sie sich mit einem Google-Konto an und geben Sie den Benutzercode ein, wenn Sie dazu aufgefordert werden.
27. Autorisieren Sie die Anwendung.

Erwartetes Ergebnis: Auf dem Server ertönt ein Benachrichtigungston und ein neuer Eintrag erscheint auf der Anfragenseite. Die Anfrage zeigt den Google-Kontonamen, die E-Mail-Adresse und den Client-PC, der die Anmeldung initiiert hat.

So genehmigen Sie eine Anmeldeanfrage

Jede OAuth-Anmeldung erzeugt eine Anfrage, die von einem Administrator oder Kassierer genehmigt werden muss, bevor der Kunde Zugang erhält.

1. Wenn eine Anmeldeanfrage eingeht, ertönt ein Benachrichtigungston auf dem Server und ein Badge erscheint am Anfragenseiten-Symbol in der Seitenleiste.
2. Navigieren Sie zur Anfragen-Seite.
3. Die ausstehende Anfrage zeigt:
   • Anbietername (z. B. Google).
   • Anzeigename vom Anbieter (z. B. "Max Mustermann").
   • E-Mail-Adresse (z. B. "max@beispiel.de").
   • Den Client-PC, der die Anfrage initiiert hat (Hostname oder Anzeigename).
   • Zeitstempel.
4. Überprüfen Sie die Anfragedetails. Stellen Sie sicher, dass die Person am Client-PC mit den Kontoinformationen übereinstimmt.
5. Klicken Sie auf Genehmigen, um die Anfrage zu akzeptieren.

Erwartetes Ergebnis: Falls kein bestehendes Mitgliedskonto mit dieser OAuth-Identität verknüpft ist, wird automatisch ein neues erstellt. Der Anzeigename und die E-Mail-Adresse vom Anbieter werden verwendet. Der Kunde wird angemeldet und der Client-PC wechselt vom Sperrbildschirm zur Online-Seite. Falls bereits ein Mitgliedskonto mit dieser OAuth-Identität verknüpft war, wird das bestehende Mitglied direkt angemeldet.

Tipp: Falls die Anmeldeanfrage verdächtig erscheint (z. B. der PC ist unbeaufsichtigt oder die Anfrage wirkt automatisiert), klicken Sie stattdessen auf Ablehnen. Der Kunde sieht eine Meldung "Zugang verweigert" und kann es erneut versuchen.

So richten Sie Facebook OAuth ein

1. Öffnen Sie das Facebook-Entwicklerportal unter https://developers.facebook.com .
2. Erstellen Sie eine neue App. Wählen Sie den App-Typ Consumer.
3. Navigieren Sie zur Seite Einstellungen > Allgemein der App. Notieren Sie die App-ID und das App-Secret.
4. Navigieren Sie zu Produkt hinzufügen und fügen Sie Facebook Login for Devices hinzu.
5. Fügen Sie in den Einstellungen von Facebook Login for Devices Ihre Weiterleitungs-URIs hinzu, falls vom Portal gefordert.
6. Öffnen Sie den HandyCafe-Server und navigieren Sie zu Einstellungen > OAuth.
7. Suchen Sie die Facebook-Anbieterzeile.
8. Aktivieren Sie den Facebook-Schalter.
9. Fügen Sie die App-ID in das Feld Client-ID ein.
10. Fügen Sie das App-Secret in das Feld Client-Secret ein.
11. Klicken Sie auf Speichern.

Erwartetes Ergebnis: Facebook erscheint als aktivierter Anbieter. Client-Sperrbildschirme zeigen neben anderen aktivierten Anbietern eine Facebook-Anmeldeschaltfläche.

So richten Sie Discord OAuth ein

1. Öffnen Sie das Discord-Entwicklerportal unter https://discord.com/developers/applications .
2. Erstellen Sie eine neue Anwendung. Benennen Sie sie nach Ihrem Cafe.
3. Navigieren Sie zum Abschnitt OAuth2 in der linken Seitenleiste.
4. Kopieren Sie die Client-ID und generieren Sie einen Client-Secret. Bewahren Sie das Secret sicher auf, da Discord es nur einmal anzeigt.
5. Öffnen Sie den HandyCafe-Server und navigieren Sie zu Einstellungen > OAuth.
6. Suchen Sie die Discord-Anbieterzeile (standardmäßig deaktiviert).
7. Aktivieren Sie den Discord-Schalter.
8. Fügen Sie die Client-ID in das Feld Client-ID ein.
9. Fügen Sie den Client-Secret in das Feld Client-Secret ein.
10. Klicken Sie auf Speichern.

Erwartetes Ergebnis: Discord steht nun als Anmeldeoption auf Client-Sperrbildschirmen zur Verfügung.

So erlauben Sie die Anmeldung ohne Guthaben

Standardmäßig erlaubt HandyCafe OAuth-authentifizierten Kunden die Anmeldung auch ohne Guthaben oder Zeitguthaben. Sie können dieses Verhalten ändern.

1. Navigieren Sie zu Einstellungen > OAuth.
2. Suchen Sie den Schalter Anmeldung ohne Guthaben erlauben.
3. Falls aktiviert (Standard), können sich Kunden, die sich über OAuth authentifizieren, unabhängig von ihrem Kontostand anmelden. Ein Kassierer kann eine Postpaid-Sitzung für sie starten.
4. Falls deaktiviert, müssen Kunden entweder Geld- oder Zeitguthaben besitzen, um sich anzumelden. Kunden mit einem Kontostand von null sehen eine Meldung, die sie auffordert, den Kassierer zum Aufladen aufzusuchen.
5. Klicken Sie nach Änderung des Schalters auf Speichern.

Erwartetes Ergebnis: Das Verhalten tritt sofort für neue Anmeldeanfragen in Kraft. Bestehende Sitzungen sind nicht betroffen.

So verknüpfen Sie eine OAuth-Identität mit einem bestehenden Mitglied

Falls ein Kunde bereits ein Mitgliedskonto hat (manuell vom Kassierer erstellt) und sich dann erstmals über OAuth anmeldet, kann der Genehmigungsprozess die OAuth-Identität mit dem bestehenden Konto verknüpfen.

1. Wenn die OAuth-Anmeldeanfrage auf der Anfragenseite eingeht, prüfen Sie, ob die E-Mail-Adresse mit einem bestehenden Mitglied übereinstimmt.
2. Falls das System eine Übereinstimmung erkennt, bietet der Genehmigungsdialog an, die OAuth-Identität mit dem bestehenden Mitglied zu verknüpfen, anstatt ein neues Konto zu erstellen.
3. Genehmigen Sie die Anfrage mit ausgewählter Verknüpfungsoption.

Erwartetes Ergebnis: Das bestehende Mitgliedskonto erhält eine OAuth-Verknüpfung. Zukünftige Anmeldungen über diesen Anbieter umgehen den Genehmigungsschritt und melden das Mitglied direkt an (nach der ersten Genehmigung).

Häufige Fehler, die Sie vermeiden sollten

• Falschen OAuth-Client-Typ in der Google Cloud Console verwenden. Sie müssen beim Erstellen der OAuth-Client-ID "Fernseher und eingeschränkte Eingabegeräte" auswählen. Falls Sie "Webanwendung" oder "Desktop-App" wählen, funktioniert der Device Authorization Flow nicht und der Client kann keinen Gerätecode abrufen.
• Globalen OAuth-Schalter nicht aktivieren. Einzelne Anbieter zu aktivieren genügt nicht. Der Haupt-OAuth-Schalter oben auf der OAuth-Einstellungsseite muss ebenfalls eingeschaltet sein.
• Anmeldeanfragen nicht genehmigen. OAuth-Anmeldungen erfordern eine ausdrückliche Genehmigung vom Server. Falls niemand die Anfragenseite überwacht, warten Kunden endlos am Sperrbildschirm. Weisen Sie in Stoßzeiten einen Kassierer zur Überwachung der Anfragen zu.
• Gerätecodes ablaufen lassen. Gerätecodes haben eine begrenzte Gültigkeitsdauer (typischerweise 5-10 Minuten). Falls der Kunde zu lange braucht, um den QR-Code zu scannen und sich zu authentifizieren, verfällt der Code und der Vorgang muss neu gestartet werden. Weisen Sie Kunden darauf hin, zügig zu scannen.
• Zugangsdaten mit zusätzlichen Leerzeichen einfügen. Stellen Sie beim Kopieren der Client-ID oder des Client-Secret aus dem Anbieterportal sicher, dass keine führenden oder abschließenden Leerzeichen enthalten sind. Zusätzliche Leerzeichen verursachen Authentifizierungsfehler.
• Google-OAuth-App nicht veröffentlichen. Google-Apps im Modus "Testen" erlauben nur eine begrenzte Anzahl von Testnutzern. Damit sich jeder Kunde anmelden kann, müssen Sie die App über die OAuth-Zustimmungsbildschirm-Seite veröffentlichen und alle erforderlichen Verifizierungsschritte abschließen.
• Client-ID und Client-Secret verwechseln. Dies sind zwei verschiedene Werte. Die Client-ID ist öffentlich. Der Client-Secret muss vertraulich bleiben. Das Vertauschen verursacht Authentifizierungsfehler.
• Cafe-Namen nicht konfigurieren. Der Cafe-Name aus Ihren HandyCafe-Einstellungen wird während des OAuth-Vorgangs auf dem Client-Sperrbildschirm angezeigt. Ein leerer oder Standardname wirkt unprofessionell. Legen Sie Ihren Cafe-Namen unter Einstellungen > Allgemein fest, bevor Sie OAuth aktivieren.