Cách Thiết Lập Đăng Nhập Xã Hội OAuth

Hướng dẫn này sẽ giúp bạn cấu hình đăng nhập xã hội để khách hàng có thể đăng nhập vào máy khách bằng tài khoản Google, Facebook, Apple, X, hoặc Discord. HandyCafe sử dụng Device Authorization Grant flow (RFC 8628), được thiết kế cho các thiết bị không có trình duyệt đầy đủ. Khách hàng quét mã QR bằng điện thoại để xác thực.

Bạn Cần Chuẩn Bị

Quyền truy cập quản trị vào HandyCafe Server.
Tài khoản Google Cloud Console (cho Google OAuth) hoặc quyền truy cập cổng nhà phát triển tương đương cho các nhà cung cấp khác.
HandyCafe Server đang chạy và có thể truy cập trên mạng của bạn.
Ít nhất một máy khách được kết nối để kiểm tra quy trình đăng nhập.

Cách Hoạt Động của OAuth Device Flow trong HandyCafe

Trước khi bắt đầu thiết lập, đây là tóm tắt về quy trình:

Khách hàng tại máy khách nhàn rỗi nhấp vào nút đăng nhập xã hội (ví dụ: "Đăng nhập bằng Google").
Máy khách gửi yêu cầu bắt đầu OAuth đến máy chủ.
Máy chủ liên hệ với endpoint ủy quyền thiết bị của nhà cung cấp và nhận mã thiết bị, mã người dùng và URL xác minh.
Máy khách hiển thị mã QR và mã người dùng trên màn hình nhàn rỗi.
Khách hàng quét mã QR bằng điện thoại và xác thực với nhà cung cấp.
Máy chủ kiểm tra nhà cung cấp cho đến khi xác thực hoàn tất.
Máy chủ tạo Yêu Cầu Đăng Nhập OAuth xuất hiện trên trang Yêu Cầu.
Quản trị viên hoặc thu ngân phê duyệt yêu cầu.
Tài khoản thành viên mới được tạo (hoặc tài khoản hiện có được liên kết) và khách hàng được đăng nhập.

Cách Thiết Lập Google OAuth

Google là nhà cung cấp được sử dụng phổ biến nhất. Phần này bao gồm mọi bước từ tạo dự án Google Cloud đến kiểm tra lần đăng nhập đầu tiên.

Phần A: Tạo Thông Tin Xác Thực Google Cloud

Mở Google Cloud Console tại https://console.cloud.google.com trong trình duyệt của bạn.
Tạo một dự án mới hoặc chọn một dự án hiện có. Đặt tên dễ nhận biết như "HandyCafe OAuth."
Điều hướng đến APIs & Services > OAuth consent screen.
Chọn External làm loại người dùng (trừ khi bạn có tổ chức Google Workspace và muốn chỉ nội bộ).
Điền vào các trường bắt buộc: Tên ứng dụng ("Tên Quán Cà Phê của Bạn"), Email hỗ trợ người dùng và Email liên hệ nhà phát triển.
Nhấp Save and Continue qua các phần Scopes và Test Users. Bạn không cần thêm phạm vi đặc biệt. Phạm vi email và profile mặc định là đủ.
Điều hướng đến APIs & Services > Credentials.
Nhấp Create Credentials > OAuth client ID.
Đối với loại Ứng dụng, chọn TVs and Limited Input devices. Điều này rất quan trọng. HandyCafe sử dụng device authorization grant flow, yêu cầu loại client cụ thể này.
Nhập tên cho client (ví dụ: "HandyCafe Device Flow").
Nhấp Create.
Sao chép Client ID và Client Secret từ hộp thoại xác nhận. Lưu trữ chúng an toàn. Bạn sẽ cần cả hai giá trị trong phần tiếp theo.

Phần B: Cấu Hình HandyCafe Server

Mở ứng dụng HandyCafe Server.
Điều hướng đến Settings bằng biểu tượng bánh răng ở thanh bên trái.
Chọn tab OAuth.
Bật công tắc OAuth ở đầu trang. Điều này kích hoạt đăng nhập xã hội trên tất cả các máy khách.
Tìm hàng nhà cung cấp Google trong danh sách nhà cung cấp.
Bật công tắc Google để kích hoạt nhà cung cấp này.
Dán Client ID từ bước 12 vào trường Client ID.
Dán Client Secret từ bước 12 vào trường Client Secret.
Nhấp Save để áp dụng cấu hình.

Kết quả mong đợi: Tab OAuth hiển thị Google đã được kích hoạt với thông tin xác thực của bạn đã điền. Các cài đặt được đẩy đến tất cả các máy khách được kết nối.

Phần C: Kiểm Tra Quy Trình Đăng Nhập

Đến một máy khách được kết nối. Màn hình nhàn rỗi bây giờ sẽ hiển thị phần đăng nhập xã hội với nút đăng nhập Google.
Nhấp vào nút đăng nhập Google trên màn hình nhàn rỗi của máy khách.
Máy khách hiển thị mã QR và mã người dùng (một chuỗi ký tự ngắn).
Quét mã QR bằng điện thoại của bạn. Nó mở trang xác minh thiết bị của Google.
Đăng nhập bằng tài khoản Google và nhập mã người dùng khi được yêu cầu.
Ủy quyền ứng dụng.

Kết quả mong đợi: Trên máy chủ, âm thanh thông báo phát ra và một mục mới xuất hiện trên trang Yêu Cầu. Yêu cầu hiển thị tên tài khoản Google, địa chỉ email và máy khách đã khởi tạo đăng nhập.

Cách Phê Duyệt Yêu Cầu Đăng Nhập

Mỗi lần đăng nhập OAuth tạo ra một yêu cầu cần được phê duyệt bởi quản trị viên hoặc thu ngân trước khi khách hàng có quyền truy cập.

Khi yêu cầu đăng nhập đến, âm thanh thông báo phát ra trên máy chủ và một huy hiệu xuất hiện trên biểu tượng trang Yêu Cầu trong thanh bên.
Điều hướng đến trang Yêu Cầu.
Yêu cầu đang chờ hiển thị:
- Tên nhà cung cấp (ví dụ: Google).
- Tên hiển thị từ nhà cung cấp (ví dụ: "John Smith").
- Địa chỉ email (ví dụ: "john@example.com").
- Máy khách đã khởi tạo yêu cầu (tên máy hoặc tên hiển thị).
- Dấu thời gian.
Xem xét chi tiết yêu cầu. Xác minh rằng người tại máy khách khớp với thông tin tài khoản.
Nhấp Approve để chấp nhận yêu cầu.

Kết quả mong đợi: Nếu không có tài khoản thành viên hiện có nào được liên kết với danh tính OAuth này, một tài khoản thành viên mới được tạo tự động. Tên hiển thị và email từ nhà cung cấp được sử dụng. Khách hàng được đăng nhập và máy khách chuyển từ màn hình nhàn rỗi sang Trang Trực Tuyến. Nếu một tài khoản thành viên đã được liên kết trước đó với danh tính OAuth này, thành viên hiện có được đăng nhập trực tiếp.

Mẹo: Nếu yêu cầu đăng nhập có vẻ đáng ngờ (ví dụ: máy khách không có người hoặc yêu cầu trông tự động), nhấp Reject thay vào đó. Khách hàng sẽ thấy thông báo "Truy cập bị từ chối" và có thể thử lại.

Cách Thiết Lập Facebook OAuth

Mở Facebook Developer Portal tại https://developers.facebook.com .
Tạo một ứng dụng mới. Chọn loại ứng dụng Consumer.
Điều hướng đến trang Settings > Basic của ứng dụng. Ghi chú App ID và App Secret.
Điều hướng đến Add Product và thêm Facebook Login for Devices.
Trong cài đặt Facebook Login for Devices, thêm các URI chuyển hướng của bạn nếu cổng yêu cầu.
Mở HandyCafe Server và điều hướng đến Settings > OAuth.
Tìm hàng nhà cung cấp Facebook.
Bật công tắc Facebook.
Dán App ID vào trường Client ID.
Dán App Secret vào trường Client Secret.
Nhấp Save.

Kết quả mong đợi: Facebook xuất hiện như một nhà cung cấp đã được kích hoạt. Màn hình nhàn rỗi của máy khách hiển thị nút đăng nhập Facebook cùng với bất kỳ nhà cung cấp nào khác đã được kích hoạt.

Cách Thiết Lập Discord OAuth

Mở Discord Developer Portal tại https://discord.com/developers/applications .
Tạo một ứng dụng mới. Đặt tên theo quán cà phê của bạn.
Điều hướng đến phần OAuth2 trong thanh bên trái.
Sao chép Client ID và tạo Client Secret. Lưu trữ bí mật an toàn vì Discord chỉ hiển thị một lần.
Mở HandyCafe Server và điều hướng đến Settings > OAuth.
Tìm hàng nhà cung cấp Discord (nó bị vô hiệu hóa theo mặc định).
Bật công tắc Discord.
Dán Client ID vào trường Client ID.
Dán Client Secret vào trường Client Secret.
Nhấp Save.

Kết quả mong đợi: Discord hiện có sẵn như một tùy chọn đăng nhập trên màn hình nhàn rỗi của máy khách.

Cách Cho Phép Đăng Nhập Không Cần Tín Dụng

Theo mặc định, HandyCafe cho phép khách hàng xác thực qua OAuth đăng nhập ngay cả khi họ không có số dư ví hoặc tín dụng thời gian. Bạn có thể thay đổi hành vi này.

Điều hướng đến Settings > OAuth.
Tìm công tắc Allow Login Without Credit.
Nếu được bật (mặc định), khách hàng xác thực qua OAuth có thể đăng nhập bất kể số dư của họ. Một thu ngân có thể bắt đầu phiên trả sau cho họ.
Nếu bị vô hiệu hóa, khách hàng phải có số dư ví hoặc tín dụng thời gian để đăng nhập. Khách hàng có số dư bằng không sẽ thấy thông báo yêu cầu đến gặp thu ngân để nạp tiền.
Nhấp Save sau khi thay đổi công tắc.

Kết quả mong đợi: Hành vi có hiệu lực ngay lập tức cho các yêu cầu đăng nhập mới. Các phiên hiện tại không bị ảnh hưởng.

Cách Liên Kết Danh Tính OAuth với Thành Viên Hiện Có

Nếu khách hàng đã có tài khoản thành viên (được tạo thủ công bởi thu ngân) và sau đó đăng nhập qua OAuth lần đầu tiên, quy trình phê duyệt có thể liên kết danh tính OAuth với tài khoản hiện có của họ.

Khi yêu cầu đăng nhập OAuth đến trang Yêu Cầu, kiểm tra xem email có khớp với thành viên hiện có không.
Nếu hệ thống phát hiện khớp, hộp thoại phê duyệt sẽ cung cấp tùy chọn liên kết danh tính OAuth với thành viên hiện có thay vì tạo tài khoản mới.
Phê duyệt yêu cầu với tùy chọn liên kết được chọn.

Kết quả mong đợi: Tài khoản thành viên hiện có có được liên kết OAuth. Các lần đăng nhập trong tương lai từ nhà cung cấp này sẽ bỏ qua bước phê duyệt và đăng nhập thành viên trực tiếp (sau lần phê duyệt đầu tiên).

Những Sai Lầm Thường Gặp Cần Tránh

Sử dụng sai loại client OAuth trong Google Cloud Console. Bạn phải chọn "TVs and Limited Input devices" khi tạo OAuth client ID. Nếu bạn chọn "Web application" hoặc "Desktop app," device authorization flow sẽ không hoạt động và máy khách sẽ không nhận được mã thiết bị.
Quên bật công tắc OAuth toàn cầu. Kích hoạt các nhà cung cấp riêng lẻ là không đủ. Công tắc OAuth chính ở đầu trang cài đặt OAuth cũng phải được bật.
Không phê duyệt yêu cầu đăng nhập. Đăng nhập OAuth yêu cầu phê duyệt rõ ràng từ máy chủ. Nếu không ai giám sát trang Yêu Cầu, khách hàng sẽ chờ vô thời hạn tại màn hình nhàn rỗi. Hãy cân nhắc phân công một thu ngân giám sát yêu cầu trong giờ cao điểm.
Để mã thiết bị hết hạn. Mã thiết bị có thời gian sống giới hạn (thường là 5-10 phút). Nếu khách hàng mất quá nhiều thời gian để quét mã QR và xác thực, mã sẽ hết hạn và họ phải bắt đầu lại. Khuyên khách hàng quét nhanh chóng.
Dán thông tin xác thực với khoảng trắng thừa. Khi sao chép Client ID hoặc Client Secret từ cổng nhà cung cấp, đảm bảo không có khoảng trắng đầu hoặc cuối. Khoảng trắng thừa sẽ gây ra lỗi xác thực.
Quên xuất bản ứng dụng Google OAuth. Các ứng dụng Google ở chế độ "Testing" chỉ cho phép một số lượng người dùng thử nghiệm hạn chế. Để cho phép bất kỳ khách hàng nào đăng nhập, bạn phải xuất bản ứng dụng thông qua trang OAuth consent screen và hoàn thành bất kỳ bước xác minh cần thiết nào.
Nhầm lẫn giữa Client ID và Client Secret. Đây là hai giá trị khác nhau. Client ID là công khai. Client Secret phải được giữ bí mật. Hoán đổi chúng sẽ gây ra lỗi xác thực.
Không cấu hình tên quán cà phê. Tên quán cà phê từ cài đặt HandyCafe của bạn được hiển thị trên màn hình nhàn rỗi của máy khách trong quá trình OAuth. Một tên trống hoặc mặc định trông không chuyên nghiệp. Đặt tên quán cà phê của bạn trong Settings > General trước khi kích hoạt OAuth.