このページは Cloud Translation API によって翻訳されました。

テレビや制限付き入力デバイスアプリケーション用の 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 を有効にするには:

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

承認認証情報を作成する

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

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

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

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

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

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

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

入力機能が制限されたデバイス上でアプリが実行される場合でも、ユーザーは、この認証フローを完了するには入力機能豊富なデバイスへのアクセス権を個別に持つ必要があります。フローには次の手順を行います。

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

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

以降のセクションでは、これらの手順について詳しく説明します。デバイスで利用できる機能やランタイム環境の範囲を考慮すると、このドキュメントの例では 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" \
         /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 フローは、次のスコープでのみサポートされています。

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

テレビや制限付き入力デバイス アプリケーション用の OAuth 2.0

テレビや制限付き入力デバイスアプリケーション用の OAuth 2.0