テレビや制限付き入力デバイス アプリケーション用の 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 トークンを使用して基本的なユーザー プロフィール情報を取得する場合は、テレビと制限付き入力デバイスでのログインをご覧ください。

Prerequisites

プロジェクトで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: デバイスとユーザーコードをリクエストする

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

パラメータ
client_id	必須 アプリケーションのクライアント ID。この値は、 API Console Credentials 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_code と user_code の有効時間（秒）。その間にユーザーが承認フローを完了しておらず、ユーザーの判断に関する情報をポーリングしてもデバイスがポーリングしない場合は、ステップ 1 からこのプロセスを再開する必要があります。
interval	デバイスがポーリング リクエスト間の待機時間（秒）。たとえば、値が 5 の場合、デバイスは 5 秒ごとに Google の承認サーバーにポーリング リクエストを送信します。詳しくは、ステップ 3 をご覧ください。
user_code	アプリケーションがアクセスをリクエストするスコープを Google に知らせる大文字と小文字を区別する値。ユーザー インターフェースは、より豊富な入力機能を備えた別のデバイスでこの値を入力するようにユーザーに指示するようになります。Google はこの値を使用して、アプリケーションへのアクセス権を付与するようにユーザーに促すときに正しいスコープのセットを表示します。
verification_url	user_code に移動してアプリへのアクセスを許可または拒否するために、ユーザーが別のデバイスで移動する必要がある URL。ユーザー インターフェースにもこの値が表示されます。

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

{
  "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 が有効であるため、user_code の UI での表示をテストする際に、その文字列値を使用することをおすすめします。
  • user_code では大文字と小文字が区別されます。大文字と小文字の変更や、その他の書式設定文字の挿入など、いかなる方法でも変更しないでください。
• verification_url
  • verification_url を表示するスペースは、40 文字の長さの URL 文字列を処理するのに十分な幅が必要です。
  • オプションで verification_url を変更しないでください。ただし、オプションで表示用のスキームを削除します。表示上の理由から URL からスキーム（https:// など）を削除する場合は、アプリが http と https の両方のバリアントを処理できるようにしてください。

警告: これらの値はいずれも変更される可能性があります。どちらの値もコードにハードコードしないでください。同様に、verification_url からスキームを削除する以外は、値を変更しないでください。

ステップ 4: Google の認可サーバーにアンケートを実施する

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

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

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

パラメータ
client_id	アプリケーションのクライアント ID。この値は、 API Console Credentials pageで確認できます。
client_secret	指定された client_id のクライアント シークレット。この値は、 API Console Credentials pageで確認できます。
device_code	ステップ 2 で認可サーバーから返された device_code。
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" \
         https://oauth2.googleapis.com/token

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

注: 前の手順で説明したように、アプリケーションはこの段階で認可サーバーをポーリングする以外、何もする必要はありません。

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

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

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

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

アクセス権が付与されました

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

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

フィールド
access_token	Google API リクエストの承認用にアプリケーションが送信するトークン。
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"
}

その他のエラー

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

エラー	HTTP ステータス コード	説明
admin_policy_enforced	400	Google Workspace 管理者のポリシーにより、リクエストされた 1 つ以上のスコープを Google アカウントが承認できません。OAuth クライアント ID へのアクセスが明示的に許可されるまで、管理者がスコープへのアクセスを制限する方法について詳しくは、Google Workspace 管理者用ヘルプのヘルプ記事「Google Workspace のデータにアクセスできるサードパーティ製アプリと内部アプリを制御する」をご覧ください。
invalid_client	401	OAuth クライアントが見つかりませんでした。たとえば、client_id パラメータ値が無効な場合にこのエラーが発生します。 OAuth クライアント タイプが正しくありません。クライアント ID のアプリケーション タイプが TV と制限付き入力デバイスに設定されていることを確認します。
invalid_grant	400	code パラメータ値が無効です。すでに申請されているか、解析できません。
unsupported_grant_type	400	grant_type パラメータ値が無効です。
org_internal	403	リクエスト内の OAuth クライアント ID は、特定の Google Cloud 組織内の Google アカウントへのアクセスを制限するプロジェクトの一部です。OAuth アプリケーションのユーザータイプ構成を確認します。

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

アクセス トークンを更新するために、アプリケーションは、次のパラメータを含む HTTPS POST リクエストを Google の承認サーバー（https://oauth2.googleapis.com/token）に送信します。

フィールド
client_id	API Consoleから取得したクライアント ID。
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 つずつ、すべてのクライアントで 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 フローは、次のスコープでのみサポートされています。

OpenID Connect、Google ログイン

• email
• openid
• profile

Drive 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