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 を有効にするには:

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

承認認証情報を作成する

OAuth 2.0 を使用して Google API にアクセスするアプリケーションには、認証情報が必要です。 アプリケーションを識別する API を Google の OAuth 2.0 サーバーに提供します。次の手順では、 プロジェクトの認証情報を作成します。これにより、アプリケーションは認証情報を使用して API にアクセスできるようになります。 有効にする必要があります

  1. Go to the Credentials page.
  2. [認証情報を作成] > [OAuth クライアント ID] をクリックします。
  3. アプリケーション タイプとして [テレビと入力が制限されているデバイス] を選択します。
  4. 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: デバイスとユーザーコードをリクエストする

このステップでは、デバイスから HTTP POST リクエストを Google の承認サーバー( https://oauth2.googleapis.com/device/code: アプリケーションを識別します。 アプリケーションがユーザーの代わりにアクセスする アクセス スコープを指定します。 この URL は、 ディスカバリ ドキュメントに、 device_authorization_endpoint メタデータ値。次の HTTP リクエストを含めます。 parameters:

パラメータ
client_id 必須

アプリケーションのクライアント ID。この値は API Console Credentials page

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.force-ssl

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

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

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

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

成功のレスポンス

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

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

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

expires_in device_codeuser_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_urluser_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 から呼び出す場合は、アプリが処理できることを確認してください。 httphttps の両方のバリエーション。

ステップ 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)または 401Unauthorized)の 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 の呼び出しを設定できます(例: YouTube Live Streaming API の呼び出しをご覧ください)。

YouTube Live Streaming API は、サービス アカウントのフローをサポートしていません。そこで サービス アカウントを YouTube アカウントにリンクすることはできません。これを使用してリクエストを承認しようとします。 NoLinkedYouTubeAccount エラーが生成されます。

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

HTTP GET の例

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

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

次に、access_token を使用して、認証されたユーザーに対して同じ API を呼び出します。 クエリ文字列パラメータ:

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

curl の例

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=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 つずつ 異なる組み合わせで作成できます更新トークンを保存する必要がある 保持され、有効な間は継続して使用できます。アプリケーションが リクエストが多すぎると、これらの上限に達する可能性があります。その場合、古い更新トークン 動作しなくなります。

トークンの取り消し

アプリケーションに付与したアクセス権の取り消しをユーザーが希望する場合があります。ユーザーはアクセス権を取り消すことができます <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 フローは、次のスコープでのみサポートされています。

OpenID Connect Google ログイン

  • 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> クロスアカウント保護ページでユーザー アカウントを保護する をご覧ください。