OAuthソーシャルログインの設定方法
このガイドでは、顧客がGoogle、Facebook、Apple、X、DiscordのアカウントでクライアントPCにサインインできるようにソーシャルログインを設定する方法を説明します。HandyCafeはDevice Authorization Grantフロー（RFC 8628）を使用しており、フルブラウザーのないデバイス向けに設計されています。顧客はスマートフォンでQRコードをスキャンして認証します。
必要なもの
- HandyCafe Serverへの管理者アクセス権。
- Google Cloud Consoleアカウント（Google OAuthの場合）または他のプロバイダーの同等の開発者ポータルアクセス。
- HandyCafe Serverがネットワーク上で起動してアクセス可能であること。
- ログインフローをテストするために少なくとも1台の接続されたクライアントPC。
HandyCafeでOAuthデバイスフローがどのように機能するか
設定に入る前に、フローの概要を説明します：
- アイドル状態のクライアントPCの顧客がソーシャルログインボタン（例：「Googleでサインイン」）をクリックします。
- クライアントはOAuth開始リクエストをサーバーに送信します。
- サーバーはプロバイダーのデバイス認証エンドポイントに接続し、デバイスコード、ユーザーコード、確認URLを受け取ります。
- クライアントはアイドル画面にQRコードとユーザーコードを表示します。
- 顧客はスマートフォンでQRコードをスキャンしてプロバイダーで認証します。
- サーバーは認証が完了するまでプロバイダーをポーリングします。
- サーバーはリクエストページに表示されるOAuthログインリクエストを作成します。
- 管理者またはキャッシャーがリクエストを承認します。
- 新しいメンバーアカウントが作成（または既存のアカウントにリンク）され、顧客がログインします。
Google OAuthの設定方法
Googleは最もよく使われるプロバイダーです。このセクションでは、Google Cloudプロジェクトの作成から最初のログインのテストまでのすべての手順を説明します。
パートA：Google Cloud認証情報の作成
- ブラウザーでGoogle Cloud Console（https://console.cloud.google.com）を開きます。
- 新しいプロジェクトを作成するか、既存のプロジェクトを選択します。「HandyCafe OAuth」など認識できる名前を付けます。
- APIs & Services > OAuthの同意画面に移動します。
- ユーザータイプとして外部を選択します（Google Workspaceの組織があって内部のみにしたい場合を除く）。
- 必須フィールドを入力します：アプリ名（「あなたのカフェ名」）、ユーザーサポートメールアドレス、開発者連絡先メールアドレス。
- スコープとテストユーザーのセクションを保存して続行してください。特別なスコープを追加する必要はありません。デフォルトのメールとプロフィールのスコープで十分です。
- APIs & Services > 認証情報に移動します。
- 認証情報を作成 > 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ログインボタンをクリックします。
- クライアントにQRコードとユーザーコード（短い英数字の文字列）が表示されます。
- スマートフォンでQRコードをスキャンします。Googleのデバイス確認ページが開きます。
- Googleアカウントでサインインし、プロンプトが表示されたらユーザーコードを入力します。
- アプリケーションを認証します。
期待される結果: サーバーで通知音が再生され、リクエストページに新しいエントリが表示されます。リクエストにはGoogleアカウント名、メールアドレス、ログインを開始したクライアントPCが表示されます。
ログインリクエストの承認方法
すべてのOAuthログインは、顧客がアクセスできるようになる前に管理者またはキャッシャーによる承認が必要なリクエストを生成します。
- ログインリクエストが届くと、サーバーで通知音が再生され、サイドバーのリクエストページアイコンにバッジが表示されます。
- リクエストページに移動します。
- 保留中のリクエストには以下が表示されます：
- プロバイダー名（例：Google）。
- プロバイダーの表示名（例：「田中太郎」）。
- メールアドレス（例：「tanaka@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は1回しか表示しないため、シークレットを安全に保管してください。
- HandyCafe Serverを開き、設定 > OAuthに移動します。
- Discordプロバイダー行を確認します（デフォルトで無効になっています）。
- Discordトグルを有効にします。
- クライアントIDをクライアントIDフィールドに貼り付けます。
- クライアントシークレットをクライアントシークレットフィールドに貼り付けます。
- 保存をクリックします。
期待される結果: クライアントのアイドル画面でDiscordがログインオプションとして利用できるようになります。
クレジットなしでのログインを許可する方法
デフォルトでは、HandyCafeはOAuth認証された顧客がウォレット残高やタイムクレジットがなくてもログインできるようにします。この動作を変更できます。
- 設定 > OAuthに移動します。
- クレジットなしでのログインを許可トグルを確認します。
- 有効（デフォルト）の場合、OAuth経由で認証された顧客は残高に関係なくログインできます。キャッシャーは後払いセッションを開始できます。
- 無効の場合、顧客はログインするためにウォレット残高またはタイムクレジットのいずれかが必要です。残高がゼロの顧客には、チャージするためにキャッシャーに行くよう促すメッセージが表示されます。
- トグルを変更した後、保存をクリックします。
期待される結果: 動作は新しいログインリクエストに即座に反映されます。既存のセッションには影響しません。
OAuthアイデンティティを既存のメンバーにリンクする方法
顧客にすでにメンバーアカウント（キャッシャーが手動で作成した）がある場合で、初めてOAuthでログインした際に、承認プロセスはOAuthアイデンティティを既存のアカウントにリンクできます。
- リクエストページにOAuthログインリクエストが届いたら、メールアドレスが既存のメンバーと一致するか確認します。
- システムが一致を検出した場合、承認ダイアログは新しいアカウントを作成する代わりに、OAuthアイデンティティを既存のメンバーにリンクするオプションを提供します。
- リンクオプションを選択した状態でリクエストを承認します。
期待される結果: 既存のメンバーアカウントにOAuthリンクが追加されます。このプロバイダーからの将来のログインは承認ステップをバイパスし、メンバーを直接ログインさせます（最初の承認後）。
よくある間違いと対策
- Google Cloud ConsoleでOAuthクライアント種別を間違える。 OAuthクライアントIDを作成する際は「テレビと入力が制限されたデバイス」を選択する必要があります。「ウェブアプリケーション」や「デスクトップアプリ」を選択すると、デバイス認証フローが機能せず、クライアントはデバイスコードを取得できません。
- グローバルOAuthトグルの有効化を忘れる。 個々のプロバイダーを有効にするだけでは不十分です。OAuthの設定ページの上部にあるマスターOAuthトグルもオンにする必要があります。
- ログインリクエストを承認しない。 OAuthログインはサーバーからの明示的な承認が必要です。リクエストページを誰も監視していない場合、顧客はアイドル画面で無期限に待つことになります。繁忙期はリクエストを監視するキャッシャーを割り当てることを検討してください。
- デバイスコードを有効期限切れにする。 デバイスコードには有効期間が限られています（通常5〜10分）。顧客がQRコードをスキャンして認証するのに時間がかかりすぎると、コードが期限切れになり最初からやり直す必要があります。顧客にすぐにスキャンするよう伝えてください。
- 余分な空白を含む認証情報を貼り付ける。 プロバイダーコンソールからクライアントIDまたはクライアントシークレットをコピーする際は、前後に空白が含まれていないことを確認してください。余分な空白は認証エラーを引き起こします。
- Google OAuthアプリの公開を忘れる。 「テスト」モードのGoogleアプリは、限られた数のテストユーザーしか許可しません。すべての顧客がログインできるようにするには、OAuthの同意画面ページからアプリを公開し、必要な確認手順を完了する必要があります。
- クライアントIDとクライアントシークレットを取り違える。 これらは2つの異なる値です。クライアントIDは公開されています。クライアントシークレットは機密に保つ必要があります。取り違えると認証エラーが発生します。
- カフェ名を設定しない。 HandyCafe設定のカフェ名はOAuthフロー中にクライアントのアイドル画面に表示されます。空白またはデフォルト名は見栄えが悪いです。OAuthを有効にする前に設定 > 一般でカフェ名を設定してください。