OAuth と Google でログインによるリンクの簡素化

概要

OAuth ベースの Google でログインの簡素化されたリンクは、OAuth リンクの上層に Google でログインを追加します。これにより、Google ユーザーにシームレスなリンク エクスペリエンスを提供し、アカウントの作成も可能になります。ユーザーは Google アカウントを使用してサービスに新しいアカウントを作成できます。

OAuth と Google でログインを使用してアカウント リンクを行うには、次の一般的な手順に従います。

1. まず、ユーザーの Google プロフィールにアクセスすることについてユーザーに同意を求めます。
2. プロフィールの情報を使用して、ユーザー アカウントが存在するかどうかを確認します。
3. 既存のユーザーの場合は、アカウントをリンクします。
4. 認証システムで Google ユーザーに一致するユーザーが見つからない場合は、Google から受け取った ID トークンを検証します。その後、ID トークンに含まれているプロフィール情報に基づいてユーザー アカウントを作成できます。

図 1. ユーザーのスマートフォンでの簡素化されたリンクによるアカウント リンク

簡素化されたリンク: OAuth + 「Google でログイン」フロー

次のシーケンス図は、Streamlined Linking におけるユーザー、Google、トークン交換エンドポイント間のインタラクションの詳細を示しています。

役割と責任

次の表に、Streamlined Linking フローにおけるアクターの役割と責任を定義します。

アクター / コンポーネント	GAL ロール	責任
Google アプリ / サーバー	OAuth クライアント	Google でログインのユーザーの同意を取得し、ID アサーション（JWT）をサーバーに渡し、結果のトークンを安全に保存します。
トークン交換エンドポイント	ID プロバイダ / 認可サーバー	ID アサーションを検証し、既存のアカウントを確認し、アカウント リンク インテント（check、get、create）を処理し、リクエストされたインテントに基づいてトークンを発行します。
サービス API	リソース サーバー	有効なアクセス トークンが提示された場合にユーザーデータへのアクセスを提供します。

簡素化されたリンクの要件

• 基本的な OAuth リンクフローを実装します。サービスは、OAuth 2.0 準拠の認証エンドポイントとトークン交換エンドポイントをサポートする必要があります。
• トークン交換エンドポイントは、JSON Web Token（JWT）アサーションをサポートし、check、create、get インテントを実装する必要があります。

• Google API クライアント ID を登録します。

簡素化されたリンクの決定ロジック

次のロジックは、簡略化されたリンクフローでインテントが呼び出される方法を決定します。

1. ユーザーが認証システムにアカウントを持っているかどうか。（ユーザーが [はい] または [いいえ] を選択して決定します）
   1. はい : ユーザーは Google アカウントに関連付けられているメールアドレスを使用してプラットフォームにログインしますか？（ユーザーが [はい] または [いいえ] を選択して決定します）
      1. YES : 認証システムに一致するアカウントがユーザーにありますか？（確認のために check intent が呼び出されます）
         1. YES : get intent が呼び出され、インテントの取得が成功した場合、アカウントがリンクされます。
         2. いいえ : 新しいアカウントを作成しますか？（ユーザーが [はい] または [いいえ] を選択して決定します）
            1. YES : create intent が呼び出され、作成インテントが正常に返された場合、アカウントがリンクされます。
            2. いいえ : OAuth リンクフローがトリガーされ、ユーザーはブラウザにリダイレクトされます。ユーザーは別のメールアドレスでリンクするオプションを選択できます。
      2. いいえ : OAuth リンクフローがトリガーされ、ユーザーはブラウザにリダイレクトされ、別のメールアドレスでリンクするオプションが表示されます。
   2. NO : 認証システムに一致するアカウントがユーザーにありますか？（確認のために check intent が呼び出されます）
      1. YES : get intent が呼び出され、インテントの取得が成功した場合、アカウントがリンクされます。
      2. NO : 作成インテントが正常に返された場合、create intent が呼び出され、アカウントがリンクされます。

実装レシピ

トークン交換エンドポイントでは、Streamlined Linking をサポートするために check、get、create インテントを実装する必要があります。

さまざまなインテントを処理する手順は次のとおりです。

检查现有用户账号（检查 intent）

Google 会调用您的令牌交换端点，以验证 Google 用户是否存在于您的系统中。如需了解参数详情，请参阅简化的关联 intent。

实现方案

如需处理 check intent，请执行以下操作：

1. 验证请求：

   • 验证 client_id、client_secret 和 grant_type（必须为 urn:ietf:params:oauth:grant-type:jwt-bearer）。
   • 使用 JWT 验证 中的条件验证 assertion (JWT)。

2. 查找用户：

   • 检查 JWT 中的 Google 账号 ID (sub) 或电子邮件地址是否与数据库中的用户匹配。

3. 回应：

   • 如果找到：返回 HTTP 200 OK，并附带 {"account_found": "true"}。
   • 如果未找到：返回 HTTP 404 Not Found，并附带 {"account_found": "false"}。

Handle automatic linking (get intent)

If the account exists, Google calls your endpoint with intent=get to retrieve tokens. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the get intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type.
   • Validate the assertion (JWT).

2. Lookup user:

   • Verify the user exists using the sub or email claim.

3. Respond:

   • If successful: Generate and return access_token, refresh_token, and expires_in in a JSON response (HTTP 200 OK).
   • If linking fails: Return HTTP 401 Unauthorized with {"error": "linking_error"} and an optional login_hint to fall back to standard OAuth linking.

使用“使用 Google 账号登录”功能处理账号创建事宜（创建 intent）

如果不存在任何账号，Google 会使用 intent=create 调用您的端点，以创建新用户。如需了解参数详情，请参阅 Streamlined Linking Intents。

实现方案

如需处理 create intent，请执行以下操作：

1. 验证请求：

   • 验证 client_id、client_secret 和 grant_type。
   • 验证 assertion (JWT)。

2. 验证用户不存在：

   • 检查您的数据库中是否已存在 sub 或 email。
   • 如果用户 存在，请返回 HTTP 401 Unauthorized，并使用 {"error": "linking_error", "login_hint": "USER_EMAIL"} 强制回退到 OAuth 关联。

3. 创建账号：

   • 使用 JWT 中的 sub、email、name 和 picture 声明创建新的用户记录。

4. 回应：

   • 在 JSON 响应 (HTTP 200 OK) 中生成并返回令牌。

Google API クライアント ID を取得する

アカウント リンクの登録プロセスで、Google API クライアント ID を指定する必要があります。OAuth リンクの手順を完了する際に作成したプロジェクトを使用して API クライアント ID を取得します。手順は次のとおりです。

1. [クライアント] ページに移動します。

2. Google APIs プロジェクトを作成または選択します。

   プロジェクトにウェブ アプリケーション タイプのクライアント ID がない場合は、[クライアントを作成] をクリックして作成します。[承認済みの JavaScript 生成元] ボックスに、サイトのドメインを必ず含めてください。ローカルテストや開発を行う場合は、[承認済みの JavaScript の生成元] フィールドに http://localhost と http://localhost:<port_number> の両方を追加する必要があります。

実装を検証する

OAuth 2.0 Playground ツールを使用して、実装を検証できます。

このツールで、次の手順を行います。

1. [構成] settings 設定をクリックして、[OAuth 2.0 構成] ウィンドウを開きます。
2. [OAuth flow] フィールドで、[クライアントサイド] を選択します。
3. [OAuth Endpoints] フィールドで、[Custom] を選択します。
4. 対応するフィールドに、OAuth 2.0 エンドポイントと Google に割り当てたクライアント ID を指定します。
5. [Step 1] セクションで、Google スコープを選択しないでください。代わりに、このフィールドを空白のままにするか、サーバーで有効なスコープを入力します（OAuth スコープを使用しない場合は任意の文字列を入力します）。完了したら、[Authorize APIs] をクリックします。
6. [Step 2] セクションと [Step 3] セクションで、OAuth 2.0 フローを確認し、各ステップが意図したとおりに動作することを確認します。

Google アカウント リンク デモツールを使用して、実装を検証できます。

このツールで、次の手順を行います。

1. [Google でログイン] ボタンをクリックします。
2. リンクするアカウントを選択します。
3. サービス ID を入力します。
4. 必要に応じて、アクセスをリクエストするスコープを 1 つ以上入力します。
5. [Start Demo] をクリックします。
6. 確認のメッセージが表示されたら、リンク リクエストに同意または拒否できることを確認します。
7. プラットフォームにリダイレクトされることを確認します。