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

TV および入力制限のあるデバイスアプリケーション用の OAuth 2.0

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

OAuth 2.0 では、ユーザー名やパスワードなどの情報を秘密にしたまま、ユーザーが特定のデータをアプリケーションと共有できます。たとえば、テレビアプリケーションは 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 を有効にするには:

Google API ConsoleのOpen the API Library 。
If prompted, select a project, or create a new one.
[ライブラリ] ページで、YouTube Content ID API を見つけて有効にします。アプリで使用する他の API を見つけて、それらも有効にします。

承認認証情報を作成する

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

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

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

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

OAuth 2.0 認証の実装を開始する前に、権限が必要であることを通知します。

YouTube Data API v3 は、次のスコープを使用します。

スコープ
https://www.googleapis.com/auth/youtube	YouTube アカウントの管理
https://www.googleapis.com/auth/youtube.channel-memberships.creator	現在アクティブなチャンネルメンバー、メンバーの現在のレベル、いつメンバーになったかをリストで確認する
https://www.googleapis.com/auth/youtube.force-ssl	YouTube 動画、評価、コメント、字幕の表示、編集、完全削除
https://www.googleapis.com/auth/youtube.readonly	YouTube アカウントの表示
https://www.googleapis.com/auth/youtube.upload	YouTube 動画の管理
https://www.googleapis.com/auth/youtubepartner	YouTube のアセットや関連するコンテンツの表示と管理
https://www.googleapis.com/auth/youtubepartner-channel-audit	YouTube パートナーの監査プロセス時に関連する YouTube チャンネルの個人情報の表示

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

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

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

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

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

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

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

このステップでは、デバイスが Google の認可サーバーに HTTP POST リクエストを送信します。このリクエストには、アプリと、アプリがユーザーに代わってアクセスするアクセススコープが含まれています。この URL は、ディスカバリドキュメントに、 device_authorization_endpoint メタデータ値。次の HTTP リクエストパラメータを含めます。

パラメータ

client_id

必須

アプリケーションのクライアント ID。この値は、 API ConsoleCredentials pageにあります。

scope

必須

アプリケーションがユーザーに代わってアクセスできるリソースを識別するスコープのスペース区切りリスト。これらの値は、Google がユーザーに表示する同意画面に通知されます。詳しくは、インストール済みのアプリまたはデバイスの [許可されているスコープ] のリストです。

スコープを使用すると、アプリケーションは必要なリソースへのアクセスのみをリクエストできるようになります。付与するアクセス権のレベルも制御できます説明します。したがって、リクエストするスコープの数とユーザーの同意を得られる可能性との間には逆相関関係があります。

YouTube Data API v3 では、次のスコープを使用します。

スコープ
https://www.googleapis.com/auth/youtube	YouTube アカウントの管理
https://www.googleapis.com/auth/youtube.channel-memberships.creator	現在アクティブなチャンネルメンバー、メンバーの現在のレベル、いつメンバーになったかをリストで確認する
https://www.googleapis.com/auth/youtube.force-ssl	YouTube 動画、評価、コメント、字幕の表示、編集、完全削除
https://www.googleapis.com/auth/youtube.readonly	YouTube アカウントの表示
https://www.googleapis.com/auth/youtube.upload	YouTube 動画の管理
https://www.googleapis.com/auth/youtubepartner	YouTube のアセットや関連するコンテンツの表示と管理
https://www.googleapis.com/auth/youtubepartner-channel-audit	YouTube パートナーの監査プロセス時に関連する YouTube チャンネルの個人情報の表示

OAuth 2.0 API スコープのドキュメントでは、Google API へのアクセスに使用できるスコープの一覧を確認できます。

例

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

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutubepartner

次の例は、同じリクエストを送信する curl コマンドを示しています。

curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutubepartner" \
     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`	別のデバイスで入力するためにユーザーが移動する必要がある 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 は有効です。UI で user_code を表示する方法のテストでは、その文字列値を使用することをおすすめします。
- 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 ConsoleCredentials 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 つ以上のスコープを承認できませんポリシーを管理できます。OAuth クライアント ID にアクセス権が明示的に付与されるまで、管理者がスコープへのアクセスを制限する方法については、Google Workspace 管理者向けヘルプ記事の Google Workspace のデータにアクセスできるサードパーティ製アプリと内部アプリを制御するをご覧ください。
`invalid_client`	`401`	OAuth クライアントが見つかりませんでした。たとえば、このエラーは `client_id` パラメータ値が無効です。 OAuth クライアントの種類が正しくありません。クライアント ID のアプリケーションタイプが [テレビと入力機能が制限されたデバイス] に設定されていることを確認します。
`invalid_grant`	`400`	`code` のパラメータ値が無効か、すでに申請されているか、使用できません表示されます。
`unsupported_grant_type`	`400`	`grant_type` パラメータの値が無効です。
`org_internal`	`403`	リクエストの OAuth クライアント ID は、特定の Google Cloud 組織の Google アカウントへのアクセスを制限するプロジェクトの一部です。以下を確認します。ユーザーの種類 OAuth アプリケーションの構成を使用します。

Google API の呼び出し

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

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

HTTP GET の例

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

GET /youtubepartner/v1/contentOwners?fetchMine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtubepartner/v1/contentOwners?access_token=access_token&fetchMine=true

`curl` の例

これらのコマンドは、curl コマンドラインアプリケーションでテストできます。こちらが HTTP ヘッダーオプションを使用した例（推奨）:

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtubepartner/v1/contentOwners?fetchMine=true

または、クエリ文字列パラメータオプションを使用します。

curl https://www.googleapis.com/youtubepartner/v1/contentOwners?access_token=access_token&fetchMine=true

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

アクセストークンは定期的に期限切れになり、関連する 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

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

ユーザーのプライバシー保護のためにクロスアカウントの実装が 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> クロスアカウント保護ページでユーザーアカウントを保護するをご覧ください。