Cara Menyiapkan Login Sosial OAuth

Panduan ini memandu Anda melalui konfigurasi login sosial agar pelanggan dapat masuk ke PC klien menggunakan akun Google, Facebook, Apple, X, atau Discord mereka. HandyCafe menggunakan alur Device Authorization Grant (RFC 8628), yang dirancang untuk perangkat tanpa browser lengkap. Pelanggan memindai kode QR dengan ponsel mereka untuk melakukan autentikasi.

Yang Anda Butuhkan

• Akses admin ke HandyCafe Server.
• Akun Google Cloud Console (untuk Google OAuth) atau akses portal developer setara untuk penyedia lain.
• HandyCafe Server yang berjalan dan dapat diakses di jaringan Anda.
• Setidaknya satu PC klien yang terhubung untuk menguji alur login.

Cara Kerja Device Flow OAuth di HandyCafe

Sebelum masuk ke pengaturan, berikut ringkasan alurnya:

1. Pelanggan di PC klien yang idle mengklik tombol login sosial (misalnya, "Sign in with Google").
2. Klien mengirimkan permintaan mulai OAuth ke server.
3. Server menghubungi endpoint otorisasi perangkat penyedia dan menerima kode perangkat, kode pengguna, dan URL verifikasi.
4. Klien menampilkan kode QR dan kode pengguna di layar idle.
5. Pelanggan memindai kode QR dengan ponsel mereka dan melakukan autentikasi dengan penyedia.
6. Server melakukan polling ke penyedia sampai autentikasi selesai.
7. Server membuat Permintaan Login OAuth yang muncul di halaman Requests.
8. Admin atau kasir menyetujui permintaan.
9. Akun anggota baru dibuat (atau akun yang sudah ada dihubungkan) dan pelanggan masuk.

Cara Menyiapkan Google OAuth

Google adalah penyedia yang paling umum digunakan. Bagian ini mencakup setiap langkah mulai dari membuat proyek Google Cloud hingga menguji login pertama.

Bagian A: Buat Kredensial Google Cloud

1. Buka Google Cloud Console di https://console.cloud.google.com di browser Anda.
2. Buat proyek baru atau pilih yang sudah ada. Beri nama yang mudah dikenali seperti "HandyCafe OAuth."
3. Navigasikan ke APIs & Services > OAuth consent screen.
4. Pilih External sebagai jenis pengguna (kecuali Anda memiliki organisasi Google Workspace dan ingin hanya internal).
5. Isi field yang diperlukan: App name ("Nama Kafe Anda"), User support email, dan Developer contact email.
6. Klik Save and Continue melalui bagian Scopes dan Test Users. Anda tidak perlu menambahkan scope khusus. Scope email dan profil default sudah cukup.
7. Navigasikan ke APIs & Services > Credentials.
8. Klik Create Credentials > OAuth client ID.
9. Untuk Application type, pilih TVs and Limited Input devices. Ini sangat penting. HandyCafe menggunakan alur otorisasi perangkat, yang memerlukan jenis klien khusus ini.
10. Masukkan nama untuk klien (misalnya, "HandyCafe Device Flow").
11. Klik Create.
12. Salin Client ID dan Client Secret dari dialog konfirmasi. Simpan dengan aman. Anda akan membutuhkan kedua nilai ini di bagian berikutnya.

Bagian B: Konfigurasikan HandyCafe Server

13. Buka aplikasi HandyCafe Server.
14. Navigasikan ke Settings menggunakan ikon roda gigi di sidebar kiri.
15. Pilih tab OAuth.
16. Aktifkan tombol OAuth di bagian atas halaman. Ini mengaktifkan login sosial secara global di semua PC klien.
17. Temukan baris penyedia Google dalam daftar penyedia.
18. Aktifkan tombol Google untuk mengaktifkan penyedia ini.
19. Tempelkan Client ID dari langkah 12 ke dalam field Client ID.
20. Tempelkan Client Secret dari langkah 12 ke dalam field Client Secret.
21. Klik Save untuk menerapkan konfigurasi.

Hasil yang diharapkan: Tab OAuth menampilkan Google sebagai aktif dengan kredensial Anda yang sudah diisi. Pengaturan dikirimkan ke semua klien yang terhubung.

Bagian C: Uji Alur Login

22. Pergi ke PC klien yang terhubung. Layar idle sekarang seharusnya menampilkan bagian login sosial dengan tombol login Google.
23. Klik tombol login Google di layar idle klien.
24. Klien menampilkan kode QR dan kode pengguna (string alfanumerik pendek).
25. Pindai kode QR dengan ponsel Anda. Kode QR membuka halaman verifikasi perangkat Google.
26. Masuk dengan akun Google dan masukkan kode pengguna saat diminta.
27. Otorisasi aplikasi.

Hasil yang diharapkan: Di server, suara notifikasi diputar dan entri baru muncul di halaman Requests. Permintaan menampilkan nama akun Google, alamat email, dan PC klien yang memulai login.

Cara Menyetujui Permintaan Login

Setiap login OAuth menghasilkan permintaan yang harus disetujui oleh admin atau kasir sebelum pelanggan mendapatkan akses.

1. Ketika permintaan login tiba, suara notifikasi diputar di server dan lencana muncul pada ikon halaman Requests di sidebar.
2. Navigasikan ke halaman Requests.
3. Permintaan yang tertunda menampilkan:
   • Nama penyedia (misalnya, Google).
   • Nama tampilan dari penyedia (misalnya, "Budi Santoso").
   • Alamat email (misalnya, "budi@example.com").
   • PC klien yang memulai permintaan (nama host atau nama tampilan).
   • Stempel waktu.
4. Tinjau detail permintaan. Verifikasi bahwa orang di PC klien sesuai dengan informasi akun.
5. Klik Approve untuk menerima permintaan.

Hasil yang diharapkan: Jika tidak ada akun anggota yang terhubung dengan identitas OAuth ini, akun anggota baru dibuat secara otomatis. Nama tampilan dan email dari penyedia digunakan. Pelanggan masuk dan PC klien beralih dari layar idle ke Online Page. Jika akun anggota sebelumnya sudah terhubung dengan identitas OAuth ini, anggota yang sudah ada langsung masuk.

Tips: Jika permintaan login mencurigakan (misalnya, PC tidak ada orangnya atau permintaan tampak otomatis), klik Reject sebagai gantinya. Pelanggan akan melihat pesan "Akses ditolak" dan dapat mencoba lagi.

Cara Menyiapkan Facebook OAuth

1. Buka Facebook Developer Portal di https://developers.facebook.com .
2. Buat aplikasi baru. Pilih jenis aplikasi Consumer.
3. Navigasikan ke halaman Settings > Basic aplikasi. Catat App ID dan App Secret.
4. Navigasikan ke Add Product dan tambahkan Facebook Login for Devices.
5. Dalam pengaturan Facebook Login for Devices, tambahkan URI pengalihan jika diperlukan oleh portal.
6. Buka HandyCafe Server dan navigasikan ke Settings > OAuth.
7. Temukan baris penyedia Facebook.
8. Aktifkan tombol Facebook.
9. Tempelkan App ID ke dalam field Client ID.
10. Tempelkan App Secret ke dalam field Client Secret.
11. Klik Save.

Hasil yang diharapkan: Facebook muncul sebagai penyedia yang diaktifkan. Layar idle klien menampilkan tombol login Facebook bersama penyedia lain yang diaktifkan.

Cara Menyiapkan Discord OAuth

1. Buka Discord Developer Portal di https://discord.com/developers/applications .
2. Buat aplikasi baru. Beri nama sesuai kafe Anda.
3. Navigasikan ke bagian OAuth2 di sidebar kiri.
4. Salin Client ID dan buat Client Secret. Simpan secret dengan aman karena Discord hanya menampilkannya sekali.
5. Buka HandyCafe Server dan navigasikan ke Settings > OAuth.
6. Temukan baris penyedia Discord (dinonaktifkan secara default).
7. Aktifkan tombol Discord.
8. Tempelkan Client ID ke dalam field Client ID.
9. Tempelkan Client Secret ke dalam field Client Secret.
10. Klik Save.

Hasil yang diharapkan: Discord sekarang tersedia sebagai opsi login di layar idle klien.

Cara Mengizinkan Login Tanpa Kredit

Secara default, HandyCafe mengizinkan pelanggan yang terautentikasi melalui OAuth untuk masuk bahkan jika mereka tidak memiliki saldo dompet atau kredit waktu. Anda dapat mengubah perilaku ini.

1. Navigasikan ke Settings > OAuth.
2. Temukan tombol Allow Login Without Credit.
3. Jika diaktifkan (default), pelanggan yang terautentikasi melalui OAuth dapat masuk terlepas dari saldo mereka. Kasir dapat memulai sesi pascabayar untuk mereka.
4. Jika dinonaktifkan, pelanggan harus memiliki saldo dompet atau kredit waktu untuk masuk. Pelanggan dengan saldo nol akan melihat pesan yang meminta mereka mengunjungi kasir untuk mengisi ulang.
5. Klik Save setelah mengubah tombol.

Hasil yang diharapkan: Perilaku berlaku segera untuk permintaan login baru. Sesi yang sudah ada tidak terpengaruh.

Cara Menghubungkan Identitas OAuth ke Anggota yang Sudah Ada

Jika pelanggan sudah memiliki akun anggota (dibuat secara manual oleh kasir) dan kemudian login melalui OAuth untuk pertama kalinya, proses persetujuan dapat menghubungkan identitas OAuth ke akun yang sudah ada.

1. Ketika permintaan login OAuth tiba di halaman Requests, periksa apakah email cocok dengan anggota yang sudah ada.
2. Jika sistem mendeteksi kecocokan, dialog persetujuan akan menawarkan untuk menghubungkan identitas OAuth ke anggota yang sudah ada sebagai ganti membuat akun baru.
3. Setujui permintaan dengan opsi tautan yang dipilih.

Hasil yang diharapkan: Akun anggota yang sudah ada mendapatkan tautan OAuth. Login di masa mendatang dari penyedia ini akan melewati langkah persetujuan dan langsung masuk ke anggota (setelah persetujuan pertama).

Kesalahan Umum yang Harus Dihindari

• Menggunakan jenis klien OAuth yang salah di Google Cloud Console. Anda harus memilih "TVs and Limited Input devices" saat membuat OAuth client ID. Jika Anda memilih "Web application" atau "Desktop app," alur otorisasi perangkat tidak akan berfungsi dan klien akan gagal mendapatkan kode perangkat.
• Lupa mengaktifkan tombol OAuth global. Mengaktifkan penyedia individual saja tidak cukup. Tombol OAuth utama di bagian atas halaman pengaturan OAuth juga harus aktif.
• Tidak menyetujui permintaan login. Login OAuth memerlukan persetujuan eksplisit dari server. Jika tidak ada yang memantau halaman Requests, pelanggan akan menunggu tanpa batas di layar idle. Pertimbangkan menugaskan kasir untuk memantau permintaan selama jam sibuk.
• Membiarkan kode perangkat kedaluwarsa. Kode perangkat memiliki waktu hidup terbatas (biasanya 5-10 menit). Jika pelanggan terlalu lama memindai kode QR dan melakukan autentikasi, kode akan kedaluwarsa dan mereka harus mulai dari awal. Sarankan pelanggan untuk segera memindai.
• Menempelkan kredensial dengan spasi ekstra. Saat menyalin Client ID atau Client Secret dari konsol penyedia, pastikan tidak ada spasi di awal atau akhir yang disertakan. Spasi ekstra akan menyebabkan kegagalan autentikasi.
• Lupa mempublikasikan aplikasi Google OAuth. Aplikasi Google dalam mode "Testing" hanya mengizinkan sejumlah terbatas pengguna uji. Untuk mengizinkan pelanggan mana pun masuk, Anda harus mempublikasikan aplikasi melalui halaman OAuth consent screen dan menyelesaikan langkah verifikasi yang diperlukan.
• Menukar Client ID dan Client Secret. Keduanya adalah dua nilai yang berbeda. Client ID bersifat publik. Client Secret harus dijaga kerahasiaannya. Menukarnya akan menyebabkan kegagalan autentikasi.
• Tidak mengonfigurasi nama kafe. Nama kafe dari pengaturan HandyCafe Anda ditampilkan di layar idle klien selama alur OAuth. Nama yang kosong atau default terlihat tidak profesional. Atur nama kafe Anda di Settings > General sebelum mengaktifkan OAuth.