OAuth ベースの Google ログイン「効率化」リンクのコンセプト ガイド

OAuth ベースの Google ログインの「合理化」リンクタイプは、OAuth ベースのアカウント リンクに Google ログインを追加します。アクションでこのリンクタイプを使用する場合、フローは Google ログインから始まります。これにより、ユーザーの Google プロフィール情報がシステムに存在するかどうかを確認できます。そうでない場合は、標準の OAuth フローが開始されます。これら 2 つのリンクタイプを組み合わせることで、ユーザーはアクション内の ID を Google アカウントまたは Google 以外のアカウントにリンクできます。必要に応じて、Google プロフィール情報を使用して新しいアカウントを作成することもできます。

次のいずれかに該当する場合は、効率的なリンクの使用をおすすめします。

  • 複数のプラットフォームにまたがるアクションがある(たとえば、アクションが Android アプリで動作する場合)。
  • 既存の認証システムがあり、ユーザーが自分の ID を Google 以外のアカウントとリンクできるようにしたい場合。たとえば、ポイント プログラムを提供していて、ユーザーが既存のアカウントで獲得したポイントが失われないようにしたい場合などに便利です。

効率的なリンクが適切なソリューションかどうかを確認するには、アカウントのリンクの種類を選択するページをご覧ください。

主な用語

効率的なリンクの仕組みについて読む前に、次の用語を理解しておいてください。

  • Google ID トークン: ユーザーの基本的な Google プロフィール情報(名前、メールアドレス、プロフィール写真)を含む、ユーザー ID の署名付きアサーション。Google ID トークンは JSON Web Token(JWT)です。デコードされたトークンの例を以下に示します。
{
  "sub": 1234567890,        // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The token's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Client ID assigned to your Actions project
  "iat": 233366400,         // Unix timestamp of the token's creation time
  "exp": 233370000,         // Unix timestamp of the token's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "locale": "en_US"
}
  • user.verificationStatus: 現在のセッションに確認済みのユーザーがいるかどうかを示すためにシステムによって設定されるプロパティ。

  • user.accountLinkingStatus: 現在のセッションのユーザーにリンクされた ID があるかどうかを示すために、システムによって設定されるプロパティ。

  • アカウント リンク システム シーン: アカウント リンクの確認フローを実装する事前定義されたシーン。特定のユースケースに合わせてカスタマイズできます。

  • 認可コードフロー: 簡易リンクで実装できる OAuth 2.0 フロー。このフローには 2 つのエンドポイントが必要です。

    • 認可エンドポイント: まだログインしていないユーザーにログイン UI を表示するエンドポイント。リクエストされたアクセスへの同意が、有効期間の短い認証コードの形式で記録されます。
    • トークン交換エンドポイント: このエンドポイントは、次の 2 種類の交換を行います。
      1. 認可コードを、有効期間の長い更新トークンと有効期間の短いアクセス トークンと交換します。この交換は、ユーザーがアカウント リンクのフローを行う際に行われます。
      2. 有効期間の長い更新トークンを有効期間の短いアクセス トークンと交換します。この交換は、アクセス トークンの有効期限が切れているために Google が新しいアクセス トークンを必要とする場合に発生します。
  • 暗黙的コードフロー: 簡易リンクを使用して実装できる OAuth 2.0 フロー。このフローには、認可エンドポイントのみが必要です。このフローでは、Google はユーザーのブラウザで認可エンドポイントを開きます。ログインに成功すると、有効期間の長いアクセス トークンを Google に返します。このアクセス トークンが、アシスタントからアクションに送信されるすべてのリクエストに含まれるようになりました。

  • アクセス トークン: サービスがユーザーのデータの一部にアクセスすることを許可するトークン。アクセス トークンは個々のユーザーに関連付けられます。

  • 更新トークン: 有効期間の短いアクセス トークンの有効期限が切れたときに、新しいアクセス トークンと交換されるトークン。

前提条件

合理化されたリンクタイプを使用するには、次のものが必要です。

  • OAuth 2.0 サーバー
  • トークン交換エンドポイント

    トークン交換エンドポイントを拡張して、ID トークンからの自動リンクとアカウント作成のための Google プロトコルのサポートを追加する必要があります(このエンドポイントへのリクエストに intent=get パラメータと intent=create パラメータを追加する)。

仕組み

このセクションでは、リンクを効率化する一般的なフローについて説明します。 次のセクションの合理化されたリンクフローでは、a)音声によるアカウントの作成を有効または無効にするかどうか、b)暗黙的なコードフローと認可コードフローのどちらを使用するかに基づいて、実行されるさまざまなフローについて説明します。

基本的な流れは次のとおりです。

  1. アクションが、Google プロフィールへのアクセスについてユーザーに同意を求めます。
  2. ユーザーが同意すると、アクションはユーザーの Google プロフィール情報を含む Google ID トークンを受け取ります。
  3. プロファイルのコンテンツを読み取るには、トークンを検証してデコードする必要があります。
  4. アクションはこのトークンを使用して、ユーザーの Google プロフィール情報がシステムに存在するかどうかを確認します。
    1. ログインしている場合、ユーザーはすでに Google アカウントでシステムにログインしており、アシスタントはユーザーの ID を Google アカウントにリンクします。ユーザーは、アカウントをリンクした状態でアシスタントとの会話を続けることができます。
    2. 表示されない場合は、ステップ 5 をご覧ください。
  5. ユーザーは、a)Google プロフィール情報を使用して新しいアカウントを作成するか、b)別のアカウントでシステムにログインできます。ユーザーに表示される選択肢は、音声によるアカウントの作成を有効または無効にするかどうかによって異なります。ユーザーが別のアカウントでログインすることを選択した場合、標準の OAuth フローが開始されます。
  6. ユーザーが新しいアカウントを作成するか、別のプロバイダでログインすると、サービスが Google にアクセス トークンを返します。(認可コードフローを使用している場合、サービスも更新トークンを返します)。
  7. これで、ユーザーはアカウントをリンクした状態でアシスタントとの会話を続けることができます。

合理化されたリンクフロー

このセクションでは、合理化されたリンクによって実現できるさまざまなフローについて説明します。この図では、暗黙のコードフローではなく認可コードフローを使用した場合のフローについて説明し、Actions Builder を使用していることを前提としています。

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

上記のフローでは、アカウント リンク システムのシーンに移行し、カスタマイズされた根拠を示します。シーンでは、Google プロフィール情報にアクセスする権限をユーザーに依頼します。ユーザーが同意すると、アシスタントは user@gmail.com のプロフィール情報を含むリクエストを送信します。

この時点以降のフローは、音声によるアカウント リンクを構成しているかどうかと、ユーザーの情報がシステムにすでに存在するかどうかによって異なります。以降のセクションで、これらの各フローについて説明します。

音声アカウントの作成が有効なフロー

このセクションでは、音声によるアカウントの作成を有効にした場合に可能なアカウント リンクフローについて詳しく説明します。

フロー 1: ユーザーの情報がシステムに存在する

この場合、user@gmail.com で表されるユーザーはバックエンドに存在するため、トークン交換エンドポイントはユーザーのトークンを返します。これで、アクション内のユーザー ID が Google アカウントにリンクされます。ユーザーの元のリクエスト(「通常注文」)は、ユーザー インテント order_drink. と一致します。Webhook は、一致したインテントのフルフィルメントを処理し、データベースに user@gmail.com の通常の順序を照会します。ユーザーはアシスタントとの会話を続けることができます。

フロー 2: ユーザーの情報がなく、ユーザーがアカウントを作成する

音声によるアカウントの作成を有効にしても、user@gmail.com はバックエンドに存在しないため、アシスタントはユーザーに次のいずれかを行うかどうかを尋ねます。

a)Google プロフィール情報を使用してシステムに新しいアカウントを作成する。アカウントの新規作成は音声で行う

b)別のアカウントでシステムにログインする

この場合、ユーザーは音声を使用して新しいアカウントを作成することを選択します。Google は、アカウントの作成リクエストを使用して、サービスのトークン交換エンドポイントを呼び出します。このリクエストには、新しいアカウントを作成するために必要なコンポーネントを含む Google ID トークンが含まれています。その後、このトークンの情報(ユーザーの名前とメールアドレス)を使用して、ユーザーのアカウントを作成できます。

アカウントが作成されると、サービスは新しく作成されたアカウントのアクセス トークンと更新トークンを返します。これで、アクション内のユーザー ID が Google アカウントにリンクされます。ユーザーの元のリクエスト(「通常注文して」)は、ユーザー インテント order_drink. と一致します。その後、Webhook は一致したインテントのフルフィルメントを処理し、ユーザーが新しいためまだ存在しない user@gmail.com の通常の順序をデータベースに照会します。アクションはユーザーに何の注文をするか尋ねることができます。

フロー 3: ユーザーの情報がなく、ユーザーが別のアカウントでログインする

音声によるアカウントの作成を有効にしたため、アシスタントはユーザーに次のいずれかの操作を行うかどうかを尋ねます。

a)Google プロフィール情報を使用してシステムに新しいアカウントを作成する。アカウントの新規作成は音声で行う

b)別のアカウントでシステムにログインする

この場合、ユーザーは別のアカウントでログインすることを選択し、それによって標準の OAuth フローが開始されます。音声専用デバイスでフローが開始された場合、実行はスマートフォンに転送されます。Google はユーザーのブラウザで認可エンドポイントを開きます。ユーザーは構成に応じて、a)Google ログインを使用していない既存のアカウントでサービスにログインするか、b)別のプロバイダを使用して新しいアカウントを作成するかを選択できます。OAuth フローの詳細については、OAuth リンクのコンセプト ガイドをご覧ください。

ユーザーの認証情報を確認すると、サービスはアクセス トークンと更新トークンを Google に返します。これで、アクション内のユーザー ID が Google 以外のアカウントにリンクされました。ユーザーの元のリクエスト(「通常注文して」)は、ユーザー インテント order_drink. と一致します。その後 Webhook は、一致したインテントのフルフィルメントを処理し、user@gmail.com の通常の順序をデータベースに照会します。この順序はユーザーが初めてであるため、まだ存在していません。アクションは、ユーザーに注文したい内容や、通常の注文を設定するよう依頼できます。

音声アカウントの作成が無効になっているフロー

このセクションでは、音声によるアカウントの作成を無効にした場合に発生する可能性があるアカウントのリンクのフローについて詳しく説明します。

フロー 4: ユーザーの情報が存在しない

音声によるアカウントの作成を有効にしておらず、ユーザーがバックエンドに存在しないため、標準の OAuth フローが開始されます。Google アシスタントがユーザーのブラウザで認可エンドポイントを開きます(音声専用デバイスでフローが開始された場合、Google は画面のあるデバイスに実行を転送します)。ユーザーは、a)別のプロバイダでサービスに登録している場合は別のプロバイダでログインするか、b)別のプロバイダで新しいアカウントを作成するかを選択できます。OAuth フローの詳細については、OAuth リンクのコンセプト ガイドをご覧ください。

ユーザーの認証情報を確認すると、サービスはアクセス トークンと更新トークンを Google に返します。これで、アクション内のユーザー ID が Google 以外のアカウントにリンクされました。ユーザーの元のリクエスト(「通常注文して」)は、ユーザー インテント order_drink. と一致します。その後 Webhook は、一致したインテントのフルフィルメントを処理し、user@gmail.com の通常の順序をデータベースに照会します。この順序はユーザーが初めてであるため、まだ存在していません。アクションは、ユーザーに通常の注文をセットアップするよう依頼できます。