Como configurar el inicio de sesion social con OAuth

Esta guia te lleva paso a paso por la configuracion del inicio de sesion social para que los clientes puedan acceder a los PCs cliente usando sus cuentas de Google, Facebook, Apple, X o Discord. HandyCafe usa el flujo de Autorizacion de Dispositivo (RFC 8628), disenado para dispositivos sin navegador completo. Los clientes escanean un codigo QR con su telefono para autenticarse.

Lo que necesitaras

• Acceso de administrador al servidor HandyCafe.
• Una cuenta en la Consola de Google Cloud (para OAuth de Google) o acceso equivalente al portal de desarrolladores de otros proveedores.
• El servidor HandyCafe funcionando y accesible en tu red.
• Al menos un PC cliente conectado para probar el flujo de inicio de sesion.

Como funciona el flujo de dispositivo OAuth en HandyCafe

Antes de comenzar la configuracion, aqui tienes un resumen del flujo:

1. Un cliente en un PC inactivo hace clic en el boton de inicio de sesion social (ej. "Iniciar sesion con Google").
2. El cliente envia una solicitud de inicio OAuth al servidor.
3. El servidor contacta al endpoint de autorizacion de dispositivo del proveedor y recibe un codigo de dispositivo, un codigo de usuario y una URL de verificacion.
4. El cliente muestra un codigo QR y el codigo de usuario en la pantalla de espera.
5. El cliente escanea el codigo QR con su telefono y se autentica con el proveedor.
6. El servidor consulta al proveedor hasta que la autenticacion se completa.
7. El servidor crea una Solicitud de Inicio de Sesion OAuth que aparece en la pagina de Solicitudes.
8. Un administrador o cajero aprueba la solicitud.
9. Se crea una nueva cuenta de miembro (o se vincula una cuenta existente) y el cliente inicia sesion.

Como configurar OAuth de Google

Google es el proveedor mas utilizado. Esta seccion cubre cada paso desde la creacion del proyecto en Google Cloud hasta la prueba del primer inicio de sesion.

Parte A: Crear credenciales en Google Cloud

1. Abre la Consola de Google Cloud en https://console.cloud.google.com en tu navegador.
2. Crea un nuevo proyecto o selecciona uno existente. Nombralo algo reconocible como "HandyCafe OAuth".
3. Navega a APIs y Servicios > Pantalla de consentimiento OAuth.
4. Selecciona Externo como tipo de usuario (a menos que tengas una organizacion de Google Workspace y quieras solo uso interno).
5. Completa los campos requeridos: Nombre de la aplicacion ("Nombre de tu Cafe"), Correo de soporte al usuario y Correo de contacto del desarrollador.
6. Haz clic en Guardar y Continuar a traves de las secciones de Alcances y Usuarios de prueba. No necesitas agregar alcances especiales. Los alcances predeterminados de correo y perfil son suficientes.
7. Navega a APIs y Servicios > Credenciales.
8. Haz clic en Crear Credenciales > ID de cliente OAuth.
9. Para el tipo de aplicacion, selecciona TVs y dispositivos de entrada limitada. Esto es critico. HandyCafe usa el flujo de autorizacion de dispositivo, que requiere este tipo de cliente especifico.
10. Ingresa un nombre para el cliente (ej. "HandyCafe Flujo de Dispositivo").
11. Haz clic en Crear.
12. Copia el ID de Cliente y el Secreto de Cliente del dialogo de confirmacion. Guardalos de forma segura. Necesitaras ambos valores en la siguiente seccion.

Parte B: Configurar el servidor HandyCafe

13. Abre la aplicacion del servidor HandyCafe.
14. Navega a Ajustes usando el icono de engranaje en la barra lateral izquierda.
15. Selecciona la pestana OAuth.
16. Activa el interruptor de OAuth en la parte superior de la pagina. Esto habilita globalmente el inicio de sesion social en todos los PCs cliente.
17. Localiza la fila del proveedor Google en la lista de proveedores.
18. Activa el interruptor de Google para activar este proveedor.
19. Pega tu ID de Cliente del paso 12 en el campo ID de Cliente.
20. Pega tu Secreto de Cliente del paso 12 en el campo Secreto de Cliente.
21. Haz clic en Guardar para aplicar la configuracion.

Resultado esperado: La pestana OAuth muestra Google como habilitado con tus credenciales completadas. Los ajustes se envian a todos los clientes conectados.

Parte C: Probar el flujo de inicio de sesion

22. Ve a un PC cliente conectado. La pantalla de espera ahora deberia mostrar una seccion de inicio de sesion social con un boton de Google.
23. Haz clic en el boton de Google en la pantalla de espera del cliente.
24. El cliente muestra un codigo QR y un codigo de usuario (una cadena alfanumerica corta).
25. Escanea el codigo QR con tu telefono. Se abre la pagina de verificacion de dispositivo de Google.
26. Inicia sesion con una cuenta de Google e ingresa el codigo de usuario cuando se te solicite.
27. Autoriza la aplicacion.

Resultado esperado: En el servidor, suena una notificacion y aparece una nueva entrada en la pagina de Solicitudes. La solicitud muestra el nombre de la cuenta de Google, la direccion de correo y el PC cliente que inicio el proceso de sesion.

Como aprobar una solicitud de inicio de sesion

Cada inicio de sesion OAuth genera una solicitud que debe ser aprobada por un administrador o cajero antes de que el cliente obtenga acceso.

1. Cuando llega una solicitud de inicio de sesion, suena una notificacion en el servidor y aparece una insignia en el icono de la pagina de Solicitudes en la barra lateral.
2. Navega a la pagina de Solicitudes.
3. La solicitud pendiente muestra:
   • Nombre del proveedor (ej. Google).
   • Nombre de visualizacion del proveedor (ej. "Juan Garcia").
   • Direccion de correo (ej. "juan@example.com").
   • El PC cliente que inicio la solicitud (nombre de equipo o nombre de visualizacion).
   • Marca de tiempo.
4. Revisa los detalles de la solicitud. Verifica que la persona en el PC cliente coincida con la informacion de la cuenta.
5. Haz clic en Aprobar para aceptar la solicitud.

Resultado esperado: Si no existe una cuenta de miembro vinculada a esta identidad OAuth, se crea automaticamente una nueva cuenta de miembro. Se usan el nombre de visualizacion y correo del proveedor. El cliente inicia sesion y el PC cliente pasa de la pantalla de espera a la pagina en linea. Si una cuenta de miembro fue vinculada previamente a esta identidad OAuth, el miembro existente inicia sesion directamente.

Consejo: Si la solicitud de inicio de sesion es sospechosa (ej. el PC esta desatendido o la solicitud parece automatizada), haz clic en Rechazar en su lugar. El cliente vera un mensaje de "Acceso denegado" y podra intentar de nuevo.

Como configurar OAuth de Facebook

1. Abre el Portal de Desarrolladores de Facebook en https://developers.facebook.com .
2. Crea una nueva aplicacion. Selecciona el tipo de aplicacion Consumidor.
3. Navega a la pagina Configuracion > Basico de la aplicacion. Anota el ID de Aplicacion y el Secreto de Aplicacion.
4. Navega a Agregar Producto y agrega Facebook Login para Dispositivos.
5. En la configuracion de Facebook Login para Dispositivos, agrega tus URIs de redireccion si el portal lo requiere.
6. Abre el servidor HandyCafe y navega a Ajustes > OAuth.
7. Localiza la fila del proveedor Facebook.
8. Activa el interruptor de Facebook.
9. Pega el ID de Aplicacion en el campo ID de Cliente.
10. Pega el Secreto de Aplicacion en el campo Secreto de Cliente.
11. Haz clic en Guardar.

Resultado esperado: Facebook aparece como proveedor habilitado. Las pantallas de espera del cliente muestran un boton de inicio de sesion de Facebook junto a cualquier otro proveedor habilitado.

Como configurar OAuth de Discord

1. Abre el Portal de Desarrolladores de Discord en https://discord.com/developers/applications .
2. Crea una nueva aplicacion. Nombra la aplicacion con el nombre de tu cafe.
3. Navega a la seccion OAuth2 en la barra lateral izquierda.
4. Copia el ID de Cliente y genera un Secreto de Cliente. Guarda el secreto de forma segura ya que Discord solo lo muestra una vez.
5. Abre el servidor HandyCafe y navega a Ajustes > OAuth.
6. Localiza la fila del proveedor Discord (esta deshabilitado por defecto).
7. Activa el interruptor de Discord.
8. Pega el ID de Cliente en el campo ID de Cliente.
9. Pega el Secreto de Cliente en el campo Secreto de Cliente.
10. Haz clic en Guardar.

Resultado esperado: Discord esta ahora disponible como opcion de inicio de sesion en las pantallas de espera del cliente.

Como permitir el inicio de sesion sin credito

Por defecto, HandyCafe permite que los clientes autenticados por OAuth inicien sesion aunque no tengan saldo de billetera ni credito de tiempo. Puedes cambiar este comportamiento.

1. Navega a Ajustes > OAuth.
2. Localiza el interruptor Permitir inicio de sesion sin credito.
3. Si esta habilitado (predeterminado), los clientes que se autentiquen via OAuth pueden iniciar sesion sin importar su saldo. Un cajero puede iniciar una sesion de pago posterior para ellos.
4. Si esta deshabilitado, los clientes deben tener saldo de billetera o credito de tiempo para iniciar sesion. Los clientes con saldo cero veran un mensaje indicandoles que visiten al cajero para recargar.
5. Haz clic en Guardar despues de cambiar el interruptor.

Resultado esperado: El comportamiento entra en vigor de inmediato para nuevas solicitudes de inicio de sesion. Las sesiones existentes no se ven afectadas.

Como vincular una identidad OAuth a un miembro existente

Si un cliente ya tiene una cuenta de miembro (creada manualmente por un cajero) y luego inicia sesion via OAuth por primera vez, el proceso de aprobacion puede vincular la identidad OAuth a su cuenta existente.

1. Cuando la solicitud de inicio de sesion OAuth llegue a la pagina de Solicitudes, verifica si el correo coincide con un miembro existente.
2. Si el sistema detecta una coincidencia, el dialogo de aprobacion ofrecera vincular la identidad OAuth al miembro existente en lugar de crear una nueva cuenta.
3. Aprueba la solicitud con la opcion de vinculacion seleccionada.

Resultado esperado: La cuenta de miembro existente obtiene un vinculo OAuth. Los futuros inicios de sesion desde este proveedor omitiran el paso de aprobacion e iniciaran sesion del miembro directamente (despues de la primera aprobacion).

Errores comunes a evitar

• Usar el tipo de cliente OAuth incorrecto en la Consola de Google Cloud. Debes seleccionar "TVs y dispositivos de entrada limitada" al crear el ID de cliente OAuth. Si seleccionas "Aplicacion web" o "Aplicacion de escritorio", el flujo de autorizacion de dispositivo no funcionara y el cliente no podra obtener un codigo de dispositivo.
• Olvidar activar el interruptor global de OAuth. Habilitar proveedores individuales no es suficiente. El interruptor maestro de OAuth en la parte superior de la pagina de ajustes OAuth tambien debe estar activo.
• No aprobar solicitudes de inicio de sesion. Los inicios de sesion OAuth requieren aprobacion explicita desde el servidor. Si nadie monitorea la pagina de Solicitudes, los clientes esperaran indefinidamente en la pantalla de espera. Considera asignar un cajero para monitorear solicitudes durante las horas de mayor demanda.
• Dejar que los codigos de dispositivo expiren. Los codigos de dispositivo tienen un tiempo de vida limitado (tipicamente 5-10 minutos). Si el cliente tarda demasiado en escanear el codigo QR y autenticarse, el codigo expira y deben comenzar de nuevo. Aconseja a los clientes que escaneen rapidamente.
• Pegar credenciales con espacios extra. Al copiar el ID de Cliente o Secreto de Cliente desde la consola del proveedor, asegurate de que no haya espacios al inicio o al final. Los espacios extra causaran fallos de autenticacion.
• Olvidar publicar la aplicacion OAuth de Google. Las aplicaciones de Google en modo "Prueba" solo permiten un numero limitado de usuarios de prueba. Para permitir que cualquier cliente inicie sesion, debes publicar la aplicacion a traves de la pagina de pantalla de consentimiento OAuth y completar los pasos de verificacion requeridos.
• Confundir el ID de Cliente y el Secreto de Cliente. Son dos valores diferentes. El ID de Cliente es publico. El Secreto de Cliente debe mantenerse confidencial. Intercambiarlos causara fallos de autenticacion.
• No configurar el nombre del cafe. El nombre del cafe de tus ajustes de HandyCafe se muestra en la pantalla de espera del cliente durante el flujo OAuth. Un nombre en blanco o predeterminado luce poco profesional. Establece el nombre de tu cafe en Ajustes > General antes de habilitar OAuth.