このページは 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 を API Consoleで有効にする必要があります。

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

Google API ConsoleのOpen the API Library 。
If prompted, select a project, or create a new one.
API Library には、利用可能なすべての 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 がユーザーに表示する同意画面を通知するものです。インストールされているアプリまたはデバイスについては、許可されたスコープのリストをご覧ください。スコープを使用すると、アプリケーションは必要なリソースへのアクセスのみをリクエストできます。また、ユーザーはアプリケーションに付与するアクセス権の量を制御できます。したがって、リクエストされたスコープの数とユーザーの同意を取得する可能性の間には反比例があります。

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 は有効です。UI で user_code がどのように表示されるかをテストする際に、その文字列値を使用することをおすすめします。
- 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 にログインし、まだログインしていない場合、次のような同意画面が表示されます。

ステップ 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 Drive の呼び出し（たとえば、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 つの上限があり、すべてのクライアントで 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

Prerequisites

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

承認認証情報を作成する

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

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

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

例

ステップ 2: 認証サーバー レスポンスを処理する

成功のレスポンス

割り当て超過のレスポンス

手順 3: ユーザーコードを表示する

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

例

ステップ 5: お客様がアクセス リクエストに応答する

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

アクセスを許可しました

アクセスが拒否されました

承認待ち

アンケートの頻度が多すぎる

その他のエラー

Google API の呼び出し

HTTP GET の例

curl の例

アクセス トークンをリフレッシュする

トークンの取り消し

許可されたスコープ

OpenID Connect、Google ログイン

Drive API

YouTube API

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

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

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

ステップ 2: 認証サーバーレスポンスを処理する

ステップ 5: お客様がアクセスリクエストに応答する

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

`curl` の例

アクセストークンをリフレッシュする