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 で発生する可能性のあるさまざまなフローについて説明します。

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

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

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

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

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

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

OAuth リンクフロー

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

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

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

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

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

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

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

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

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