Googleは、黒人コミュニティのための人種的衡平の促進に取り組んでいます。 方法をご覧ください。
このページは Cloud Translation API によって翻訳されました。
Switch to English

OAuth 2.0の認証と承認

Nest APIは、認証と承認にOAuth 2.0プロトコルを使用します。

Nest APIを使用して製品がプライベートデータにアクセスする前に、そのAPIへのアクセスを許可するアクセストークンを取得する必要があります。 1つのアクセストークンで、APIの複数のセクションにさまざまな程度のアクセスを許可できます。

認証シーケンスは、製品がブラウザーを、要求されたアクセスを示すクエリパラメーターを含むNest URLにリダイレクトしたときに始まります。 Nestはユーザー認証、セッション選択、ユーザー同意を処理します。結果は認証コードで、製品はこれをアクセストークンと交換できます。その後、製品はアクセストークンを使用してNest APIを呼び出すことができます。

OAuth 2.0フロー
OAuth 2.0フロー

Works with Nestクライアントを構成する

クライアントのOAuth 2.0認証情報を見つけるには、クライアントページの[概要]タブを確認します。

リダイレクトURIまたはPINベースの認証?

クライアントを構成するときに、リダイレクトURIを入力するか、リダイレクトURIフィールドを空白のままにしてPINベースの認証を使用するように求められます。

製品が、関連付けられたアプリまたはWebページを持たないデバイス(フィットネストラッカー、アプライアンス、セキュリティパネルなど)である場合は、[リダイレクトURI]フィールドを空白のままにします。

製品にブラウザコンポーネントがある場合、ベストプラクティスはリダイレクトURIを含めることです。

権限をリクエストする

クライアント構成には、一連のアクセス許可(スコープとも呼ばれます)が含まれています。アクセス許可は、アクセストークンが許可するリソースと操作のセットを制御する変数パラメーターです。一般に、事前にではなく、アクセスが必要なときに、アクセス許可を段階的に要求することがベストプラクティスです。

結果

構成を保存すると、クライアントに一意のクライアントIDとクライアントシークレットが割り当てられます。さらに、クライアントには認証URLが割り当てられます。

認証URLには、起こり得るクロスサイトリクエストフォージェリ(CSRF)攻撃をテストするために使用できる状態パラメーターが含まれています。 CSRF攻撃のテストを参照してください。

OAuthの詳細

認証コードをリクエストする

クライアントを構成したら、認証コード(PINコードと呼ばれることもあります)を要求できます。認証コードは、Nestの呼び出しに使用する最後のトークンではありません。これは、OAuth 2.0フローの次のステップで、実際のアクセストークンと交換するために使用されます。この手順により、Nestからユーザーに、合意されたアクセス権で正しい製品に権限が付与されていることが直接保証されます。

ユーザー体験

製品へのアクセスを許可するようユーザーに要求するWorks with Nestページを表示します。これにより、製品が識別され、製品が要求した特定のユーザー権限(スコープ)の概要が示されます。画面上の単語は、クライアント構成に由来します。

これを自分でテストするには、ステップ1の認証URLをブラウザーにロードします。 Works with Nestのアクセスリクエストページが表示されます。

Nestと連携

先に進み、自分で[承諾]をクリックして、ユーザーに表示される内容を確認してください。 [同意する]ボタンをクリックすると、ユーザーは製品のデータへのアクセス要求を承認します。

PIN体験

クライアント設定で[リダイレクトURI]フィールドを空白のままにすると、ユーザーはPIN(認証コード)を表示するNestページにリダイレクトされます。デバイスのUIは、ユーザーにPINを手動で入力するように求めます。

ピンコード

リダイレクトURIエクスペリエンス

クライアント設定にリダイレクトURIを含めると、ユーザーはクラウド(またはlocalhost)のページにリダイレクトされ、Nestは自動的に認証コードをユーザーのデバイスに送信します。

CSRF攻撃のテスト

製品は、認証コードを受け入れる前に、stateパラメータで返された値が元の認証リクエストからの状態値と一致することを確認する必要があります。これにより、悪意のあるスクリプトではなく、実際のユーザーを確実に処理できます。状態値が一致しない場合は、応答として401 Unauthorized HTTPエラーコードをスローする必要があります。

CSRF攻撃は、エンドユーザーに、現在認証されているWebアプリケーションで不要なアクションを実行させる攻撃です。

CSRF攻撃
CSRF攻撃

CSRF攻撃を防ぐために、承認を要求するときは常に推測不可能なstate送信することをお勧めします。

このようにして、Works with Nest統合は、Nestクラウドから取得したアクセスコードが、他の製品ではなく、製品からの要求に応答していることを確認できます。

例:

クライアントの設定で、リダイレクトURIを指定するとします。

 http://localhost:5000/callback
 

また、クライアントが認証URLで7tvPJiv8StrAqo9IQE9xsJaDso4状態を送信するとします。

 https://home.nest.com/login/oauth2?client_id=CLIENT_ID&state=7tvPJiv8StrAqo9IQE9xsJaDso4
 

ユーザーは要求に同意します。

Nestクラウドは、リダイレクトURIの一部として状態パラメーターを返します。

 127.0.0.1 - - [02/Jun/2017 13:18:58] "GET /callback?state=7tvPJiv8StrAqo9IQE9xsJaDso4&code=5N4CFK8E8TCFW7PM HTTP/1.1" 302 -
127.0.0.1 - - [02/Jun/2017 13:18:58] "GET / HTTP/1.1" 200 -
 

製品はこの状態値を受け取り、検証可能な状態のリダイレクトのみを受け入れるようにプログラムする必要があります。

推測できない状態パラメーターを生成する方法は複数あります。メモリに保持されているディクショナリからのランダム化された状態値または再計算可能な値を提供できます。簡単に検証できる変数(クライアントIDやセッションCookieなど)を含む秘密鍵を使用して、ハッシュ値を計算できます。これにより、秘密鍵がないと推測が困難なバイト値になります。別の提案は、現在の日付と時刻をハッシュすることです。このアプローチでは、アプリケーションはそれを検証するために送信時間を節約するか、または有効期間のスライドを許可する必要があります(たとえば、時間ベースのワンタイムパスワードアルゴリズム[TOTP]を使用)。

キー付きハッシュメッセージ認証コード(HMAC)を計算した後、base-64でそれをエンコードし、状態パラメーターとしてNestクラウドに渡します。

datetimeを使用するPythonの例を次に示します。

 import base64
import datetime
import hmac
import hashlib

def generate_state_parameter(client_id, private_key):
    date = datetime.datetime.today()
    raw_state = str(date) + client_id
    hashed = hmac.new(private_key, raw_state, hashlib.sha1)
    state = base64.b64encode(hashed.digest())
    return (state, date)
 

承認コードのエラーメッセージ

認証コード要求が失敗すると、ユーザーにエラーメッセージが表示されます。これらのメッセージとその防止方法の詳細については、「 Authorization Reference 」を参照してください。

アクセストークンのExchange認証コード

アクセストークンを取得する最後の手順は、取得した認証コードを使用して製品に要求することです。これは、 "x-www-form-urlencoded" HTTP POSTリクエストを行うことによって行われます。

以下のパラメータをリクエストに含めます。 4つのパラメーターはすべて必須です。

パラメータ説明
クライアントID ステップ1のクライアントID
client_secret ステップ1のクライアントシークレット
コード手順2で受け取った認証コード
grant_type このフィールドの値は常に次のとおりですauthorization_code

各POST呼び出しの前に、新しい認証コードを取得します。これを行うには、認証URLをリロードします。次に、POSTのcodeパラメータを変更して、新しい認証コードを含めます。

コード例(auth)

さまざまな言語の例をご覧ください

郵便配達員の例(auth)

PostmanはOAuthリクエストをテストする簡単な方法を提供します。

[ ヘッダー ]タブで、Content-Type = application/x-www-form-urlencodedます。

アクセストークンを取得するPOSTヘッダー

[ ボディ ]タブで、次のkey:valueペアを含めます。

アクセストークンを取得するPOST本文

アクセストークンの応答

リクエストが成功すると、次のフィールドを含むJSONオブジェクトが返されます。

  • access_token —ユーザーのアクセストークン。この値は安全に保つ必要があります。
  • expires_in —要求された時点から、トークンが期限切れになるまでの残り秒数。

アクセストークンのエラーメッセージ

リクエストが失敗した場合、HTTPステータスコードの形式でエラーを受け取ります。これらのエラーの詳細とそれらを防ぐ方法については、 Authorization Referenceを参照してください。

認証されたリクエストを行う

製品はアクセストークンを取得した後、そのトークンをHTTP認証ヘッダーでNest APIに送信します。トークンをURIクエリ文字列パラメーターとして送信することは可能ですが、URIパラメーターは完全に保護されていないログファイルになる可能性があるため、お勧めしません。

アクセストークンは、トークンリクエストのスコープに記述されている一連の操作とリソースに対してのみ有効です。たとえば、Nest Thermostat APIに対してアクセストークンが発行された場合、Nest Camera APIへのアクセスは許可されません。

コード例(読み取り/書き込み)

郵便配達員の例(読み取り/書き込み)

Postmanは、Content-Type = application/jsonを使用してAPI呼び出しをテストする簡単な方法を提供します。

データを読み取るためのGET

無効なトークン

無効なトークンを使用してAPI呼び出しを行うと、サーバーから401 Unauthorized応答が返されます。次の理由により、トークンが無効であり、再生成が必要な場合があります。

  • 期限切れです
  • ユーザーが製品に最初に付与した権限を取り消しました

ユーザーを認証ワークフローの最初にリダイレクトして、401 Unauthorizedエラーを適切に処理するように製品をコーディングすることが重要です。

Nest接続を閉じて動作します

ユーザーがWorks with Nest接続を削除する 、製品はauth_revokedイベントを受け取り、接続が閉じます。