Paano I-set Up ang OAuth Social Login

Itinuturo ng gabay na ito kung paano i-configure ang social login para makakag-sign in ang mga customer sa mga client PC gamit ang kanilang Google, Facebook, Apple, X, o Discord account. Gumagamit ang HandyCafe ng Device Authorization Grant flow (RFC 8628), na dinisenyo para sa mga device na walang buong browser. Ini-scan ng mga customer ang isang QR code gamit ang kanilang telepono para ma-authenticate.

Kakailanganin Mo

• Admin access sa HandyCafe Server.
• Isang Google Cloud Console account (para sa Google OAuth) o katumbas na developer portal access para sa ibang provider.
• Ang HandyCafe Server na tumatakbo at naa-access sa iyong network.
• Hindi bababa sa isang nakakonektang client PC para subukan ang login flow.

Paano Gumagana ang OAuth Device Flow sa HandyCafe

Bago sumisid sa setup, narito ang buod ng flow:

1. Isang customer sa isang idle client PC ay nag-click ng social login button (hal., "Sign in with Google").
2. Nagpapadala ang client ng OAuth start request sa server.
3. Nakikipag-ugnayan ang server sa device authorization endpoint ng provider at nakatanggap ng device code, user code, at verification URL.
4. Ipinapakita ng client ang isang QR code at user code sa idle screen.
5. Inis-scan ng customer ang QR code gamit ang kanilang telepono at nag-a-authenticate sa provider.
6. Nagpo-poll ang server sa provider hanggang matagumpay ang authentication.
7. Ang server ay gumagawa ng OAuth Login Request na lilitaw sa Requests na pahina.
8. Isang admin o cashier ang nag-a-approve ng request.
9. Isang bagong member account ay nililikha (o isang existing na account ay naka-link) at ang customer ay naka-log in.

Paano Mag-set Up ng Google OAuth

Ang Google ang pinaka-karaniwang ginagamit na provider. Sinasaklaw ng seksyong ito ang bawat hakbang mula sa paglikha ng Google Cloud project hanggang sa pag-test ng unang login.

Bahagi A: Gumawa ng Google Cloud Credentials

1. Buksan ang Google Cloud Console sa https://console.cloud.google.com sa iyong browser.
2. Gumawa ng bagong project o pumili ng existing. Pangalanan ito ng isang makilalang pangalan tulad ng "HandyCafe OAuth."
3. Pumunta sa APIs & Services > OAuth consent screen.
4. Piliin ang External bilang uri ng user (maliban kung mayroon kang Google Workspace organization at gusto mong internal lamang).
5. Punan ang mga kinakailangang field: App name ("Pangalan ng Iyong Cafe"), User support email, at Developer contact email.
6. I-click ang Save and Continue sa mga seksyon ng Scopes at Test Users. Hindi mo kailangang magdagdag ng espesyal na mga saklaw. Ang mga default na email at profile na saklaw ay sapat na.
7. Pumunta sa APIs & Services > Credentials.
8. I-click ang Create Credentials > OAuth client ID.
9. Para sa Application type, piliin ang TVs and Limited Input devices. Ito ay kritikal. Gumagamit ang HandyCafe ng device authorization grant flow, na nangangailangan ng partikular na uri ng client na ito.
10. Maglagay ng pangalan para sa client (hal., "HandyCafe Device Flow").
11. I-click ang Create.
12. Kopyahin ang Client ID at Client Secret mula sa confirmation dialog. Itago ang mga ito nang ligtas. Kakailanganin mo ang parehong halaga sa susunod na seksyon.

Bahagi B: I-configure ang HandyCafe Server

13. Buksan ang HandyCafe Server application.
14. Pumunta sa Settings gamit ang gear icon sa kaliwang sidebar.
15. Piliin ang OAuth tab.
16. I-enable ang OAuth toggle sa itaas ng pahina. Globally na ino-enable nito ang social login sa lahat ng client PC.
17. Hanapin ang Google provider row sa listahan ng mga provider.
18. I-enable ang Google toggle para i-activate ang provider na ito.
19. I-paste ang iyong Client ID mula sa hakbang 12 sa Client ID field.
20. I-paste ang iyong Client Secret mula sa hakbang 12 sa Client Secret field.
21. I-click ang Save para i-apply ang configuration.

Inaasahang resulta: Ipinapakita ng OAuth tab ang Google bilang naka-enable na may iyong mga credential na napuno. Ang mga setting ay ipinapadala sa lahat ng nakakonektang client.

Bahagi C: Subukan ang Login Flow

22. Pumunta sa isang nakakonektang client PC. Dapat na ngayon ay nagpapakita ang idle screen ng isang social login na seksyon na may Google login button.
23. I-click ang Google login button sa client idle screen.
24. Ipinapakita ng client ang isang QR code at user code (isang maikling alphanumeric string).
25. I-scan ang QR code gamit ang iyong telepono. Nagbubukas ito ng device verification na pahina ng Google.
26. Mag-sign in gamit ang isang Google account at ilagay ang user code kapag tinanong.
27. I-authorize ang application.

Inaasahang resulta: Sa server, isang notification na tunog ang tumatunog at isang bagong entry ay lilitaw sa Requests na pahina. Ipinapakita ng request ang pangalan ng Google account, email address, at ang client PC na nagpasimula ng login.

Paano Mag-approve ng Login Request

Ang bawat OAuth login ay gumagawa ng request na dapat na aprubahan ng isang admin o cashier bago makakuha ng access ang customer.

1. Kapag dumating ang isang login request, isang notification na tunog ang tumatunog sa server at isang badge ay lilitaw sa Requests page icon sa sidebar.
2. Pumunta sa Requests na pahina.
3. Ipinapakita ng pending request ang:
   • Pangalan ng provider (hal., Google).
   • Display name mula sa provider (hal., "Juan dela Cruz").
   • Email address (hal., "juan@example.com").
   • Ang client PC na nagpasimula ng request (hostname o display name).
   • Timestamp.
4. Suriin ang mga detalye ng request. I-verify na ang taong nasa client PC ay tumutugma sa impormasyon ng account.
5. I-click ang Approve para tanggapin ang request.

Inaasahang resulta: Kung walang existing na member account na naka-link sa OAuth identity na ito, nabuo nililikha ang isang bagong member account. Ang display name at email mula sa provider ay ginagamit. Ang customer ay naka-log in at ang client PC ay lumilipat mula sa idle screen papunta sa Online Page. Kung ang isang member account ay nakikipag-date na naka-link sa OAuth identity na ito, ang existing na member ay nagpadala ng naka-log in.

Tip: Kung ang login request ay kahina-hinala (hal., ang PC ay walang tao o mukhang automated ang request), i-click ang Reject sa halip. Makakakita ang customer ng mensaheng "Access denied" at maaari silang subukan muli.

Paano Mag-set Up ng Facebook OAuth

1. Buksan ang Facebook Developer Portal sa https://developers.facebook.com .
2. Gumawa ng bagong app. Piliin ang Consumer app type.
3. Pumunta sa Settings > Basic na pahina ng app. Tandaan ang App ID at App Secret.
4. Pumunta sa Add Product at idagdag ang Facebook Login for Devices.
5. Sa mga setting ng Facebook Login for Devices, idagdag ang iyong mga redirect URI kung kinakailangan ng portal.
6. Buksan ang HandyCafe Server at pumunta sa Settings > OAuth.
7. Hanapin ang Facebook provider row.
8. I-enable ang Facebook toggle.
9. I-paste ang App ID sa Client ID field.
10. I-paste ang App Secret sa Client Secret field.
11. I-click ang Save.

Inaasahang resulta: Ang Facebook ay lilitaw bilang isang naka-enable na provider. Ang mga client idle screen ay nagpapakita ng Facebook login button kasabay ng anumang iba pang naka-enable na provider.

Paano Mag-set Up ng Discord OAuth

1. Buksan ang Discord Developer Portal sa https://discord.com/developers/applications .
2. Gumawa ng bagong application. Pangalanan ito pagkatapos ng iyong cafe.
3. Pumunta sa OAuth2 na seksyon sa kaliwang sidebar.
4. Kopyahin ang Client ID at gumawa ng Client Secret. Itago nang ligtas ang secret dahil ipinapakita lamang ito ng Discord nang isang beses.
5. Buksan ang HandyCafe Server at pumunta sa Settings > OAuth.
6. Hanapin ang Discord provider row (ito ay naka-disable bilang default).
7. I-enable ang Discord toggle.
8. I-paste ang Client ID sa Client ID field.
9. I-paste ang Client Secret sa Client Secret field.
10. I-click ang Save.

Inaasahang resulta: Ang Discord ay available na ngayon bilang isang opsyon sa login sa mga client idle screen.

Paano Pahintulutan ang Login Nang Walang Credit

Bilang default, pinapahintulutan ng HandyCafe ang mga OAuth-authenticated na customer na mag-log in kahit walang wallet balance o time credit. Maaari mong baguhin ang gawi na ito.

1. Pumunta sa Settings > OAuth.
2. Hanapin ang Allow Login Without Credit toggle.
3. Kung naka-enable (default), ang mga customer na nag-authenticate sa pamamagitan ng OAuth ay maaaring mag-log in sa kanilang balanse. Maaaring magsimula ng postpaid session para sa kanila ang isang cashier.
4. Kung naka-disable, ang mga customer ay dapat magkaroon ng alinman sa wallet balance o time credit para mag-log in. Ang mga customer na may zero balance ay makakakita ng mensaheng nagsasabi sa kanila na bisitahin ang cashier para mag-top up.
5. I-click ang Save pagkatapos baguhin ang toggle.

Inaasahang resulta: Ang gawi ay kaagad na magkakabisa para sa mga bagong login request. Ang mga existing na session ay hindi apektado.

Paano Mag-link ng OAuth Identity sa isang Existing na Member

Kung ang isang customer ay mayroon nang member account (manu-manong ginawa ng cashier) at pagkatapos ay nag-log in sa pamamagitan ng OAuth sa unang pagkakataon, maaaring i-link ng approval process ang OAuth identity sa kanilang existing account.

1. Kapag dumating ang OAuth login request sa Requests na pahina, suriin kung tumutugma ang email sa isang existing na member.
2. Kung matukoy ng system ang isang tugma, ang approval dialog ay mag-aalok na i-link ang OAuth identity sa existing na member sa halip na gumawa ng bagong account.
3. I-approve ang request na may napiling link na opsyon.

Inaasahang resulta: Ang existing na member account ay nakakakuha ng OAuth link. Ang mga susunod na login mula sa provider na ito ay lalampas sa hakbang ng approval at magpapadala ng mag-lo-log in member (pagkatapos ng unang approval).

Mga Karaniwang Mali na Dapat Iwasan

• Paggamit ng maling uri ng OAuth client sa Google Cloud Console. Kailangan mong piliin ang "TVs and Limited Input devices" kapag gumagawa ng OAuth client ID. Kung pipiliin mo ang "Web application" o "Desktop app," ang device authorization flow ay hindi gagana at ang client ay mabibigo na makakuha ng device code.
• Pagkalimot na i-enable ang global OAuth toggle. Hindi sapat ang pag-enable ng mga indibidwal na provider. Ang master OAuth toggle sa itaas ng OAuth settings na pahina ay dapat ding naka-on.
• Hindi pag-approve ng mga login request. Ang mga OAuth login ay nangangailangan ng tahasang approval mula sa server. Kung walang nagmamasid sa Requests na pahina, magaabang nang walang hanggan ang mga customer sa idle screen. Isaalang-alang ang pag-assign ng cashier para subaybayan ang mga request sa panahon ng abala.
• Pagpapahintulot na mag-expire ang mga device code. Ang mga device code ay may limitadong buhay (karaniwang 5-10 minuto). Kung masyadong matagal ang customer bago ini-scan ang QR code at nag-authenticate, mag-e-expire ang code at kailangan nilang magsimula muli. Savahan ang mga customer na agad na mag-scan.
• Pag-paste ng mga credential na may dagdag na whitespace. Kapag kinokopya ang Client ID o Client Secret mula sa provider console, tiyaking walang mga nangungunang o sinusundan na espasyo. Ang dagdag na whitespace ay magdudulot ng authentication failure.
• Pagkalimot na i-publish ang Google OAuth app. Ang mga Google app sa mode na "Testing" ay nagpapahintulot lamang ng limitadong bilang ng mga test user. Para pahintulutan ang anumang customer na mag-log in, kailangan mong i-publish ang app sa pamamagitan ng OAuth consent screen na pahina at kumpletuhin ang anumang kinakailangang hakbang ng pag-verify.
• Pagpapalitan ng Client ID at Client Secret. Ang dalawa ay magkaibang halaga. Ang Client ID ay pampubliko. Ang Client Secret ay dapat itago nang kompidensyal. Ang pagpapalitan ng mga ito ay magdudulot ng authentication failure.
• Hindi pag-configure ng pangalan ng cafe. Ang pangalan ng cafe mula sa iyong mga HandyCafe setting ay ipinapakita sa client idle screen sa panahon ng OAuth flow. Ang isang blangko o default na pangalan ay mukhang hindi propesyonal. Itakda ang pangalan ng iyong cafe sa Settings > General bago i-enable ang OAuth.