OAuth Login

HandyCafe supports social/OAuth login for customers using the Device Authorization Grant (RFC 8628). This flow is designed for kiosk and public environments where customers cannot safely enter credentials on shared PCs.

Supported Providers

Each provider can be individually enabled or disabled in Settings > OAuth.

Authentication Flow

The device authorization flow proceeds through the following steps:

1. Customer selects a provider -- on the client idle screen, the customer taps a provider button (e.g., Google, Discord).
2. Client sends request to server -- the client notifies the HandyCafe server that an OAuth login has been initiated.
3. Server requests a device code -- the server contacts the selected provider's device authorization endpoint and receives a device code, user code, and verification URI.
4. Client displays the code -- the client shows the user_code and verification_uri to the customer, typically rendered as a QR code for easy scanning.
5. Customer authenticates on their phone -- the customer scans the QR code with their personal device (phone or tablet) and completes authentication on the provider's website.
6. Server polls for token -- the server periodically polls the provider for a token. Poll states include:
   • Pending -- the customer has not yet completed authentication.
   • SlowDown -- polling too frequently; the server backs off.
   • Success -- authentication completed; token received.
   • Expired -- the device code has expired before authentication.
   • Error -- an unexpected error occurred.
7. Server retrieves user info -- on success, the server uses the token to fetch the customer's profile from the provider, including provider_uid, email, name, and avatar_url.
8. Admin approves or rejects -- the login request appears on the Requests Page. An admin or cashier reviews and approves or rejects the request.
9. Member created or linked -- if approved, a new member account is created or the OAuth identity is linked to an existing member.
10. Client session starts -- the client receives confirmation and the customer's session begins.

Security Considerations

• Credentials never touch the shared PC. Customers authenticate on their personal devices only. No passwords or tokens are entered on the client machine.
• Admin approval gate. Every OAuth login request must be approved by an admin or cashier before a session starts, preventing unauthorized access.
• Configurable credit requirement. An "allow login without credit" option can be enabled or disabled, controlling whether customers need a positive balance to log in via OAuth.

Configuration

OAuth providers are configured in Settings > OAuth. Each provider requires its own client credentials (client ID and client secret) obtained from the provider's developer console. Enable only the providers you want to offer to your customers.