HandyCafe Docs
owner it-admin

How to Set Up OAuth Social Login

This guide walks you through configuring social login so customers can sign in to client PCs using their Google, Facebook, Apple, X, or Discord accounts. HandyCafe uses the Device Authorization Grant flow (RFC 8628), which is designed for devices without a full browser. Customers scan a QR code with their phone to authenticate.

What You Will Need

  • Admin access to the HandyCafe Server.
  • A Google Cloud Console account (for Google OAuth) or equivalent developer portal access for other providers.
  • The HandyCafe Server running and accessible on your network.
  • At least one connected client PC to test the login flow.

How OAuth Device Flow Works in HandyCafe

Before diving into setup, here is a summary of the flow:

  1. A customer at an idle client PC clicks the social login button (e.g., "Sign in with Google").
  2. The client sends an OAuth start request to the server.
  3. The server contacts the provider's device authorization endpoint and receives a device code, a user code, and a verification URL.
  4. The client displays a QR code and the user code on the idle screen.
  5. The customer scans the QR code with their phone and authenticates with the provider.
  6. The server polls the provider until authentication completes.
  7. The server creates an OAuth Login Request that appears on the Requests page.
  8. An admin or cashier approves the request.
  9. A new member account is created (or an existing account is linked) and the customer is logged in.

How to Set Up Google OAuth

Google is the most commonly used provider. This section covers every step from creating the Google Cloud project to testing the first login.

Part A: Create Google Cloud Credentials

  1. Open the Google Cloud Console at https://console.cloud.google.com in your browser.
  2. Create a new project or select an existing one. Name it something recognizable like "HandyCafe OAuth."
  3. Navigate to APIs & Services > OAuth consent screen.
  4. Select External as the user type (unless you have a Google Workspace organization and want internal only).
  5. Fill in the required fields: App name ("Your Cafe Name"), User support email, and Developer contact email.
  6. Click Save and Continue through the Scopes and Test Users sections. You do not need to add special scopes. The default email and profile scopes are sufficient.
  7. Navigate to APIs & Services > Credentials.
  8. Click Create Credentials > OAuth client ID.
  9. For Application type, select TVs and Limited Input devices. This is critical. HandyCafe uses the device authorization grant flow, which requires this specific client type.
  10. Enter a name for the client (e.g., "HandyCafe Device Flow").
  11. Click Create.
  12. Copy the Client ID and Client Secret from the confirmation dialog. Store them securely. You will need both values in the next section.

Part B: Configure HandyCafe Server

  1. Open the HandyCafe Server application.
  2. Navigate to Settings using the gear icon in the left sidebar.
  3. Select the OAuth tab.
  4. Enable the OAuth toggle at the top of the page. This globally enables social login across all client PCs.
  5. Locate the Google provider row in the providers list.
  6. Enable the Google toggle to activate this provider.
  7. Paste your Client ID from step 12 into the Client ID field.
  8. Paste your Client Secret from step 12 into the Client Secret field.
  9. Click Save to apply the configuration.

Expected result: The OAuth tab shows Google as enabled with your credentials filled in. The settings are pushed to all connected clients.

Part C: Test the Login Flow

  1. Go to a connected client PC. The idle screen should now show a social login section with a Google login button.
  2. Click the Google login button on the client idle screen.
  3. The client displays a QR code and a user code (a short alphanumeric string).
  4. Scan the QR code with your phone. It opens Google's device verification page.
  5. Sign in with a Google account and enter the user code when prompted.
  6. Authorize the application.

Expected result: On the server, a notification sound plays and a new entry appears on the Requests page. The request shows the Google account name, email address, and the client PC that initiated the login.

How to Approve a Login Request

Every OAuth login generates a request that must be approved by an admin or cashier before the customer gains access.

  1. When a login request arrives, a notification sound plays on the server and a badge appears on the Requests page icon in the sidebar.
  2. Navigate to the Requests page.
  3. The pending request shows:
    • Provider name (e.g., Google).
    • Display name from the provider (e.g., "John Smith").
    • Email address (e.g., "john@example.com").
    • The client PC that initiated the request (hostname or display name).
    • Timestamp.
  4. Review the request details. Verify that the person at the client PC matches the account information.
  5. Click Approve to accept the request.

Expected result: If no existing member account is linked to this OAuth identity, a new member account is created automatically. The display name and email from the provider are used. The customer is logged in and the client PC transitions from the idle screen to the Online Page. If a member account was previously linked to this OAuth identity, the existing member is logged in directly.

Tip: If the login request is suspicious (e.g., the PC is unattended or the request looks automated), click Reject instead. The customer will see an "Access denied" message and can try again.

How to Set Up Facebook OAuth

  1. Open the Facebook Developer Portal at https://developers.facebook.com .
  2. Create a new app. Select the Consumer app type.
  3. Navigate to the app's Settings > Basic page. Note the App ID and App Secret.
  4. Navigate to Add Product and add Facebook Login for Devices.
  5. In the Facebook Login for Devices settings, add your redirect URIs if required by the portal.
  6. Open the HandyCafe Server and navigate to Settings > OAuth.
  7. Locate the Facebook provider row.
  8. Enable the Facebook toggle.
  9. Paste the App ID into the Client ID field.
  10. Paste the App Secret into the Client Secret field.
  11. Click Save.

Expected result: Facebook appears as an enabled provider. Client idle screens show a Facebook login button alongside any other enabled providers.

How to Set Up Discord OAuth

  1. Open the Discord Developer Portal at https://discord.com/developers/applications .
  2. Create a new application. Name it after your cafe.
  3. Navigate to the OAuth2 section in the left sidebar.
  4. Copy the Client ID and generate a Client Secret. Store the secret securely as Discord only shows it once.
  5. Open the HandyCafe Server and navigate to Settings > OAuth.
  6. Locate the Discord provider row (it is disabled by default).
  7. Enable the Discord toggle.
  8. Paste the Client ID into the Client ID field.
  9. Paste the Client Secret into the Client Secret field.
  10. Click Save.

Expected result: Discord is now available as a login option on client idle screens.

How to Allow Login Without Credit

By default, HandyCafe allows OAuth-authenticated customers to log in even if they have no wallet balance or time credit. You can change this behavior.

  1. Navigate to Settings > OAuth.
  2. Locate the Allow Login Without Credit toggle.
  3. If enabled (default), customers who authenticate via OAuth can log in regardless of their balance. A cashier can start a postpaid session for them.
  4. If disabled, customers must have either a wallet balance or time credit to log in. Customers with zero balance will see a message telling them to visit the cashier to top up.
  5. Click Save after changing the toggle.

Expected result: The behavior takes effect immediately for new login requests. Existing sessions are not affected.

How to Link an OAuth Identity to an Existing Member

If a customer already has a member account (created manually by a cashier) and then logs in via OAuth for the first time, the approval process can link the OAuth identity to their existing account.

  1. When the OAuth login request arrives on the Requests page, check if the email matches an existing member.
  2. If the system detects a match, the approval dialog will offer to link the OAuth identity to the existing member instead of creating a new account.
  3. Approve the request with the link option selected.

Expected result: The existing member account gains an OAuth link. Future logins from this provider will bypass the approval step and log the member in directly (after the first approval).

Common Mistakes to Avoid

  • Using the wrong OAuth client type in Google Cloud Console. You must select "TVs and Limited Input devices" when creating the OAuth client ID. If you select "Web application" or "Desktop app," the device authorization flow will not work and the client will fail to get a device code.
  • Forgetting to enable the global OAuth toggle. Enabling individual providers is not enough. The master OAuth toggle at the top of the OAuth settings page must also be on.
  • Not approving login requests. OAuth logins require explicit approval from the server. If no one monitors the Requests page, customers will wait indefinitely at the idle screen. Consider assigning a cashier to monitor requests during busy hours.
  • Letting device codes expire. Device codes have a limited lifetime (typically 5-10 minutes). If the customer takes too long to scan the QR code and authenticate, the code expires and they must start over. Advise customers to scan promptly.
  • Pasting credentials with extra whitespace. When copying Client ID or Client Secret from the provider console, ensure no leading or trailing spaces are included. Extra whitespace will cause authentication failures.
  • Forgetting to publish the Google OAuth app. Google apps in "Testing" mode only allow a limited number of test users. To allow any customer to log in, you must publish the app through the OAuth consent screen page and complete any required verification steps.
  • Mixing up Client ID and Client Secret. These are two different values. The Client ID is public-facing. The Client Secret must be kept confidential. Swapping them will cause authentication failures.
  • Not configuring the cafe name. The cafe name from your HandyCafe settings is displayed on the client idle screen during the OAuth flow. A blank or default name looks unprofessional. Set your cafe name in Settings > General before enabling OAuth.