如何设置 OAuth 社交登录

本指南将带您完成社交登录的配置，让顾客可以使用其 Google、Facebook、Apple、X 或 Discord 账户登录客户端 PC。HandyCafe 使用设备授权授权流（RFC 8628），该流程专为没有完整浏览器的设备设计。顾客用手机扫描二维码进行身份验证。

前提条件

HandyCafe Server 的管理员访问权限。
Google Cloud Console 账户（用于 Google OAuth）或其他提供商的对应开发者门户访问权限。
HandyCafe Server 正在运行且可在您的网络上访问。
至少一台已连接的客户端 PC 用于测试登录流程。

HandyCafe 中 OAuth 设备流的工作原理

在深入设置之前，以下是流程的摘要：

空闲客户端 PC 上的顾客点击社交登录按钮（例如"使用 Google 登录"）。
客户端向服务端发送 OAuth 启动请求。
服务端联系提供商的设备授权端点，并收到设备代码、用户代码和验证 URL。
客户端在待机画面上显示二维码和用户代码。
顾客用手机扫描二维码，并向提供商进行身份验证。
服务端轮询提供商，直到身份验证完成。
服务端创建一个 OAuth 登录请求，显示在请求页面上。
管理员或收银员批准该请求。
新会员账户被创建（或现有账户被关联），顾客登录成功。

如何设置 Google OAuth

Google 是最常用的提供商。本节涵盖从创建 Google Cloud 项目到测试首次登录的每个步骤。

第 A 部分：创建 Google Cloud 凭证

在浏览器中打开 Google Cloud Console：https://console.cloud.google.com。
创建新项目或选择现有项目。使用易于识别的名称，例如"HandyCafe OAuth"。
导航至 API 和服务 > OAuth 同意屏幕。
选择外部作为用户类型（除非您有 Google Workspace 组织并且只想用于内部）。
填写必填字段：应用名称（"您的网吧名称"）、用户支持电子邮件和开发者联系电子邮件。
点击保存并继续，跳过范围和测试用户部分。您不需要添加特殊范围，默认的电子邮件和个人资料范围已足够。
导航至 API 和服务 > 凭证。
点击创建凭证 > OAuth 客户端 ID。
对于应用程序类型，选择电视和受限输入设备。这一点至关重要。HandyCafe 使用设备授权授权流，需要此特定客户端类型。
输入客户端名称（例如"HandyCafe 设备流"）。
点击创建。
从确认对话框中复制客户端 ID 和客户端密钥。请安全存储。下一节中您将需要这两个值。

第 B 部分：配置 HandyCafe Server

打开 HandyCafe Server 应用。
使用左侧边栏中的齿轮图标导航至设置。
选择 OAuth 标签页。
启用页面顶部的 OAuth 开关。这将在所有客户端 PC 上全局启用社交登录。
在提供商列表中找到 Google 提供商行。
启用 Google 开关以激活此提供商。
将步骤 12 中的客户端 ID 粘贴到客户端 ID 字段中。
将步骤 12 中的客户端密钥粘贴到客户端密钥字段中。
点击保存以应用配置。

预期结果： OAuth 标签页显示 Google 已启用并填写了您的凭证。设置被推送到所有已连接的客户端。

第 C 部分：测试登录流程

前往已连接的客户端 PC。待机画面现在应该显示带有 Google 登录按钮的社交登录部分。
在客户端待机画面上点击 Google 登录按钮。
客户端显示二维码和用户代码（短字母数字字符串）。
用手机扫描二维码。它会打开 Google 的设备验证页面。
使用 Google 账户登录，并在提示时输入用户代码。
授权应用程序。

预期结果： 在服务端，播放通知音，请求页面上出现新条目。请求显示 Google 账户名称、电子邮件地址以及发起登录的客户端 PC。

如何批准登录请求

每个 OAuth 登录都会生成一个请求，必须由管理员或收银员批准，顾客才能获得访问权限。

当登录请求到达时，服务端播放通知音，侧边栏中请求页面图标上出现徽章。
导航至请求页面。
待处理的请求显示：
- 提供商名称（例如 Google）。
- 提供商提供的显示名称（例如"张三"）。
- 电子邮件地址（例如"zhang@example.com"）。
- 发起请求的客户端 PC（主机名或显示名称）。
- 时间戳。
查看请求详情。验证客户端 PC 前的人与账户信息匹配。
点击批准接受请求。

预期结果： 如果没有与此 OAuth 身份关联的现有会员账户，系统将自动创建新会员账户，使用提供商提供的显示名称和电子邮件。顾客登录成功，客户端 PC 从待机画面切换到在线页面。如果会员账户之前已与此 OAuth 身份关联，则直接登录现有会员。

提示： 如果登录请求可疑（例如 PC 无人值守或请求看起来是自动发起的），请点击拒绝。顾客将看到"访问被拒绝"的消息，可以重试。

如何设置 Facebook OAuth

在浏览器中打开 Facebook 开发者门户：https://developers.facebook.com。
创建新应用。选择消费者应用类型。
导航至应用的设置 > 基本信息页面。记下应用 ID 和应用密钥。
导航至添加产品并添加设备的 Facebook 登录。
在设备的 Facebook 登录设置中，如果门户要求，请添加您的重定向 URI。
打开 HandyCafe Server 并导航至设置 > OAuth。
找到 Facebook 提供商行。
启用 Facebook 开关。
将应用 ID 粘贴到客户端 ID 字段中。
将应用密钥粘贴到客户端密钥字段中。
点击保存。

预期结果： Facebook 显示为已启用的提供商。客户端待机画面在其他已启用提供商旁边显示 Facebook 登录按钮。

如何设置 Discord OAuth

在浏览器中打开 Discord 开发者门户：https://discord.com/developers/applications。
创建新应用。以您的网吧命名。
在左侧边栏导航至 OAuth2 部分。
复制客户端 ID 并生成客户端密钥。请安全存储密钥，因为 Discord 只会显示一次。
打开 HandyCafe Server 并导航至设置 > OAuth。
找到 Discord 提供商行（默认已禁用）。
启用 Discord 开关。
将客户端 ID 粘贴到客户端 ID 字段中。
将客户端密钥粘贴到客户端密钥字段中。
点击保存。

预期结果： Discord 现在作为客户端待机画面上的登录选项可用。

如何允许无余额登录

默认情况下，HandyCafe 允许通过 OAuth 验证的顾客登录，即使他们没有钱包余额或时间额度。您可以更改此行为。

导航至设置 > OAuth。
找到允许无余额登录开关。
如果启用（默认），通过 OAuth 验证的顾客无论余额如何都可以登录。收银员可以为他们开始后付费时段。
如果禁用，顾客必须有钱包余额或时间额度才能登录。余额为零的顾客将看到一条消息，提示他们前往收银台充值。
更改开关后点击保存。

预期结果： 更改对新的登录请求立即生效。现有时段不受影响。

如何将 OAuth 身份关联到现有会员

如果顾客已有会员账户（由收银员手动创建），然后首次通过 OAuth 登录，批准过程可以将 OAuth 身份关联到其现有账户。

当 OAuth 登录请求到达请求页面时，检查电子邮件是否与现有会员匹配。
如果系统检测到匹配，批准对话框将提供将 OAuth 身份关联到现有会员的选项，而不是创建新账户。
选择关联选项后批准请求。

预期结果： 现有会员账户获得 OAuth 关联。来自此提供商的未来登录将绕过批准步骤，直接登录会员（在首次批准后）。

应避免的常见错误

在 Google Cloud Console 中使用了错误的 OAuth 客户端类型。 创建 OAuth 客户端 ID 时，您必须选择"电视和受限输入设备"。如果您选择"Web 应用程序"或"桌面应用程序"，设备授权流将无法工作，客户端将无法获取设备代码。
忘记启用全局 OAuth 开关。 仅启用单独的提供商是不够的。OAuth 设置页面顶部的主 OAuth 开关也必须打开。
未批准登录请求。 OAuth 登录需要服务端的明确批准。如果没有人监控请求页面，顾客将在待机画面上无限期等待。请考虑在繁忙时段分配收银员监控请求。
让设备代码过期。 设备代码有有限的有效期（通常为 5-10 分钟）。如果顾客花太长时间扫描二维码和验证，代码会过期，他们必须重新开始。请建议顾客及时扫描。
粘贴凭证时带有多余空格。 从提供商控制台复制客户端 ID 或客户端密钥时，请确保不含前后空格。多余的空格会导致身份验证失败。
忘记发布 Google OAuth 应用。 处于"测试"模式的 Google 应用只允许有限数量的测试用户。要允许任何顾客登录，您必须通过 OAuth 同意屏幕页面发布应用，并完成所需的验证步骤。
混淆了客户端 ID 和客户端密钥。 这是两个不同的值。客户端 ID 是面向公众的。客户端密钥必须保密。交换它们会导致身份验证失败。
未配置网吧名称。 您的 HandyCafe 设置中的网吧名称会在 OAuth 流程中显示在客户端待机画面上。空白或默认名称显得不专业。启用 OAuth 之前，请在设置 > 常规中设置您的网吧名称。