OAuth リンクのコンセプトガイド

OAuth リンクタイプは、業界標準の OAuth 2.0 フロー（暗黙的フローと認可コードフロー）の 2 つをサポートしています。暗黙的なコードフローでは、Google がユーザーのブラウザで認可エンドポイントを開きます。ログインに成功すると、有効期間の長いアクセストークンが Google に返されます。このアクセストークンは、アシスタントからアクションに送信されるすべてのリクエストに含まれます。

次の場合は、OAuth リンクのソリューションの使用をおすすめします。

OAuth 2.0 サーバーの既存の実装がある場合、トークン交換エンドポイントを拡張して、ID トークンからの自動リンクおよびアカウント作成のための Google プロトコルのサポートを追加することはできません（このエンドポイントへのリクエストに intent=get パラメータと intent=create パラメータを追加するなど）。

OAuth リンクが適切なソリューションであることを確認するには、アカウントリンクタイプを選択するページをご覧ください。

主な用語

OAuth リンクの仕組みを理解する前に、次の用語を理解しておいてください。

user.verificationStatus: 現在のセッションに確認済みのユーザーがいるかどうかを示すためにシステムによって設定されるプロパティ。
user.accountLinkingStatus: 現在のセッションのユーザーにリンクされた ID があるかどうかを示すために、システムによって設定されるプロパティ。
アカウントリンクシステムシーン: アカウントリンクの確認フローを実装する事前定義されたシーン。特定のユースケースに合わせてカスタマイズできます。
認可コードフロー: この OAuth 2.0 フロー中に、Google はユーザーのブラウザで認可エンドポイントを開きます。ログインに成功すると、サービスが認可コードを作成し、そのコードを Google に返します。Google はこの認可コードをトークン交換エンドポイントに送信します。このエンドポイントはコードの真正性を検証し、アクセストークンと更新トークンを返します。

このフローには 2 つのエンドポイントが必要です。
- 認可エンドポイント: データアクセスについてユーザーの同意を得る、またはユーザーから同意を得るためのエンドポイント。このエンドポイントは次の処理を行います。
  1. まだログインしていないユーザーにログイン UI を表示します。
  2. リクエストされたアクセスへの同意を有効期間の短い認証コードの形式で記録します。
- トークン交換エンドポイント: このエンドポイントは、アクションユーザーによるサービスへのアクセスを許可するトークンと呼ばれる暗号化された文字列を取得するために使用されます。このエンドポイントは、次の 2 種類の交換を行います。
  1. 認可コードを、有効期間の長い更新トークンと有効期間の短いアクセストークンと交換します。この交換は、ユーザーがアカウントリンクのフローを行う際に行われます。
  2. 有効期間の長い更新トークンを有効期間の短いアクセストークンと交換します。この交換は、アクセストークンの有効期限が切れているために Google が新しいアクセストークンを必要とする場合に発生します。
暗黙的なコードフロー: この OAuth 2.0 フローでは、Google はユーザーのブラウザで認可エンドポイントを開きます。ログインに成功すると、有効期間の長いアクセストークンを Google に返します。このアクセストークンは、アシスタントからアクションに送信されるすべてのリクエストに含まれます。このフローには、認可エンドポイントのみが必要です。
アクセストークン: サービスがユーザーのデータの一部にアクセスすることを許可するトークン。アクセストークンは個々のユーザーに関連付けられているため、推測できないものにする必要があります。
更新トークン: 有効期間の短いアクセストークンの有効期限が切れたときに、新しいアクセストークンと交換されるトークン。

仕組み

このセクションでは、OAuth 認可コードと暗黙的フローの一般的なフローについて説明します。次のセクションの OAuth リンクフローでは、OAuth で発生する可能性のあるさまざまなフローについて説明します。

認可コードフローの概要は次のとおりです。

アクションは、アカウントをサービスにリンクするかどうかをユーザーに尋ねます。
ユーザーがアカウントのリンクに同意すると、ユーザーのブラウザで認可エンドポイントが開きます。音声専用デバイスでアクションのフローが開始された場合、Google は実行をスマートフォンに転送します。
ユーザーがログインして（まだログインしていない場合）、Google に API を使用して自分のデータにアクセスする権限を付与します（まだ権限を付与していない場合）。
サービスが認可コードを作成し、リクエストに付加された認可コードとともにユーザーのブラウザを Google にリダイレクトして Google に認可コードを返します。
Google が認可コードをトークン交換エンドポイントに送信します。このエンドポイントはコードの真正性を検証し、アクセストークンと更新トークンを返します。アクセストークンは有効期間の短いトークンで、サービスが API にアクセスするための認証情報として受け入れられます。更新トークンは長期間有効なトークンです。Google では、このトークンを保存して、有効期限が切れたときに新しいアクセストークンを取得するために使用できます。
ユーザーがアカウントのリンクのフローを完了すると、アシスタントからフルフィルメント Webhook に送信されるすべてのリクエストにアクセストークンが含まれます。

暗黙的なコードフローをまとめると、次のようになります。

アクションは、アカウントをサービスにリンクするかどうかをユーザーに尋ねるものです。
ユーザーがアカウントのリンクに同意すると、ユーザーのブラウザで認可エンドポイントが開きます。
ユーザーがログインして（まだログインしていない場合）、Google に API を使用して自分のデータにアクセスする権限を付与します（まだ権限を付与していない場合）。
サービスがアクセストークンを作成し、リクエストに付加されたアクセストークンを使用してユーザーのブラウザを Google にリダイレクトして Google に返します。
ユーザーがアカウントのリンクのフローを完了すると、Google はサービスの API を呼び出し、各リクエストにアクセストークンを付与します。サービスが、アクセストークンによって Google に API へのアクセス権限が付与されていることを確認して、API 呼び出しを完了します。

基本的な認可コードフローは次のとおりです。

アクションは、アカウントをサービスにリンクするかどうかをユーザーに尋ねます。
ユーザーがアカウントのリンクに同意すると、ユーザーのブラウザで認可エンドポイントが開きます。音声専用デバイスでアクションのフローが開始された場合、Google は実行をスマートフォンに転送します。
ユーザーがログインして（まだログインしていない場合）、Google に API を使用して自分のデータにアクセスする権限を付与します（まだ権限を付与していない場合）。
サービスが認可コードを作成し、リクエストに付加された一時的な認可コードをユーザーのブラウザを Google にリダイレクトして Google に返します。
Google が認可コードをトークン交換エンドポイントに送信します。このエンドポイントはコードの真正性を検証し、アクセストークンと更新トークンを返します。アクセストークンは有効期間の短いトークンで、サービスが API にアクセスするための認証情報として受け入れられます。更新トークンは長期間有効なトークンです。Google では、このトークンを保存して、有効期限が切れたときに新しいアクセストークンを取得するために使用できます。
ユーザーがアカウントのリンクのフローを完了すると、アシスタントからフルフィルメント Webhook に送信されるすべてのリクエストにアクセストークンが含まれます。

OAuth リンクフロー

このセクションでは、OAuth リンクで発生する可能性のあるさまざまなフローについて説明します。

各フローには、ユーザーがアクションを呼び出した後の一般的なステップが含まれます。

上記のフローでは、アカウントリンクシステムのシーンに移行し、カスタマイズされた根拠を示します。Google アシスタントは、アカウントをサービスにリンクするかどうかをユーザーに尋ね、リクエストされた権限を含む画面が表示されます。ユーザーが同意すると、Google はブラウザ内のサービスの認可エンドポイントにユーザーをリダイレクトします。ユーザーがログインして（構成によっては新しいアカウントを作成し）、ユーザーのデータにアクセスする権限をアクションに付与します。

この後のフローは、暗黙的フローまたは認可コードフローを実装したかどうかによって異なります。これらのフローについては、次のセクションで説明します。

フロー 1: ユーザーが暗黙的フローでログインする

ユーザーがログインして認証情報を確認すると、有効期間が長いアクセストークンが作成され、Google に返されます。この時点で、アクション内のユーザーの ID はログインに使用したアカウントにリンクされ、Google がサービスの API に対して行う各 API 呼び出しにアクセストークンが追加されます。

フロー 2: ユーザーが認可コードフローでログインする

ユーザーがログインして認証情報を確認すると、サービスによって認証コードが作成され、Google に返されます。

この認可コードはトークン交換エンドポイントに送信され、トークン交換エンドポイントからアクセストークンと更新トークンの両方が返されます。この時点で、アクション内のユーザー ID はユーザーがログインしたアカウントにリンクされ、アシスタントからフルフィルメントに送信されるすべての後続のリクエストにアクセストークンが含まれます。