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

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

このドキュメントでは、アクセスに対する 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 を有効にするには:

Open the API Library Google API Console。
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 にアクセスするアプリケーションには、認証情報が必要です。アプリケーションを識別する 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 リクエストを含めます。 parameters:

パラメータ

パラメータ
`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` の場合、デバイスは認証サーバーと通信します詳しくは、ステップ 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: ユーザーコードを表示する

手順 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 は、任意で変更する場合を除き、いかなる方法でも変更しないでください。表示のスキームが削除されます。スキームを廃止する予定がある場合（例: https://）を URL から呼び出す場合は、アプリが処理できることを確認してください。 http と https の両方のバリエーション。

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

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

ユーザーは別のデバイスを使用して verification_url に移動するためアクセスを許可（または拒否）しても、リクエスト元のデバイスには、リクエストに応答します。そのため、リクエスト元のデバイスは Google の認可サーバーに送信して、ユーザーがリクエストに応答したかどうかを判断します。

リクエスト元のデバイスは、レスポンスを受信するまでポーリングリクエストを送信し続ける必要があります。これは、ユーザーがアクセスリクエストに応答したか、device_code および user_code がで取得されましたステップ 2 の有効期限が切れています。手順 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`	認可サーバーから返される `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" \
         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:

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

その他のエラー

ポーリングリクエストに必須のものがない場合も、認可サーバーはエラーを返します。含まれていない可能性があります。通常、これらのリクエストには 400 が含まれます。（Bad Request）または 401（Unauthorized）の HTTP レスポンスステータスできます。次のようなエラーがあります。

エラー	HTTP ステータスコード	説明
`admin_policy_enforced`	`400`	次のエラーにより、Google アカウントはリクエストされた 1 つ以上のスコープを承認できませんポリシーを管理できます。Google Workspace 管理者用ヘルプを見る記事内部アプリが Google Workspace データにアクセスするをご覧ください。 OAuth へのアクセス権が明示的に付与されるまで、管理者はスコープへのアクセスを制限できるできます。
`invalid_client`	`401`	OAuth クライアントが見つかりませんでした。たとえば、このエラーは `client_id` パラメータ値が無効です。 OAuth クライアントタイプが正しくありません。必ず、アプリケーションタイプ」が「TVs and Limited Input devices」に設定されていることを確認します。
`invalid_grant`	`400`	`code` のパラメータ値が無効か、すでに申請されているか、使用できません表示されます。
`unsupported_grant_type`	`400`	`grant_type` パラメータ値が無効です。
`org_internal`	`403`	リクエスト内の OAuth クライアント ID が、Google アカウントへのアクセスを制限するプロジェクトの一部である特定の <ph type="x-smartling-placeholder"></ph> Google Cloud 組織。以下を確認します。ユーザーの種類 OAuth アプリケーションの構成を使用します。

Google API の呼び出し

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

すべての Google API を試して、 OAuth 2.0 Playground。

HTTP GET の例

呼び出しは、 <ph type="x-smartling-placeholder"></ph> drive.files エンドポイント（Drive Files API）Authorization: Bearer HTTP を使用次のようになります。独自のアクセストークンを指定する必要があります。

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 つずつ異なる組み合わせで作成できます更新トークンを保存する必要がある保持され、有効な間は継続して使用できます。アプリケーションがリクエストが多すぎると、これらの上限に達する可能性があります。その場合、古い更新トークン動作しなくなります。

トークンの取り消し

アプリケーションに付与したアクセス権の取り消しをユーザーが希望する場合があります。ユーザーはアクセス権を取り消すことができます <ph type="x-smartling-placeholder"></ph>にアクセスアカウント設定。詳しくは、削除第三者のサイトやアプリの [サイトまたはアプリのアクセス] セクションでアカウントにアクセスできるアプリサポートドキュメントをご覧ください。

また、アプリケーションに付与されているアクセス権をプログラムで取り消すこともできます。プログラムによる取り消しは、ユーザーが登録解除を行ったり、 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

クロスアカウント保護機能の実装

ユーザーのプライバシー保護のためにクロスアカウントの実装が Google のクロスアカウント保護サービスを利用して保護します。このサービスを使用すると、セキュリティ・イベント通知をサブスクライブして、ユーザーアカウントに大幅な変更が加えられる可能性があります。その後、状況に応じて、この情報を使用して決める方法を決めることです。

Google のクロスアカウント保護サービスからアプリに送信されるイベントタイプの例を以下に示します。

https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
https://schemas.openid.net/secevent/oauth/event-type/token-revoked
https://schemas.openid.net/secevent/risc/event-type/account-disabled

詳しくは、 <ph type="x-smartling-placeholder"></ph> クロスアカウント保護ページでユーザーアカウントを保護するをご覧ください。

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

前提条件

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

承認認証情報を作成する

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

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

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

例

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

成功のレスポンス

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

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

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

例

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

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

アクセスを許可しました

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

承認が保留中です

ポーリングの頻度が多すぎる

その他のエラー

Google API の呼び出し

HTTP GET の例

curl の例

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

トークンの取り消し

許可されるスコープ

OpenID Connect Google ログイン

Drive API

YouTube API

クロスアカウント保護機能の実装

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

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

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

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

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

`curl` の例

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