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

このドキュメントでは、テレビ、ゲーム機、プリンタなどのデバイスで実行されるアプリを介して YouTube Data API にアクセスするための 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 を有効にする必要があります。

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

  1. の 。
  2. [ライブラリ] ページで、YouTube Data API を見つけて有効にします。アプリケーションで使用する他の API を見つけて、それらも有効にします。

承認認証情報を作成する

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

  1. [認証情報を作成] > [OAuth クライアント ID] をクリックします。
  2. アプリケーションの種類として [テレビと入力が限られたデバイス] を選択します。
  3. OAuth 2.0 クライアントに名前を付けて、[作成] をクリックします。

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

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

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

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

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

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

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

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

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

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

ユーザーがブラウザを搭載した別のデバイスでログインする

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

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

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

パラメータ
client_id 必須

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

scope 必須

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

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

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

スコープ
https://www.googleapis.com/auth/youtubeYouTube アカウントの管理
https://www.googleapis.com/auth/youtube.channel-memberships.creator現在アクティブなチャンネル メンバー、メンバーの現在のレベル、いつメンバーになったかをリストで確認する
https://www.googleapis.com/auth/youtube.force-sslYouTube 動画、評価、コメント、字幕の表示、編集、完全削除
https://www.googleapis.com/auth/youtube.readonlyYouTube アカウントの表示
https://www.googleapis.com/auth/youtube.uploadYouTube 動画の管理
https://www.googleapis.com/auth/youtubepartnerYouTube のアセットや関連するコンテンツの表示と管理
https://www.googleapis.com/auth/youtubepartner-channel-auditYouTube パートナーの監査プロセス時に関連する 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%2Fyoutube.readonly

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

curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly" \
     https://oauth2.googleapis.com/device/code

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

認可サーバーは、次のいずれかのレスポンスを返します。

成功のレスポンス

リクエストが有効な場合、レスポンスは次のプロパティを含む JSON オブジェクトになります。

プロパティ
device_code 承認をリクエストするアプリを実行しているデバイスを識別するために Google が一意に割り当てる値。ユーザーは、入力機能が豊富な別のデバイスからそのデバイスを承認します。たとえば、ユーザーがラップトップやスマートフォンを使用して、テレビで実行されているアプリを承認する場合があります。この場合、device_code はテレビを識別します。

このコードにより、アプリを実行しているデバイスは、ユーザーがアクセスを許可したかどうかを安全に判断できます。

expires_in device_codeuser_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_urluser_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:// など)を削除する場合は、アプリが httphttps の両方のバリエーションを処理できることを確認してください。

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

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

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

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

パラメータ
client_id アプリケーションのクライアント ID。この値は、 にあります。
client_secret 指定された client_id のクライアント シークレット。この値は、 にあります。
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"
}

その他のエラー

また、ポーリング リクエストに必須パラメータが含まれていない場合や、パラメータ値が正しくない場合には、認可サーバーはエラーを返します。通常、これらのリクエストには 400Bad Request)または 401Unauthorized)の HTTP レスポンス ステータス コードが付いています。たとえば次のようなエラーです。

エラー HTTP ステータス コード 説明
admin_policy_enforced 400 Google Workspace 管理者のポリシーにより、リクエストされた 1 つ以上のスコープを Google アカウントが承認できません。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 の呼び出し

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

YouTube Data API は、複数の YouTube チャンネルを所有して管理している YouTube コンテンツ所有者(レコード レーベルや映画制作会社など)のサービス アカウントのみをサポートしています。

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

HTTP GET の例

Authorization: Bearer HTTP ヘッダーを使用して youtube.channels エンドポイント(YouTube Data API)を呼び出すと、次のようになります。独自のアクセス トークンを指定する必要があります。

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

curl の例

これらのコマンドは、curl コマンドライン アプリケーションでテストできます。HTTP ヘッダー オプションを使用する例を次に示します(推奨)。

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

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

アクセス トークンは定期的に期限が切れ、関連する API リクエストに対して無効な認証情報になります。トークンに関連付けられたスコープへのオフライン アクセスをリクエストした場合は、ユーザーに権限を求めることなくアクセス トークンを更新できます(ユーザーが不在の場合を含めて)。

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

フィールド
client_id から取得したクライアント ID。
client_secret から取得したクライアント シークレット。
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 ConnectGoogle ログイン

  • 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

クロスアカウント保護の実装方法と利用可能なイベントの一覧については、 クロスアカウント保護でユーザー アカウントを保護する をご覧ください。