TVおよび制限付き入力デバイスアプリケーション用のOAuth2.0

このドキュメントでは、テレビ、ゲームコンソール、プリンターなどのデバイスで実行されているアプリケーションを介してGoogleAPIにアクセスするためのOAuth2.0認証を実装する方法について説明します。より具体的には、このフローは、ブラウザにアクセスできないか、入力機能が制限されているデバイス向けに設計されています。

OAuth 2.0を使用すると、ユーザーはユーザー名、パスワード、その他の情報を非公開にしながら、特定のデータをアプリケーションと共有できます。たとえば、TVアプリケーションはOAuth 2.0を使用して、Googleドライブに保存されているファイルを選択する権限を取得できます。

このフローを使用するアプリケーションは個々のデバイスに配布されるため、アプリは秘密を保持できないと想定されます。ユーザーがアプリを使用しているとき、またはアプリがバックグラウンドで実行されているときに、GoogleAPIにアクセスできます。

代替案

あなたは、ブラウザと完全な入力機能へのアクセスを持っている(ユニバーサルWindowsのプラットフォームを含む)のAndroid、iOSの、MacOSの、Linux、またはWindowsのようなプラットフォームのためのアプリケーションを、作成している場合は、使用モバイルおよびデスクトップアプリケーション用のOAuth 2.0フローを。 (アプリがグラフィカルインターフェイスのないコマンドラインツールであっても、このフローを使用する必要があります。)

前提条件

プロジェクトのAPIを有効にする

GoogleのAPIを呼び出す任意のアプリケーションがでこれらのAPIを有効にする必要があります API Console。

プロジェクトのAPIを有効にするには:

  1. Open the API Library で Google API Console。
  2. If prompted, select a project, or create a new one.
  3. API Library 製品ファミリと人気によってグループ化されたリストのすべての利用可能なAPI、。有効にするAPIが一覧で表示されていない場合は、使用した検索は、それを見つけるか、それが属する製品ファミリですべて表示をクリックします。
  4. 有効にするAPIを選択して、[有効]ボタンをクリックしてください。
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

承認資格情報を作成する

OAuth2.0を使用してGoogleAPIにアクセスするアプリケーションには、GoogleのOAuth2.0サーバーに対してアプリケーションを識別する認証資格が必要です。次の手順では、プロジェクトのクレデンシャルを作成する方法について説明します。その後、アプリケーションは資格情報を使用して、そのプロジェクトで有効にしたAPIにアクセスできます。

  1. Go to the Credentials page.
  2. >のOAuthクライアントIDを認証情報を作成]をクリックします。
  3. テレビやリミテッド入力デバイスのアプリケーションの種類を選択します。
  4. あなたのOAuth 2.0のクライアントに名前を付けて、[作成]をクリックします。

アクセス範囲を特定する

スコープを使用すると、アプリケーションは必要なリソースへのアクセスのみを要求できると同時に、ユーザーはアプリケーションに付与するアクセスの量を制御できます。したがって、要求されたスコープの数とユーザーの同意を得る可能性の間には反比例の関係がある可能性があります。

OAuth 2.0承認の実装を開始する前に、アプリがアクセスするためにアクセス許可を必要とするスコープを特定することをお勧めします。

参照可スコープのインストール済みのアプリケーションやデバイスのためのリストを。

OAuth2.0アクセストークンの取得

アプリケーションが入力機能が制限されたデバイスで実行されている場合でも、この認証フローを完了するには、ユーザーはより豊富な入力機能を備えたデバイスに個別にアクセスできる必要があります。フローには次のステップがあります。

  1. アプリケーションは、アプリケーションがアクセス許可を要求するスコープを識別するリクエストをGoogleの承認サーバーに送信します。
  2. サーバーは、デバイスコードやユーザーコードなど、後続の手順で使用されるいくつかの情報で応答します。
  3. ユーザーがアプリを承認するために別のデバイスに入力できる情報を表示します。
  4. アプリケーションは、ユーザーがアプリを承認したかどうかを判断するために、Googleの承認サーバーのポーリングを開始します。
  5. ユーザーは、より豊富な入力機能を備えたデバイスに切り替え、Webブラウザーを起動し、手順3で表示されたURLに移動し、手順3でも表示されたコードを入力します。ユーザーはアプリケーションへのアクセスを許可(または拒否)できます。
  6. ポーリングリクエストへの次の応答には、アプリがユーザーに代わってリクエストを承認するために必要なトークンが含まれています。 (ユーザーがアプリケーションへのアクセスを拒否した場合、応答にはトークンが含まれていません。)

次の画像は、このプロセスを示しています。

ユーザーは、ブラウザーを備えた別のデバイスにログインします

次のセクションでは、これらの手順について詳しく説明します。デバイスが有していてもよい機能とランタイム環境の範囲を考えると、この文書に示されている例が使用curlコマンドラインユーティリティを。これらの例は、さまざまな言語やランタイムに簡単に移植できるはずです。

ステップ1:デバイスとユーザーコードをリクエストする

このステップでは、お使いのデバイスがで、Googleの承認サーバーにHTTP POSTリクエストを送信しhttps://oauth2.googleapis.com/device/code識別し、アプリケーションだけでなく、アクセスは、アプリケーションがユーザの上でアクセスしたいとスコープという、に代わって。あなたはからこのURLを取得する必要がありますディスカバリーの文書使っdevice_authorization_endpointメタデータ値を。次のHTTPリクエストパラメータを含めます。

パラメーター
client_id必須

アプリケーションのクライアントID。あなたには、この値を見つけることができ API ConsoleCredentials page

scope必須

アプリケーションがユーザーに代わってアクセスできるリソースを識別するスコープのスペース区切りのリスト。これらの値は、Googleがユーザーに表示する同意画面に通知します。参照可スコープのインストール済みのアプリケーションやデバイスのためのリストを。

スコープを使用すると、アプリケーションは必要なリソースへのアクセスのみを要求できると同時に、ユーザーはアプリケーションに付与するアクセスの量を制御できます。したがって、要求されたスコープの数とユーザーの同意を得る可能性の間には反比例の関係があります。

次のスニペットは、サンプルリクエストを示しています。

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=email%20profile

この例が示すcurl同じリクエストを送信するためのコマンド:

curl -d "client_id=client_id&scope=email%20profile" \
     https://oauth2.googleapis.com/device/code

ステップ2:許可サーバーの応答を処理する

許可サーバーは、次のいずれかの応答を返します。

成功への対応

リクエストが有効な場合、レスポンスは次のプロパティを含むJSONオブジェクトになります。

プロパティ
device_code承認をリクエストするアプリを実行するデバイスを識別するためにGoogleが一意に割り当てる値。ユーザーは、より豊富な入力機能を備えた別のデバイスからそのデバイスを承認します。たとえば、ユーザーはラップトップや携帯電話を使用して、テレビで実行されているアプリを承認する場合があります。この場合、 device_codeテレビを識別します。

このコードにより、アプリを実行しているデバイスは、ユーザーがアクセスを許可したか拒否したかを安全に判断できます。

expires_in時間の長さは、秒単位で、ということdevice_codeuser_code有効です。その間に、ユーザーが認証フローを完了せず、デバイスがユーザーの決定に関する情報を取得するためにポーリングも行わない場合は、手順1からこのプロセスを再開する必要があります。
intervalデバイスがポーリング要求間で待機する時間の長さ(秒単位)。値がある場合たとえば、 5 、お使いのデバイスには、Googleの承認サーバー5秒ごとにポーリング要求を送信する必要があります。参照してください。ステップ3の詳細については。
user_codeアプリケーションがアクセスを要求しているスコープをGoogleに識別する大文字と小文字を区別する値。ユーザーインターフェイスは、より豊富な入力機能を備えた別のデバイスにこの値を入力するようにユーザーに指示します。次に、Googleはその値を使用して、アプリケーションへのアクセスを許可するようにユーザーに求めるときに、正しいスコープのセットを表示します。
verification_urlユーザーが入力するように、別のデバイスに、に移動しなければならないことをURL user_codeや助成金をしたり、アプリケーションへのアクセスを拒否します。ユーザーインターフェイスにもこの値が表示されます。

次のスニペットは、サンプルの応答を示しています。

{
  "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code": "GQVQ-JKEC",
  "verification_url": "https://www.google.com/device",
  "expires_in": 1800,
  "interval": 5
}

クォータが応答を超えました

デバイスコードリクエストがクライアントIDに関連付けられたクォータを超えた場合、次のエラーを含む403レスポンスを受け取ります。

{
  "error_code": "rate_limit_exceeded"
}

その場合は、バックオフ戦略を使用してリクエストの割合を減らします。

ステップ3:ユーザーコードを表示する

表示verification_urluser_codeユーザに工程2で得られています。どちらの値にも、US-ASCII文字セットの印刷可能な文字を含めることができます。あなたがユーザーに表示することを内容がにナビゲートするためのユーザー指示する必要がありverification_url別のデバイス上と入力しますuser_code

次のルールを念頭に置いて、ユーザーインターフェイス(UI)を設計します。

  • user_code
    • user_code 15「W」のサイズの文字を扱うことができるフィールドに表示されなければなりません。言い換えれば、あなたはコードを表示できる場合WWWWWWWWWWWWWWW正しく、あなたのUIが有効であり、道テストするとき、私たちは、その文字列値を使用することをお勧めしuser_codeあなたのUIで表示されます。
    • user_code大文字と小文字が区別され、そのような場合の変更や他の書式文字を挿入するように、任意の方法で変更されるべきではありません。
  • verification_url
    • あなたが表示スペースverification_url 40文字の長さのURL文字列を処理するのに十分な幅でなければなりません。
    • あなたは変更しないでくださいverification_url 、必要に応じて表示するためのスキームを削除する場合を除き、どのような方法で。あなたが(例えばスキームを取り除くために計画した場合はhttps:// )表示上の理由からURLを、必ずあなたのアプリは、両方扱うことができることがhttphttps変種を。

ステップ4:Googleの認証サーバーをポーリングする

ユーザがナビゲートするために別の装置を使用するためverification_url及び許可(または拒否)アクセスするとき、ユーザ応答のアクセス要求に対して、要求側デバイスは自動的に通知されません。そのため、リクエスト元のデバイスは、ユーザーがリクエストに応答したタイミングを判断するために、Googleの認証サーバーをポーリングする必要があります。

要求側デバイスは、ユーザがアクセス要求に応答するまで、またはしたことを示す応答を受信するまでポーリング要求を送信し続けるべきdevice_codeuser_codeで得ステップ2が満了しているが。 interval要求間に待機する、秒単位で、ステップ2指定の時間の量を返しました。

投票へのエンドポイントのURLですhttps://oauth2.googleapis.com/token 。ポーリング要求には、次のパラメーターが含まれています。

パラメーター
client_idアプリケーションのクライアントID。あなたには、この値を見つけることができ API ConsoleCredentials page
client_secret提供のためのクライアントシークレットclient_id 。あなたには、この値を見つけることができ API ConsoleCredentials page
device_code device_codeに認証サーバから返されたステップ2
grant_typeこの値を設定しurn:ietf:params:oauth:grant-type:device_code

次のスニペットは、サンプルリクエストを示しています。

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

client_id=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

この例が示すcurl同じリクエストを送信するためのコマンド:

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         /token

ステップ5:ユーザーがアクセス要求に応答する

以下の画像を示し、彼らはに移動したときに、ユーザーが見るものに類似ページverification_urlあなたが表示されていることステップ3

コードを入力してデバイスを接続します

入力後user_codeすでにログインしていない場合、ロギング、Googleにして、ユーザーは以下のような同意画面を見ています:

デバイスクライアントの同意画面の例

ステップ6:ポーリングリクエストへの応答を処理する

Googleの認証サーバーは、次のいずれかの応答で各ポーリング要求に応答します。

アクセスが許可されました

ユーザーが(クリックすることで、デバイスへのアクセスを許可された場合はAllow同意画面上)、そしてレスポンスは、アクセストークンとリフレッシュトークンが含まれています。トークンがためにあなたのデバイスを有効GoogleのAPIにアクセスユーザーに代わってを。 ( scope応答内のプロパティは、デバイスがアクセスできるAPIを決定します。)

この場合、API応答には次のフィールドが含まれます。

田畑
access_tokenアプリケーションがGoogleAPIリクエストを承認するために送信するトークン。
expires_inアクセストークンの残りの有効期間(秒単位)。
refresh_token新しいアクセストークンを取得するために使用できるトークン。更新トークンは、ユーザーがアクセスを取り消すまで有効です。更新トークンは常にデバイスに対して返されることに注意してください。
scopeアクセスのスコープは、によって付与されたaccess_tokenスペース区切り、大文字と小文字を区別した文字列のリストとして表現します。
token_type返されるトークンのタイプ。この時点では、このフィールドの値は常にに設定されているBearer

次のスニペットは、サンプルの応答を示しています。

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

アクセストークンの有効期間は限られています。アプリケーションが長期間に渡ってAPIにアクセスする必要がある場合は、それができるリフレッシュトークンを使用する新しいアクセストークンを取得します。アプリケーションでこのタイプのアクセスが必要な場合は、後で使用できるように更新トークンを保存する必要があります。

アクセス拒否

ユーザがデバイスにアクセスを許可することを拒否した場合、サーバ応答が持つ403 HTTPレスポンスステータスコード( Forbidden )。応答には次のエラーが含まれています。

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

承認待ち

ユーザーはまだ承認フローを完了していない場合、サーバーは返し428 HTTP応答ステータスコード( Precondition Required )。応答には次のエラーが含まれています。

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

ポーリングが多すぎる

デバイスは、あまりにも頻繁にポーリング要求を送信した場合、サーバは返し403 HTTPレスポンスのステータスコード( Forbidden )。応答には次のエラーが含まれています。

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

その他のエラー

ポーリング要求に必要なパラメーターがないか、パラメーター値が正しくない場合にも、許可サーバーはエラーを返します。これらの要求は、通常は持っている400Bad Request )または401Unauthorized )HTTPレスポンスのステータスコードを。これらのエラーは次のとおりです。

エラーHTTPステータスコード説明
invalid_client 401 OAuthクライアントが見つかりませんでした。たとえば、このエラーが発生するclient_idパラメータ値が無効です。
invalid_grant 400 codeパラメータ値が無効です。
unsupported_grant_type 400 grant_typeパラメータ値が無効です。

GoogleAPIの呼び出し

アプリケーションがアクセストークンを取得した後、APIに必要なアクセス範囲が許可されている場合は、トークンを使用して、特定のユーザーアカウントに代わってGoogleAPIを呼び出すことができます。これを行うには、いずれかを含むことにより、APIへのリクエストにアクセストークン含むaccess_token 、クエリパラメータまたはAuthorization HTTPヘッダーBearer値。クエリ文字列はサーバーログに表示される傾向があるため、可能な場合はHTTPヘッダーを使用することをお勧めします。ほとんどの場合、あなたは、GoogleのAPIへのあなたの通話を設定するには、クライアントライブラリを使用することができます(例えば、時にドライブのファイルAPIを呼び出します)。

あなたはすべてのGoogleのAPIを試してみるとで彼らのスコープを表示することができOAuth 2.0の遊び場

HTTPGETの例

呼び出しdrive.filesエンドポイント(ドライブファイルのAPI)を使用してAuthorization: Bearer HTTPヘッダーには、次のようになります。独自のアクセストークンを指定する必要があることに注意してください。

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

ここで使用して認証されたユーザーのために、同じAPIの呼び出しですaccess_token 、クエリ文字列パラメータは:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl

あなたがこれらのコマンドをテストすることができcurlコマンドラインアプリケーション。 HTTPヘッダーオプションを使用する例を次に示します(推奨)。

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

または、代わりに、クエリ文字列パラメータオプション:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

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

アクセストークンは定期的に期限切れになり、関連するAPIリクエストの無効なクレデンシャルになります。トークンに関連付けられたスコープへのオフラインアクセスを要求した場合は、ユーザーに許可を求めるプロンプトを表示せずに(ユーザーが存在しない場合を含めて)アクセストークンを更新できます。

アクセストークンを更新するには、アプリケーションはHTTPS送信POST Googleの承認サーバーへの要求( https://oauth2.googleapis.com/token次のパラメータが含まれます):

田畑
client_id取得したクライアントID API Console
client_secret取得したクライアントシークレット API Console
grant_type OAuth 2.0の仕様で定義され、このフィールドの値に設定する必要がありますrefresh_token
refresh_token認証コード交換から返された更新トークン。

次のスニペットは、サンプルリクエストを示しています。

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

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

ユーザーがアプリケーションに付与されたアクセスを取り消していない限り、トークンサーバーは新しいアクセストークンを含むJSONオブジェクトを返します。次のスニペットは、サンプルの応答を示しています。

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

発行される更新トークンの数には制限があることに注意してください。クライアント/ユーザーの組み合わせごとに1つの制限、およびすべてのクライアントにわたるユーザーごとに別の制限。更新トークンは長期保存に保存し、有効である限り使用し続ける必要があります。アプリケーションが要求する更新トークンが多すぎると、これらの制限に達する可能性があります。その場合、古い更新トークンは機能しなくなります。

トークンを取り消す

場合によっては、ユーザーはアプリケーションに与えられたアクセスを取り消すことができます。ユーザーが訪問してアクセスを取り消すことができるアカウント設定を。参照してください。アカウントへのアクセス権を持つサードパーティのサイト&アプリを削除サイトやアプリのアクセスセクションを詳細については、サポートドキュメント。

アプリケーションが、与えられたアクセスをプログラムで取り消すことも可能です。プログラムによる失効は、ユーザーが登録を解除したり、アプリケーションを削除したり、アプリに必要なAPIリソースが大幅に変更されたりした場合に重要です。つまり、削除プロセスの一部にAPIリクエストを含めて、アプリケーションに以前に付与された権限が確実に削除されるようにすることができます。

プログラムでトークンを取り消すには、あなたのアプリケーションがに要求を行いhttps://oauth2.googleapis.com/revoke 、パラメータとしてトークンが含まれています。

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

トークンは、アクセストークンまたは更新トークンにすることができます。トークンがアクセストークンであり、対応する更新トークンがある場合、更新トークンも取り消されます。

失効が正常に処理された場合、レスポンスのHTTPステータスコードがある200 。エラー状態のために、HTTPステータスコード400エラーコードとともに返されます。

許可されたスコープ

デバイスのOAuth2.0フローは、次のスコープでのみサポートされます。

OpenIDを接続しGoogleのサインイン

  • email
  • openid
  • profile

ドライブAPI

  • https://www.googleapis.com/auth/drive.appdata
  • https://www.googleapis.com/auth/drive.file

YouTube API

  • https://www.googleapis.com/auth/youtube
  • https://www.googleapis.com/auth/youtube.readonly