11 月 21 日に、スマートホームのドキュメントはすべて Google Home Developer Center に移動します。Google Home Developer Center では、さらに役立つリソースをご用意しています。注: アクションの構築は、引き続き Actions Console で行います。

概要

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

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

設計ガイドライン

このセクションでは、アプリフリップアカウントのリンク同意画面の設計要件と推奨事項について説明します。Google からアプリが呼び出されると、同意画面が表示されます。

要件

ユーザーのアカウントが特定の Google サービス（Google Home や Google アシスタントなど）ではなく、Google にリンクされていることを示す必要があります。

推奨事項

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

Google のプライバシーポリシーを表示する。同意画面に Google のプライバシーポリシーへのリンクを含めます。
共有するデータ。明確で簡潔な表現を使って、Google が必要とするデータとその理由をユーザーに伝えます。
行動を促す明確なフレーズがある。「同意してリンクする」など、行動を促す明確なフレーズを明記する。これは、ユーザーがアカウントをリンクするために Google と共有する必要があるデータを理解する必要があるからです。
解約が可能。ユーザーがリンクしない場合に、戻るかキャンセルする方法を提供する。
リンクを解除する機能。プラットフォーム上でのアカウント設定の URL など、リンクを解除するメカニズムをユーザーに提供します。あるいは、ユーザーがリンクされたアカウントを管理できる Google アカウントへのリンクを含めることもできます。
ユーザーアカウントを変更できること。ユーザーがアカウントを切り替える方法を提案する。これは、ユーザーが複数のアカウントを持つ傾向がある場合に特に役立ちます。
- ユーザーがアカウントを切り替えて同意画面を閉じる必要がある場合は、OAuth リンクと暗黙的フローを使用して、ユーザーが希望するアカウントにログインできるように、回復可能なエラーを Google に送信します。
ロゴを掲載する。同意画面に会社のロゴを表示します。スタイルガイドラインを使用してロゴを配置します。Google のロゴも表示する場合は、ロゴと商標をご覧ください。

同意画面の例は、個々の同意要件と、同意画面を設計する際に従うべき推奨事項を示したものです。 — **図 2.**アカウントリンク同意画面のデザインガイドライン

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

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

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

OAuth 2.0 サーバーを実装する

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

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

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

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

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

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

ていることを確認しclient_id Googleに割り当てられたクライアントIDと一致すること、およびredirect_uriあなたのサービスのためにGoogleが提供するリダイレクトURLと一致します。これらのチェックは、意図しないクライアントアプリや誤って構成されたクライアントアプリへのアクセスを許可しないようにするために重要です。あなたが複数のOAuth 2.0のフローをサポートしている場合、またことを確認response_typeあるcode 。
ユーザーがサービスにサインインしているかどうかを確認します。ユーザーがサインインしていない場合は、サービスのサインインまたはサインアップフローを完了します。
GoogleがAPIへのアクセスに使用する認証コードを生成します。認証コードには任意の文字列値を指定できますが、ユーザー、トークンの対象となるクライアント、およびコードの有効期限を一意に表す必要があり、推測できないようにする必要があります。通常、約10分後に有効期限が切れる認証コードを発行します。

URLがで指定されていることを確認redirect_uriパラメータは次の形式を持っている：

  https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
  https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

で指定されたURLにユーザーのブラウザをリダイレクトredirect_uriパラメータ。あなたが追加することによってリダイレクトするときにだけ生成された認証コードとオリジナルの、無修正の状態値を含めるcodeやstateのパラメータを。以下は、得られた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は、次の手順を実行して要求：

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

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次のステップを実行することにより、要求：

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

HTTPS応答の本文で次のJSONオブジェクトを返します。

{
"token_type": "Bearer",
"access_token": " ACCESS_TOKEN ",
"expires_in": SECONDS_TO_EXPIRATION
}

userinfoリクエストを処理する

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

リンクされたアカウントサインイングーグルワンタップで。
摩擦のサブスクリプションAndroidTVに。

トークンエンドポイントからアクセストークンが正常に取得されると、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エンドポイントでリクエストを処理するには、次の手順を実行します。

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

アクセストークンが有効であれば、リターンおよび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 でアカウントリンクを設定する手順は次のとおりです。

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

次のステップ（省略可）

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