Cómo configurar el inicio de sesión social con OAuth

Esta guía te lleva paso a paso por la configuración del inicio de sesión 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 Autorización de Dispositivo (RFC 8628), diseñado para dispositivos sin navegador completo. Los clientes escanean un código QR con su teléfono para autenticarse.

Lo que necesitarás

• 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 sesión.

Cómo funciona el flujo de dispositivo OAuth en HandyCafe

Antes de comenzar la configuración, aquí tienes un resumen del flujo:

1. Un cliente en un PC inactivo hace clic en el botón de inicio de sesión social (ej. "Iniciar sesión con Google").
2. El cliente envía una solicitud de inicio OAuth al servidor.
3. El servidor contacta al endpoint de autorización de dispositivo del proveedor y recibe un código de dispositivo, un código de usuario y una URL de verificación.
4. El cliente muestra un código QR y el código de usuario en la pantalla de espera.
5. El cliente escanea el código QR con su teléfono y se autentica con el proveedor.
6. El servidor consulta al proveedor hasta que la autenticación se completa.
7. El servidor crea una Solicitud de Inicio de Sesión OAuth que aparece en la página 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 sesión.

Cómo configurar OAuth de Google

Google es el proveedor más utilizado. Esta sección cubre cada paso desde la creación del proyecto en Google Cloud hasta la prueba del primer inicio de sesión.

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. Nómbralo 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 organización de Google Workspace y quieras solo uso interno).
5. Completa los campos requeridos: Nombre de la aplicación ("Nombre de tu Café"), Correo de soporte al usuario y Correo de contacto del desarrollador.
6. Haz clic en Guardar y Continuar a través 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 aplicación, selecciona TVs y dispositivos de entrada limitada. Esto es crítico. HandyCafe usa el flujo de autorización de dispositivo, que requiere este tipo de cliente específico.
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 diálogo de confirmación. Guárdalos de forma segura. Necesitarás ambos valores en la siguiente sección.

Parte B: Configurar el servidor HandyCafe

13. Abre la aplicación del servidor HandyCafe.
14. Navega a Ajustes usando el icono de engranaje en la barra lateral izquierda.
15. Selecciona la pestaña OAuth.
16. Activa el interruptor de OAuth en la parte superior de la página. Esto habilita globalmente el inicio de sesión 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 configuración.

Resultado esperado: La pestaña OAuth muestra Google como habilitado con tus credenciales completadas. Los ajustes se envían a todos los clientes conectados.

Parte C: Probar el flujo de inicio de sesión

22. Ve a un PC cliente conectado. La pantalla de espera ahora debería mostrar una sección de inicio de sesión social con un botón de Google.
23. Haz clic en el botón de Google en la pantalla de espera del cliente.
24. El cliente muestra un código QR y un código de usuario (una cadena alfanumérica corta).
25. Escanea el código QR con tu teléfono. Se abre la página de verificación de dispositivo de Google.
26. Inicia sesión con una cuenta de Google e ingresa el código de usuario cuando se te solicite.
27. Autoriza la aplicación.

Resultado esperado: En el servidor, suena una notificación y aparece una nueva entrada en la página de Solicitudes. La solicitud muestra el nombre de la cuenta de Google, la dirección de correo y el PC cliente que inició el proceso de sesión.

Cómo aprobar una solicitud de inicio de sesión

Cada inicio de sesión 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 sesión, suena una notificación en el servidor y aparece una insignia en el icono de la página de Solicitudes en la barra lateral.
2. Navega a la página de Solicitudes.
3. La solicitud pendiente muestra:
   • Nombre del proveedor (ej. Google).
   • Nombre de visualización del proveedor (ej. "Juan García").
   • Dirección de correo (ej. "juan@example.com").
   • El PC cliente que inició la solicitud (nombre de equipo o nombre de visualización).
   • Marca de tiempo.
4. Revisa los detalles de la solicitud. Verifica que la persona en el PC cliente coincida con la información 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 automáticamente una nueva cuenta de miembro. Se usan el nombre de visualización y correo del proveedor. El cliente inicia sesión y el PC cliente pasa de la pantalla de espera a la página en línea. Si una cuenta de miembro fue vinculada previamente a esta identidad OAuth, el miembro existente inicia sesión directamente.

Consejo: Si la solicitud de inicio de sesión es sospechosa (ej. el PC está desatendido o la solicitud parece automatizada), haz clic en Rechazar en su lugar. El cliente verá un mensaje de "Acceso denegado" y podrá intentar de nuevo.

Cómo configurar OAuth de Facebook

1. Abre el Portal de Desarrolladores de Facebook en https://developers.facebook.com .
2. Crea una nueva aplicación. Selecciona el tipo de aplicación Consumidor.
3. Navega a la página Configuración > Básico de la aplicación. Anota el ID de Aplicación y el Secreto de Aplicación.
4. Navega a Agregar Producto y agrega Facebook Login para Dispositivos.
5. En la configuración de Facebook Login para Dispositivos, agrega tus URIs de redirección 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 Aplicación en el campo ID de Cliente.
10. Pega el Secreto de Aplicación 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 botón de inicio de sesión de Facebook junto a cualquier otro proveedor habilitado.

Cómo configurar OAuth de Discord

1. Abre el Portal de Desarrolladores de Discord en https://discord.com/developers/applications .
2. Crea una nueva aplicación. Nombra la aplicación con el nombre de tu café.
3. Navega a la sección 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 (está 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 está ahora disponible como opción de inicio de sesión en las pantallas de espera del cliente.

Cómo permitir el inicio de sesión sin crédito

Por defecto, HandyCafe permite que los clientes autenticados por OAuth inicien sesión aunque no tengan saldo de billetera ni crédito de tiempo. Puedes cambiar este comportamiento.

1. Navega a Ajustes > OAuth.
2. Localiza el interruptor Permitir inicio de sesión sin crédito.
3. Si está habilitado (predeterminado), los clientes que se autentiquen vía OAuth pueden iniciar sesión sin importar su saldo. Un cajero puede iniciar una sesión de pago posterior para ellos.
4. Si está deshabilitado, los clientes deben tener saldo de billetera o crédito de tiempo para iniciar sesión. Los clientes con saldo cero verán un mensaje indicándoles que visiten al cajero para recargar.
5. Haz clic en Guardar después de cambiar el interruptor.

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

Cómo 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 sesión vía OAuth por primera vez, el proceso de aprobación puede vincular la identidad OAuth a su cuenta existente.

1. Cuando la solicitud de inicio de sesión OAuth llegue a la página de Solicitudes, verifica si el correo coincide con un miembro existente.
2. Si el sistema detecta una coincidencia, el diálogo de aprobación ofrecerá vincular la identidad OAuth al miembro existente en lugar de crear una nueva cuenta.
3. Aprueba la solicitud con la opción de vinculación seleccionada.

Resultado esperado: La cuenta de miembro existente obtiene un vínculo OAuth. Los futuros inicios de sesión desde este proveedor omitirán el paso de aprobación e iniciarán sesión del miembro directamente (después de la primera aprobación).

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 "Aplicación web" o "Aplicación de escritorio", el flujo de autorización de dispositivo no funcionará y el cliente no podrá obtener un código 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 página de ajustes OAuth también debe estar activo.
• No aprobar solicitudes de inicio de sesión. Los inicios de sesión OAuth requieren aprobación explícita desde el servidor. Si nadie monitorea la página de Solicitudes, los clientes esperarán indefinidamente en la pantalla de espera. Considera asignar un cajero para monitorear solicitudes durante las horas de mayor demanda.
• Dejar que los códigos de dispositivo expiren. Los códigos de dispositivo tienen un tiempo de vida limitado (típicamente 5-10 minutos). Si el cliente tarda demasiado en escanear el código QR y autenticarse, el código expira y deben comenzar de nuevo. Aconseja a los clientes que escaneen rápidamente.
• Pegar credenciales con espacios extra. Al copiar el ID de Cliente o Secreto de Cliente desde la consola del proveedor, asegúrate de que no haya espacios al inicio o al final. Los espacios extra causarán fallos de autenticación.
• Olvidar publicar la aplicación OAuth de Google. Las aplicaciones de Google en modo "Prueba" solo permiten un número limitado de usuarios de prueba. Para permitir que cualquier cliente inicie sesión, debes publicar la aplicación a través de la página de pantalla de consentimiento OAuth y completar los pasos de verificación requeridos.
• Confundir el ID de Cliente y el Secreto de Cliente. Son dos valores diferentes. El ID de Cliente es público. El Secreto de Cliente debe mantenerse confidencial. Intercambiarlos causará fallos de autenticación.
• No configurar el nombre del café. El nombre del café 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 café en Ajustes > General antes de habilitar OAuth.