TV および入力機能が限られたデバイス アプリケーション用の OAuth 2.0

このドキュメントでは、テレビ、ゲーム機、プリンタなどのデバイスで実行されるアプリを介して Google API にアクセスするための OAuth 2.0 認可を実装する方法について説明します。具体的には、このフローは、ブラウザにアクセスできないデバイス、または入力機能が制限されているデバイスを対象としています。

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

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

代替手段

Android、iOS、macOS、Linux、Windows（ユニバーサル Windows プラットフォームを含む）などのプラットフォーム向けに、ブラウザと完全な入力機能にアクセスできるアプリを作成している場合は、モバイルアプリとデスクトップ アプリ用の OAuth 2.0 フローを使用します。（アプリがグラフィカル インターフェースのないコマンドライン ツールであっても、このフローを使用する必要があります）。

ユーザーが Google アカウントでログインし、JWT ID トークンを使用して基本的なユーザー プロフィール情報を取得するのみの場合は、テレビと入力制限のあるデバイスでのログインをご覧ください。

前提条件

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

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

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

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

承認認証情報を作成する

OAuth 2.0 を使用して Google API にアクセスするアプリケーションは、Google の OAuth 2.0 サーバーに対して自身の身元を示す認証情報を持つ必要があります。プロジェクトの認証情報を作成する手順は次のとおりです。アプリケーションは、その認証情報を使用して、そのプロジェクトで有効にした API にアクセスできます。

1. Go to the Credentials page.
2. [認証情報を作成] > [OAuth クライアント ID] をクリックします。
3. アプリケーション タイプとして「テレビと制限付き入力デバイス」を選択します。
4. OAuth 2.0 クライアントに名前を付けて [作成] をクリックします。

アクセス スコープを特定する

スコープを指定すると、アプリケーションからのアクセス要求は必要なリソースのみに限定されるようになり、ユーザーはアプリケーションに付与するアクセスレベルを制御できます。そのため、リクエストされるスコープの数とユーザーの同意を得る可能性の間には逆相関が生じる場合があります。

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

インストール済みのアプリまたはデバイスについては、許可されているスコープのリストをご覧ください。

OAuth 2.0 アクセス トークンの取得

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

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

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

以降のセクションでは、これらの手順について詳しく説明します。デバイスの機能やランタイム環境の範囲を考慮し、このドキュメントの例では、curl コマンドライン ユーティリティを使用します。これらの例は、さまざまな言語やランタイムに簡単に移植できる必要があります。

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

このステップでは、デバイスが Google の認可サーバーに HTTP POST リクエストを送信します。このリクエストには、アプリと、アプリがユーザーに代わってアクセスするアクセス スコープが含まれます。https://oauth2.googleapis.com/device/codeこの URL は、device_authorization_endpoint メタデータ値を使用して、ディスカバリ ドキュメントから取得する必要があります。次の HTTP リクエスト パラメータを含めます。

例

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

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": "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: ユーザーコードを表示する

ステップ 2 で取得した verification_url と user_code をユーザーに表示します。どちらの値にも、US-ASCII 文字セットの印刷可能な文字を含めることができます。ユーザーに表示するコンテンツには、別のデバイスで verification_url に移動して user_code を入力するよう指示する必要があります。

ユーザー インターフェース（UI）を設計する際は、次のルールを念頭に置いてください。

• user_code
  • user_code は、15 個の「W」サイズの文字を処理できるフィールドに表示する必要があります。つまり、コード WWWWWWWWWWWWWWW を正しく表示できる場合、UI は有効です。UI で user_code がどのように表示されるかをテストする際は、その文字列値を使用することをおすすめします。
  • user_code では大文字と小文字が区別されるため、大文字と小文字の変更や他の書式文字の挿入など、いかなる方法でも変更しないでください。
• verification_url
  • verification_url を表示するスペースは、40 文字の URL 文字列を処理できるだけの幅が必要です。
  • verification_url は、表示用のスキーマを必要に応じて削除する場合を除き、いかなる方法でも変更しないでください。表示上の理由から URL からスキーム（https:// など）を削除する場合は、アプリが http バリアントと https バリアントの両方を処理できることを確認してください。

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

ユーザーは別のデバイスを使用して verification_url に移動し、アクセスを許可（または拒否）するため、ユーザーがアクセス リクエストに応答しても、リクエスト元のデバイスには自動的に通知されません。そのため、リクエスト元のデバイスは Google の承認サーバーにポーリングして、ユーザーがリクエストに応答したタイミングを判定する必要があります。

リクエスト元のデバイスは、ユーザーがアクセス リクエストに応答したことを示すレスポンスを受信するか、 ステップ 2 で取得した device_code と user_code が期限切れになるまで、ポーリング リクエストを送信し続けます。ステップ 2 で返された interval には、リクエスト間の待機時間を秒単位で指定します。

ポーリングするエンドポイントの URL は https://oauth2.googleapis.com/token です。ポーリング リクエストには、次のパラメータが含まれます。

例

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

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" \
         https://oauth2.googleapis.com/token

ステップ 5: ユーザーがアクセス リクエストに応答する

次の画像は、ステップ 3 で表示した verification_url にユーザーが移動したときに表示されるページに似ています。

user_code を入力し、Google にログインしていない場合は、次のような同意画面が表示されます。

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

Google の認可サーバーは、各ポーリング リクエストに対して次のいずれかのレスポンスを返します。

アクセスを許可しました

ユーザーがデバイスへのアクセスを許可した場合（同意画面で Allow をクリックした場合）、レスポンスにはアクセス トークンと更新トークンが含まれます。トークンを使用すると、デバイスはユーザーに代わって Google API にアクセスできます。（レスポンスの scope プロパティによって、デバイスがアクセスできる API が決まります）。

この場合、API レスポンスには次のフィールドが含まれます。

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

{
  "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"
}

その他のエラー

また、ポーリング リクエストに必須パラメータが含まれていない場合や、パラメータ値が正しくない場合には、認可サーバーはエラーを返します。通常、これらのリクエストには 400（Bad Request）または 401（Unauthorized）の HTTP レスポンス ステータス コードが付いています。たとえば次のようなエラーです。

Google API の呼び出し

アプリケーションがアクセス トークンを取得すると、API で必要なアクセス権が付与されている場合は、そのトークンを使用して特定のユーザー アカウントの代わりに Google API を呼び出すことができます。これを行うには、access_token クエリ パラメータまたは Authorization HTTP ヘッダー Bearer 値のいずれかを含めて、API へのリクエストにアクセス トークンを含めます。クエリ文字列はサーバーログに表示されるため、可能であれば HTTP ヘッダーを使用することをおすすめします。ほとんどの場合、クライアント ライブラリを使用して Google API への呼び出しを設定できます（Drive Files API を呼び出す場合など）。

すべての Google API を試して、そのスコープを確認するには、OAuth 2.0 Playground をご覧ください。

HTTP GET の例

Authorization: Bearer HTTP ヘッダーを使用して drive.files エンドポイント（Drive Files API）を呼び出す場合、呼び出しは次のようになります。独自のアクセス トークンを指定する必要があります。

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

以下は、access_token クエリ文字列パラメータを使用して、認証済みユーザーの同じ API を呼び出すコードです。

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 リクエストに対して無効な認証情報になります。トークンに関連付けられたスコープへのオフライン アクセスをリクエストした場合は、ユーザーに権限を求めることなくアクセス トークンを更新できます（ユーザーが不在の場合を含めて）。

アクセス トークンを更新するには、アプリケーションが Google の認可サーバーに HTTPS POST リクエストを送信します。このリクエストには、次のパラメータが含まれます。https://oauth2.googleapis.com/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 つ、すべてのクライアントのユーザーごとに 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 が返されます。

許可されるスコープ

デバイスの OAuth 2.0 フローは、次のスコープでのみサポートされています。