roblox-oauth

roblox-oauth

使用する場面

主に Roblox Open Cloud の OAuth 2.0 委任認可に関するタスクでは、このスキルを使用します。

• Creator Dashboard で OAuth アプリを登録または設定する。
• confidential クライアントと public クライアントの実装を選択する。
• 認可コードフローを構築する。特に PKCE を使用する場合。
• 認可 URL を作成し、リダイレクトコールバックを処理する。
• 認可コードの交換、トークンの更新、トークンのイントロスペクション、またはセッションの取り消しを行う。
• ユーザー認可型の統合に必要な最小限の OAuth スコープを選択する。
• ユーザーの同意後に、トークンがアクセスできるリソースを検証する。
• OAuth テスト用に localhost またはサンプルアプリ形式の開発環境を設定する。
• OAuth 固有のエラー、リダイレクトの不一致、トークンの誤用、またはスコープの失敗をデバッグする。

タスクの主な内容が次の場合は、このスキルを使用しないでください。

• 一般的な Open Cloud リクエストの構築、API キー、webhook、または OAuth を使用しないクラウド自動化。
• エクスペリエンス内のスクリプトアーキテクチャ、リモート、レプリケーション、またはゲームプレイコード。
• DataStore または MemoryStore の設計。

判断基準

• サーバー所有の API キーではなく、ユーザーまたはクリエイターが許可する委任アクセスが必要な統合には、このスキルを使用します。
• すべてのクライアントで PKCE を使用する認可コードフローを優先し、public クライアントでは PKCE を必須とします。
• ブラウザーアプリとモバイルアプリは、クライアントシークレットを安全に保持できない public クライアントとして扱います。
• セキュアなバックエンドを備えたアプリは confidential クライアントとして扱い、クライアントシークレットはサーバー側だけに保持します。
• アプリの実際の機能に必要な最小限のスコープを要求します。
• アプリで ID トークンが必要な場合は openid を追加し、プロファイルのクレームが本当に必要な場合に限り profile を追加します。
• タスクが OAuth の仕組みではなく、エンドポイントの選択、リクエストの構成、レート制限、または webhook に移った場合は、roblox-cloud に引き継ぎます。
• タスクがエクスペリエンス内のランタイムアーキテクチャや永続化の設計に移った場合は、適切な Roblox スキルに引き継ぎます。
• リクエストに OAuth と対象外のアーキテクチャが混在する場合は、OAuth の部分だけを回答し、それ以外は明示的に対象外とします。

手順

1. OAuth のユースケースを確認します：
   • ユーザーまたは作成者の委任による Open Cloud リソースへのアクセス。
   • アプリの種類：confidential または public。
   • API アクセスに加えて、本人確認が必要かどうか。
2. アプリの設定を登録または確認します：
   • アプリの登録と公開が必要な場合、開発者の本人確認が済んでいることを確認します。
   • client ID を記録します。
   • アプリが confidential の場合は、Roblox では一度しか表示されないため、client secret をすぐに安全な場所へ保存します。
   • 必要なスコープのみを追加します。
   • 本番環境とローカル開発環境の正確なリダイレクト URL を追加します。
3. コーディングの前にフローを設計します：
   • 認可コードフローを使用します。
   • すべてのクライアントで PKCE を使用します。public クライアントでは必須です。
   • 認可を試行するたびに、新しい高エントロピーの state を生成します。
   • 認可を試行するたびに、新しい code_verifier と code_challenge を生成します。
   • OIDC の本人確認が関係する場合は nonce を使用します。
4. 認可リクエストを正しく構築します：
   • ユーザーを https://apis.roblox.com/oauth/v1/authorize に遷移させます。
   • client_id、redirect_uri、scope、および response_type=code を含めます。
   • PKCE では code_challenge と code_challenge_method=S256 を含めます。
   • confidential クライアントのシークレットをブラウザーやモバイルのコードに公開しないでください。
5. コールバックを慎重に処理します：
   • code を使用する前に、返された state を検証します。
   • 成功時のクエリパラメーター（code）と失敗時のクエリパラメーター（error、error_description）の両方を処理します。
   • 認可コードの有効期間は短く、一度しか使用できないものとして扱います。
6. POST /oauth/v1/token でコードをトークンに交換します：
   • application/x-www-form-urlencoded を使用します。
   • code、client ID、grant type、および code_verifier または confidential クライアントの認証情報を送信します。
   • リフレッシュトークンは、信頼できるサーバー側のシステムにのみ保存します。
7. トークンのライフサイクルを明示的に管理します：
   • アクセストークンの有効期間は約15分です。
   • リフレッシュトークンの有効期間は約90日で、リフレッシュ時に一度だけ使用できます。
   • リフレッシュが成功するたびに、保存済みのリフレッシュトークンをアトミックに置き換えます。
   • アプリを切断する際は、POST /oauth/v1/token/revoke でセッションを取り消します。
8. トークンで実際にできることを検証します：
   • ID クレームには GET /oauth/v1/userinfo を使用します。
   • ユーザーが許可したリソースレベルのアクセスをアプリで確認する必要がある場合は、POST /oauth/v1/token/resources を使用します。
   • POST /oauth/v1/token/introspect はトークンの有効性とクレームの確認にのみ使用します。リソースへの認可確認の代わりにはなりません。
9. スコープとリスクを必要最小限に抑えます：
   • 実際に使用するエンドポイントとリソースの所有権の要件に合わせてスコープを選びます。
   • 設計とレビューでは、medium、high、critical のエンドポイントカテゴリを、最小権限に関する警告の目安として扱います。
   • スキルの範囲を一般的な Open Cloud エンドポイントの実装に広げないでください。
10. 回答の範囲を守ります：

• アプリ登録、認証フローの設計、トークン、スコープ、ローカル開発、および OAuth 固有のエラーに焦点を当てます。
• API キーを優先するクラウド統合、ゲームプレイアーキテクチャ、データサービスの設計に話題を広げないでください。

リファレンスの活用

• 役割、グラントタイプの選択、OIDC の基本については、まず references/oauth-overview.md を開いてください。
• Creator Dashboard の設定、リダイレクト URL のルール、プライベートモードの制限、アプリの審査については、references/oauth-registration.md を開いてください。
• PKCE、認可 URL、コールバック処理、トークンの保存を実装する場合は、references/oauth-development-guide.md を開いてください。
• OAuth エンドポイントの正確な情報、トークンの有効期間、トークン検証ヘルパー、ディスカバリーメタデータについては、references/oauth-reference.md を開いてください。
• localhost の設定、環境変数のパターン、サンプルアプリでのフローの組み立て方については、references/oauth-sample-app.md を開いてください。
• アプリの動作に必要な最小限のスコープを判断する場合は、references/scopes-reference.md を開いてください。
• 強力なスコープをリクエストする前に、エンドポイントの機密性を評価する必要がある場合は、references/risk-level-reference.md を開いてください。
• Open Cloud のエラーパターンに照らして OAuth やトークン関連の障害を調査する場合は、references/cloud-auth-related-error-guidance.md を開いてください。

チェックリスト

• このタスクでは、API キーによる自動化ではなく、委任された OAuth アクセスが実際に必要です。
• クライアントは、機密クライアントかパブリッククライアントか正しく分類されています。
• PKCE が含まれています。パブリッククライアントが PKCE を省略しようとする場合は、その設計を却下します。
• リダイレクト URL は完全一致し、想定する環境に対して有効です。
• リクエストするスコープは最小限で、インテグレーションの実際の動作に合致しています。
• openid は、ID データまたは ID トークンが必要な場合に限り含めます。
• state は生成、保存され、コールバック時に検証されます。
• 認可コードは速やかに、一度だけ交換されます。
• アクセストークンとリフレッシュトークンは、信頼できないクライアントに保存されません。
• リフレッシュ後に保存済みのリフレッシュトークンを置き換えることで、リフレッシュトークンのローテーションに対応します。
• アプリは userinfo、introspect、token/resources を、それぞれ異なる目的で使用します。
• ガイダンスの範囲は、一般的な Open Cloud リクエストの仕組み、ゲームプレイのスクリプト作成、データアーキテクチャには及びません。

よくある間違い

• まず認証モデルを選ばず、API キーと OAuth を同じものとして扱うこと。
• 機密クライアントのシークレットをフロントエンドやモバイルのコードに含めること。
• 特にパブリッククライアントで PKCE を省略すること。
• コールバック時の state の検証を忘れること。
• リフレッシュトークンは、リフレッシュ成功後も複数回再利用できると思い込むこと。
• 認可コードの有効期間が短く、一度しか使用できないことを忘れること。
• openid なしで profile をリクエストすること。
• 開発中に、必要最小限のスコープではなく広範なスコープをリクエストすること。
• トークンのイントロスペクションによって、リソースの所有権や同意済みのリソース範囲が証明されると思い込むこと。
• ユーザーの再認可なしにスコープを追加または変更すること。
• OAuth 以外の Open Cloud の問題をこのスキルの範囲として扱い、roblox-cloud に引き継がないこと。

例

パブリックなウェブアプリまたはモバイルアプリ

• PKCE を使用した認可コードフローを使用します。
• すべてのシークレットをクライアントに保存しないでください。
• state を検証し、可能であれば信頼できるバックエンドでコードを交換して、リフレッシュトークンを安全に保存します。

機密サーバーアプリ

• アプリを登録し、シークレットを一度だけ保存し、PKCE も使用します。
• サーバーでコードの交換、トークンのリフレッシュ、ベアラートークンを使った Open Cloud の呼び出しを行います。

ローカル開発

• リダイレクト URL として http://localhost:<port>/oauth/callback を追加します。
• クライアント ID とシークレットを環境変数に保存します。
• 追加のスコープをリクエストしたり審査を申請したりする前に、ログイン、コールバック、トークン交換、リフレッシュ、ログアウトまたは取り消しの一連の流れをテストします。