Come Configurare l'Accesso Social OAuth

Questa guida ti accompagna nella configurazione dell'accesso social affinche i clienti possano accedere ai PC client usando i loro account Google, Facebook, Apple, X o Discord. HandyCafe usa il flusso Device Authorization Grant (RFC 8628), progettato per dispositivi senza un browser completo. I clienti scansionano un codice QR con il loro telefono per autenticarsi.

Cosa Ti Servira

• Accesso amministratore a HandyCafe Server.
• Un account Google Cloud Console (per OAuth Google) o accesso equivalente al portale sviluppatori per altri provider.
• HandyCafe Server in esecuzione e accessibile sulla tua rete.
• Almeno un PC client connesso per testare il flusso di accesso.

Come Funziona il Flusso OAuth Device in HandyCafe

Prima di entrare nella configurazione, ecco un riepilogo del flusso:

1. Un cliente su un PC client inattivo clicca il pulsante di accesso social (ad es. "Accedi con Google").
2. Il client invia una richiesta di avvio OAuth al server.
3. Il server contatta l'endpoint di autorizzazione dispositivo del provider e riceve un codice dispositivo, un codice utente e un URL di verifica.
4. Il client mostra un codice QR e il codice utente sulla schermata di inattivita.
5. Il cliente scansiona il codice QR con il telefono e si autentica con il provider.
6. Il server interroga il provider finche l'autenticazione non e completata.
7. Il server crea una Richiesta di Accesso OAuth che appare nella pagina Richieste.
8. Un amministratore o cassiere approva la richiesta.
9. Viene creato un nuovo account membro (o viene collegato un account esistente) e il cliente e connesso.

Come Configurare OAuth Google

Google e il provider piu comunemente usato. Questa sezione copre ogni passaggio dalla creazione del progetto Google Cloud al test del primo accesso.

Parte A: Creare le Credenziali Google Cloud

1. Apri Google Cloud Console all'indirizzo https://console.cloud.google.com nel tuo browser.
2. Crea un nuovo progetto o selezionane uno esistente. Dagli un nome riconoscibile come "HandyCafe OAuth".
3. Vai su API e Servizi > Schermata di consenso OAuth.
4. Seleziona Esterno come tipo di utente (a meno che non tu abbia un'organizzazione Google Workspace e voglia solo uso interno).
5. Compila i campi obbligatori: Nome app ("Nome del Tuo Locale"), Email di supporto utente ed Email di contatto sviluppatore.
6. Clicca Salva e Continua nelle sezioni Ambiti e Utenti di Test. Non e necessario aggiungere ambiti speciali. Gli ambiti predefiniti di email e profilo sono sufficienti.
7. Vai su API e Servizi > Credenziali.
8. Clicca Crea credenziali > ID client OAuth.
9. Per il tipo di applicazione, seleziona TV e dispositivi a input limitato. Questo e fondamentale. HandyCafe usa il flusso di autorizzazione dispositivo, che richiede questo specifico tipo di client.
10. Inserisci un nome per il client (ad es. "HandyCafe Device Flow").
11. Clicca Crea.
12. Copia l'ID Client e il Segreto Client dal dialogo di conferma. Conservali in modo sicuro. Avrai bisogno di entrambi nella sezione successiva.

Parte B: Configurare il Server HandyCafe

13. Apri l'applicazione HandyCafe Server.
14. Vai su Impostazioni tramite l'icona ingranaggio nella barra laterale sinistra.
15. Seleziona la scheda OAuth.
16. Abilita l'interruttore OAuth in cima alla pagina. Questo abilita globalmente l'accesso social su tutti i PC client.
17. Individua la riga del provider Google nell'elenco dei provider.
18. Abilita l'interruttore Google per attivare questo provider.
19. Incolla il tuo ID Client del passaggio 12 nel campo ID Client.
20. Incolla il tuo Segreto Client del passaggio 12 nel campo Segreto Client.
21. Clicca Salva per applicare la configurazione.

Risultato atteso: La scheda OAuth mostra Google come abilitato con le tue credenziali inserite. Le impostazioni vengono inviate a tutti i client connessi.

Parte C: Testare il Flusso di Accesso

22. Vai a un PC client connesso. La schermata di inattivita dovrebbe ora mostrare una sezione di accesso social con un pulsante di accesso Google.
23. Clicca il pulsante di accesso Google sulla schermata di inattivita del client.
24. Il client mostra un codice QR e un codice utente (una breve stringa alfanumerica).
25. Scansiona il codice QR con il tuo telefono. Si apre la pagina di verifica dispositivo di Google.
26. Accedi con un account Google e inserisci il codice utente quando richiesto.
27. Autorizza l'applicazione.

Risultato atteso: Sul server, viene riprodotto un suono di notifica e compare una nuova voce nella pagina Richieste. La richiesta mostra il nome dell'account Google, l'indirizzo email e il PC client che ha avviato l'accesso.

Come Approvare una Richiesta di Accesso

Ogni accesso OAuth genera una richiesta che deve essere approvata da un amministratore o cassiere prima che il cliente ottenga l'accesso.

1. Quando arriva una richiesta di accesso, sul server viene riprodotto un suono di notifica e compare un badge sull'icona della pagina Richieste nella barra laterale.
2. Vai alla pagina Richieste.
3. La richiesta in sospeso mostra:
   • Nome del provider (ad es. Google).
   • Nome visualizzato dal provider (ad es. "Mario Rossi").
   • Indirizzo email (ad es. "mario@esempio.com").
   • Il PC client che ha avviato la richiesta (nome host o nome visualizzato).
   • Timestamp.
4. Esamina i dettagli della richiesta. Verifica che la persona al PC client corrisponda alle informazioni dell'account.
5. Clicca Approva per accettare la richiesta.

Risultato atteso: Se nessun account membro esistente e collegato a questa identita OAuth, viene creato automaticamente un nuovo account membro. Il nome visualizzato e l'email del provider vengono usati. Il cliente viene connesso e il PC client passa dalla schermata di inattivita alla Pagina Online. Se un account membro era precedentemente collegato a questa identita OAuth, il membro esistente viene connesso direttamente.

Suggerimento: Se la richiesta di accesso sembra sospetta (ad es. il PC e incustodito o la richiesta sembra automatizzata), clicca invece Rifiuta. Il cliente vedra un messaggio di "Accesso negato" e potra riprovare.

Come Configurare OAuth Facebook

1. Apri il Portale Sviluppatori Facebook all'indirizzo https://developers.facebook.com .
2. Crea una nuova app. Seleziona il tipo di app Consumer.
3. Vai alla pagina Impostazioni > Base dell'app. Annota l'ID App e il Segreto App.
4. Vai su Aggiungi Prodotto e aggiungi Facebook Login per Dispositivi.
5. Nelle impostazioni di Facebook Login per Dispositivi, aggiungi gli URI di reindirizzamento se richiesti dal portale.
6. Apri HandyCafe Server e vai su Impostazioni > OAuth.
7. Individua la riga del provider Facebook.
8. Abilita l'interruttore Facebook.
9. Incolla l'ID App nel campo ID Client.
10. Incolla il Segreto App nel campo Segreto Client.
11. Clicca Salva.

Risultato atteso: Facebook appare come provider abilitato. Le schermate di inattivita dei client mostrano un pulsante di accesso Facebook insieme agli altri provider abilitati.

Come Configurare OAuth Discord

1. Apri il Portale Sviluppatori Discord all'indirizzo https://discord.com/developers/applications .
2. Crea una nuova applicazione. Dagli il nome del tuo locale.
3. Vai alla sezione OAuth2 nella barra laterale sinistra.
4. Copia l'ID Client e genera un Segreto Client. Conserva il segreto in modo sicuro poiche Discord lo mostra una sola volta.
5. Apri HandyCafe Server e vai su Impostazioni > OAuth.
6. Individua la riga del provider Discord (e disabilitata per impostazione predefinita).
7. Abilita l'interruttore Discord.
8. Incolla l'ID Client nel campo ID Client.
9. Incolla il Segreto Client nel campo Segreto Client.
10. Clicca Salva.

Risultato atteso: Discord e ora disponibile come opzione di accesso sulle schermate di inattivita dei client.

Come Consentire l'Accesso Senza Credito

Per impostazione predefinita, HandyCafe consente ai clienti autenticati tramite OAuth di accedere anche se non hanno saldo portafoglio o credito tempo. Puoi cambiare questo comportamento.

1. Vai su Impostazioni > OAuth.
2. Individua l'interruttore Consenti Accesso Senza Credito.
3. Se abilitato (impostazione predefinita), i clienti che si autenticano tramite OAuth possono accedere indipendentemente dal loro saldo. Un cassiere puo avviare una sessione postpagata per loro.
4. Se disabilitato, i clienti devono avere un saldo portafoglio o un credito tempo per accedere. I clienti con saldo zero vedranno un messaggio che li invita a recarsi dal cassiere per ricaricare.
5. Clicca Salva dopo aver cambiato l'interruttore.

Risultato atteso: Il comportamento entra in vigore immediatamente per le nuove richieste di accesso. Le sessioni esistenti non vengono influenzate.

Come Collegare un'Identita OAuth a un Membro Esistente

Se un cliente ha gia un account membro (creato manualmente da un cassiere) e poi accede tramite OAuth per la prima volta, il processo di approvazione puo collegare l'identita OAuth al suo account esistente.

1. Quando la richiesta di accesso OAuth arriva nella pagina Richieste, verifica se l'email corrisponde a un membro esistente.
2. Se il sistema rileva una corrispondenza, il dialogo di approvazione proporra di collegare l'identita OAuth al membro esistente invece di creare un nuovo account.
3. Approva la richiesta con l'opzione di collegamento selezionata.

Risultato atteso: L'account membro esistente ottiene un collegamento OAuth. I futuri accessi da questo provider salteranno il passaggio di approvazione e connetteranno direttamente il membro (dopo la prima approvazione).

Errori Comuni da Evitare

• Usare il tipo di client OAuth sbagliato in Google Cloud Console. Devi selezionare "TV e dispositivi a input limitato" quando crei l'ID client OAuth. Se selezioni "Applicazione web" o "App desktop", il flusso di autorizzazione dispositivo non funzionera e il client non riuscira a ottenere un codice dispositivo.
• Dimenticare di abilitare l'interruttore OAuth globale. Abilitare i singoli provider non e sufficiente. Anche l'interruttore OAuth principale in cima alla pagina delle impostazioni OAuth deve essere attivo.
• Non approvare le richieste di accesso. Gli accessi OAuth richiedono l'approvazione esplicita dal server. Se nessuno monitora la pagina Richieste, i clienti aspetteranno a tempo indeterminato sulla schermata di inattivita. Considera di assegnare un cassiere al monitoraggio delle richieste durante le ore di punta.
• Lasciare scadere i codici dispositivo. I codici dispositivo hanno una durata limitata (in genere 5-10 minuti). Se il cliente impiega troppo tempo a scansionare il codice QR e autenticarsi, il codice scade e deve ricominciare. Informa i clienti di scansionare prontamente.
• Incollare le credenziali con spazi extra. Quando copi l'ID Client o il Segreto Client dalla console del provider, assicurati che non ci siano spazi iniziali o finali. Gli spazi extra causano errori di autenticazione.
• Dimenticare di pubblicare l'app Google OAuth. Le app Google in modalita "Test" consentono solo un numero limitato di utenti di test. Per consentire a qualsiasi cliente di accedere, devi pubblicare l'app tramite la pagina della schermata di consenso OAuth e completare eventuali passaggi di verifica richiesti.
• Confondere l'ID Client con il Segreto Client. Sono due valori diversi. L'ID Client e pubblico. Il Segreto Client deve essere tenuto riservato. Scambiarli causa errori di autenticazione.
• Non configurare il nome del locale. Il nome del locale dalle impostazioni di HandyCafe viene visualizzato sulla schermata di inattivita del client durante il flusso OAuth. Un nome vuoto o predefinito appare poco professionale. Imposta il nome del tuo locale in Impostazioni > Generale prima di abilitare OAuth.