概要

すべてのスマートホーム アクションには、ユーザーを認証するための仕組みを組み込む必要があります。

認証を使用すると、ユーザーの Google アカウントと認証システム内のユーザー アカウントを関連付けることができます。これにより、フルフィルメントでスマートホーム インテントを受け取ったときにユーザーを識別できます。Google スマートホームは、認証コード フローを使用した OAuth のみに対応します。

設計ガイドライン

このセクションでは、AppFlipアカウントリンク同意画面の設計要件と推奨事項について説明します。 Googleがアプリを呼び出すと、アプリはユーザーに同意画面を表示します。

要件

  1. ユーザーのアカウントが、GoogleホームやGoogleアシスタントなどの特定のGoogle製品ではなく、Googleにリンクされていることを伝える必要があります。

推奨事項

次のことを行うことをお勧めします。

  1. Googleのプライバシーポリシーを表示します。同意画面にGoogleのプライバシーポリシーへのリンクを含めます。

  2. 共有するデータ。明確で簡潔な言葉を使用して、Googleが必要とするデータとその理由をユーザーに伝えます。

  3. 召喚状を明確にします。 「同意してリンクする」など、同意画面に明確な召喚状を記載します。これは、ユーザーがアカウントをリンクするためにGoogleと共有する必要があるデータを理解する必要があるためです。

  4. キャンセルする機能。リンクしないことを選択した場合、ユーザーが戻るかキャンセルする方法を提供します。

  5. リンクを解除する機能。プラットフォームのアカウント設定へのURLなど、ユーザーがリンクを解除するためのメカニズムを提供します。または、ユーザーがリンクされたアカウントを管理できるGoogleアカウントへのリンクを含めることもできます。

  6. ユーザーアカウントを変更する機能。ユーザーが自分のアカウントを切り替える方法を提案します。これは、ユーザーが複数のアカウントを持っている傾向がある場合に特に役立ちます。

    • ユーザーがアカウントを切り替えるために同意画面を閉じる必要がある場合は、回復可能なエラーをGoogleに送信して、ユーザーがOAuthリンク暗黙的なフロー使用して目的のアカウントにサインインできるようにします。
  7. あなたのロゴを含めてください。同意画面に会社のロゴを表示します。スタイルガイドラインを使用してロゴを配置します。 Googleのロゴも表示したい場合は、ロゴと商標を参照してください。

この図は、ユーザーの同意画面を設計するときに従うべき個々の要件と推奨事項への呼び出しを含む同意画面の例を示しています。
図2.アカウントリンク同意画面の設計ガイドライン。

OAuth によるアカウント リンクを実装する

スマートホーム アクションに OAuth によるアカウント リンクを実装するには、次の手順を行う必要があります。

  1. OAuth サーバー 2.0 を実装します。
  2. Actions Console でアカウント リンクを設定します。

OAuth 2.0 サーバーを実装する

ここでは、OAuth 2.0 サーバーを設定してスマートホーム アクションと連携させる方法について説明します。

認証コードフローのOAuth 2.0のサーバーの実装では、あなたのサービスは、HTTPSで利用できるように2つのエンドポイント、から構成されています。最初のエンドポイントは承認エンドポイントであり、データアクセスについてユーザーからの同意を検索または取得する責任があります。承認エンドポイントは、まだサインインしていないユーザーにサインインUIを提示し、要求されたアクセスへの同意を記録します。 2番目のエンドポイントは、トークン交換エンドポイントです。これは、トークンと呼ばれる暗号化された文字列を取得するために使用され、ユーザーにサービスへのアクセスを許可します。

GoogleアプリケーションがサービスのAPIの1つを呼び出す必要がある場合、Googleはこれらのエンドポイントを一緒に使用して、ユーザーからユーザーに代わってこれらのAPIを呼び出す許可を取得します。

Googleによって開始されたOAuth2.0認証コードフローセッションには、次のフローがあります。

  1. Googleは、ユーザーのブラウザで認証エンドポイントを開きます。アクションの音声のみのデバイスでフローが開始された場合、Googleは実行を電話に転送します。
  2. ユーザーは、まだサインインしていない場合はサインインし、まだアクセス許可を付与していない場合は、APIを使用してデータにアクセスするためのGoogleアクセス許可を付与します。
  3. あなたのサービスは、認証コードを作成し、Googleにそれを返します。これを行うには、リクエストに認証コードを添付して、ユーザーのブラウザをGoogleにリダイレクトします。
  4. Googleは、コードの正当性を検証し、アクセストークンリフレッシュトークンを返し、あなたのトークン交換エンドポイントに認証コードを送信します。アクセストークンは、APIにアクセスするための資格情報としてサービスが受け入れる短期間のトークンです。更新トークンは、有効期限が切れたときにGoogleが保存して、新しいアクセストークンを取得するために使用できる長期間有効なトークンです。
  5. ユーザーがアカウントのリンクフローを完了すると、Googleから送信される後続のすべてのリクエストにアクセストークンが含まれます。

承認リクエストを処理する

OAuth 2.0認証コードフローを使用してアカウントのリンクを実行する必要がある場合、Googleは次のパラメータを含むリクエストを使用してユーザーを認証エンドポイントに送信します。

承認エンドポイントパラメータ
client_id Googleに割り当てたクライアントID。
redirect_uriこのリクエストへの応答を送信するURL。
stateリダイレクトURIで変更されずにGoogleに返される簿記の値。
scopeオプション:Googleがために許可を要求しているデータを指定範囲の文字列のスペース区切りのセット。
response_type応答で返す値のタイプ。 OAuth 2.0の認証コードの流れについては、応答タイプは常にあるcode
user_localeでGoogleアカウントの言語設定RFC5646のユーザーの優先言語でコンテンツをローカライズするために使用される形式、。

あなたの認可エンドポイントがで利用可能である場合たとえば、 https://myservice.example.com/auth 、要求は次のようになります。

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE

承認エンドポイントがサインイン要求を処理するには、次の手順を実行します。

  1. ていることを確認しclient_id Googleに割り当てられたクライアントIDと一致すること、およびredirect_uriあなたのサービスのためにGoogleが提供するリダイレクトURLと一致します。これらのチェックは、意図しないクライアントアプリや誤って構成されたクライアントアプリへのアクセスを許可しないようにするために重要です。あなたが複数のOAuth 2.0のフローをサポートしている場合、またことを確認response_typeあるcode
  2. ユーザーがサービスにサインインしているかどうかを確認します。ユーザーがサインインしていない場合は、サービスのサインインまたはサインアップフローを完了します。
  3. GoogleがAPIへのアクセスに使用する認証コードを生成します。認証コードには任意の文字列値を指定できますが、ユーザー、トークンの対象となるクライアント、およびコードの有効期限を一意に表す必要があり、推測できないようにする必要があります。通常、約10分後に有効期限が切れる認証コードを発行します。
  4. URLがで指定されていることを確認redirect_uriパラメータは次の形式を持っている:
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
      https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
      
  5. で指定されたURLにユーザーのブラウザをリダイレクトredirect_uriパラメータ。あなたが追加することによってリダイレクトするときにだけ生成された認証コードとオリジナルの、無修正の状態値を含めるcodestateのパラメータを。以下は、得られたURLの例です:
    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

トークン交換リクエストを処理する

サービスのトークン交換エンドポイントは、次の2種類のトークン交換を担当します。

  • アクセストークンと更新トークンの認証コードを交換します
  • 更新トークンをアクセストークンと交換する

トークン交換リクエストには、次のパラメータが含まれます。

トークン交換エンドポイントパラメーター
client_idリクエストの発信元をGoogleとして識別する文字列。この文字列は、Googleの一意の識別子としてシステム内に登録する必要があります。
client_secretサービスのためにGoogleに登録した秘密の文字列。
grant_type交換されるトークンのタイプ。それはどちらかだauthorization_codeまたはrefresh_token
codeときgrant_type=authorization_code 、このパラメータは、Googleがあなたのサインインまたはトークン交換エンドポイントのいずれかから受信したコードです。
redirect_uriときgrant_type=authorization_code 、このパラメータは、最初の認証要求で使用されるURLです。
refresh_tokenときgrant_type=refresh_token Googleがあなたのトークン交換エンドポイントから受信したトークンは、このパラメータは、リフレッシュです。
アクセストークンと更新トークンの認証コードを交換します

ユーザーがログインし、認証エンドポイントが短期間の認証コードをGoogleに返すと、Googleはトークン交換エンドポイントにリクエストを送信して、認証コードをアクセストークンと更新トークンに交換します。

これらの要求のために、の値grant_typeありauthorization_code 、との値code以前にGoogleに付与された認証コードの値です。次に、認証コードをアクセストークンと更新トークンに交換するリクエストの例を示します。

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

アクセストークンとリフレッシュトークン、トークン交換エンドポイントの応答のための交換認証コードへPOSTは、次の手順を実行して要求:

  1. ことを確認しclient_id認可原点として要求元を識別し、そのclient_secret期待値と一致します。
  2. 認証コードが有効で有効期限が切れていないこと、および要求で指定されたクライアントIDが認証コードに関連付けられたクライアントIDと一致することを確認してください。
  3. URLがで指定されていることを確認redirect_uriパラメータは、最初の認証要求で使用される値と同じです。
  4. あなたが上記の基準のすべてを確認できない場合は、とHTTP 400不正な要求エラーを返す{"error": "invalid_grant"}ボディとして。
  5. それ以外の場合は、認証コードのユーザーIDを使用して、更新トークンとアクセストークンを生成します。これらのトークンは任意の文字列値にすることができますが、トークンの対象となるユーザーとクライアントを一意に表す必要があり、推測可能であってはなりません。アクセストークンの場合は、トークンの有効期限も記録します。これは通常、トークンを発行してから1時間後です。更新トークンは期限切れになりません。
  6. HTTPS応答の本文に以下のJSONオブジェクトを返します:
    {
    "token_type": "Bearer",
    "access_token": "ACCESS_TOKEN",
    "refresh_token": "REFRESH_TOKEN",
    "expires_in": SECONDS_TO_EXPIRATION
    }
    

Googleは、ユーザーのアクセストークンと更新トークンを保存し、アクセストークンの有効期限を記録します。アクセストークンの有効期限が切れると、Googleは更新トークンを使用してトークン交換エンドポイントから新しいアクセストークンを取得します。

更新トークンをアクセストークンと交換する

アクセストークンの有効期限が切れると、Googleはトークン交換エンドポイントにリクエストを送信して、更新トークンを新しいアクセストークンと交換します。

これらの要求のために、の値grant_typeされrefresh_token 、との値refresh_token以前にGoogleに付与されたリフレッシュトークンの値です。以下は、更新トークンをアクセストークンと交換するリクエストの例です。

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

アクセストークンのリフレッシュトークン、トークン交換エンドポイントの応答を交換するにはPOST次のステップを実行することにより、要求:

  1. ていることを確認しclient_idグーグルとして要求元に識別し、そのclient_secret期待値と一致しました。
  2. 更新トークンが有効であること、および要求で指定されたクライアントIDが更新トークンに関連付けられたクライアントIDと一致することを確認します。
  3. あなたが上記の基準のすべてを確認できない場合は、とHTTP 400不正な要求エラーを返す{"error": "invalid_grant"}ボディとして。
  4. それ以外の場合は、更新トークンのユーザーIDを使用してアクセストークンを生成します。これらのトークンは任意の文字列値にすることができますが、トークンの対象となるユーザーとクライアントを一意に表す必要があり、推測可能であってはなりません。アクセストークンの場合は、トークンの有効期限も記録します。通常は、トークンを発行してから1時間後です。
  5. HTTPS応答の本文で次のJSONオブジェクトを返します。
    {
    "token_type": "Bearer",
    "access_token": " ACCESS_TOKEN ",
    "expires_in": SECONDS_TO_EXPIRATION
    }
userinfoリクエストを処理する

ユーザー情報エンドポイントは、リンクされたユーザについての戻り主張OAuth 2.0の保護されたリソースです。次のユースケースを除いて、userinfoエンドポイントの実装とホスティングはオプションです。

トークンエンドポイントからアクセストークンが正常に取得されると、Googleはuserinfoエンドポイントにリクエストを送信して、リンクされたユーザーに関する基本的なプロファイル情報を取得します。

userinfoエンドポイントリクエストヘッダー
Authorization headerタイプBearerのアクセストークン。

たとえば、あなたのuserinfoエンドポイントがで利用可能な場合https://myservice.example.com/userinfo 、要求は次のようになります。

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

userinfoエンドポイントでリクエストを処理するには、次の手順を実行します。

  1. Authorizationヘッダーからアクセストークンを抽出し、アクセストークンに関連付けられているユーザーの情報を返します。
  2. アクセストークンが無効である場合は、使用してHTTP 401不正なエラーを返すWWW-Authenticate応答ヘッダを。以下のユーザー情報のエラー応答の例である:
    HTTP/1.1 401 Unauthorized
    WWW-Authenticate: error="invalid_token",
    error_description="The Access Token expired"
    
    401不正な、または他の任意の失敗エラー応答をリンク処理中に返された場合、エラーが回復不能、検索されたトークンは廃棄されることになり、ユーザが持っているであろうリンクプロセスを再開します。
  3. アクセストークンが有効であれば、リターンおよびHTTPS応答の本文に以下のJSONオブジェクトとHTTP 200応答:

    {
    "sub": "USER_UUID",
    "email": "EMAIL_ADDRESS",
    "given_name": "FIRST_NAME",
    "family_name": "LAST_NAME",
    "name": "FULL_NAME",
    "picture": "PROFILE_PICTURE",
    }
    
    あなたのuserinfoエンドポイントがHTTP 200の成功応答を返した場合、トークン取得し、クレームはユーザーのGoogleに対して登録されていますアカウント。

    userinfoエンドポイント応答
    subシステム内のユーザーを識別する一意のID。
    emailユーザーのメールアドレス。
    given_nameオプション:ユーザーのファーストネーム。
    family_nameオプション:ユーザーの姓。
    nameオプション:ユーザーのフルネーム。
    pictureオプション:ユーザーのプロフィール画像。

コンソールでアカウント リンクを設定する

Actions Console でアカウント リンクを設定する手順は次のとおりです。

  1. Actions Console に移動します。
  2. スマートホーム アクション プロジェクトを選択します。
  3. [Develop](開発)タブを選択し、左側のナビゲーションで [Account linking](アカウントのリンク)をクリックします。
  4. [OAuth Client information](OAuth クライアント情報)のすべてのフィールドを入力します。[Next](次へ)をクリックします。
  5. [Save](保存)をクリックします。

次のステップ(省略可)

OAuth 2.0 を実装すると、OAuth ベースのアプリ切り替えを設定できるようになります。アプリ切り替えを使うと、デベロッパーの認証システムに登録されているユーザーのアカウントを、そのユーザーの Google アカウントに簡単にリンクできます。アプリ切り替えの実装手順については、OAuth ベースのアプリ切り替えをご覧ください。