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

このドキュメントでは、テレビ、ゲーム機、プリンタなどのデバイスで実行されているアプリケーションを介して Google API にアクセスするための OAuth 2.0 認証を実装する方法について説明します。具体的には、このフローは、ブラウザにアクセスできないデバイスか、入力機能が制限されているデバイス向けに設計されています。

OAuth 2.0 を使用すると、ユーザー名やパスワードなどの情報を秘密にしたまま、ユーザーが特定のデータをアプリケーションと共有できます。 たとえば、TV アプリケーションで OAuth 2.0 を使用して、Google ドライブに保存されたファイルを選択する権限を取得できます。

このフローを使用するアプリは個々のデバイスに分散されるため、アプリはシークレットを保持できないとみなされます。ユーザーがアプリを使用しているとき、またはアプリがバックグラウンドで実行されているときに、Google API にアクセスできます。

代案

Android、iOS、macOS、Linux、Windows などのプラットフォーム(Universal Windows プラットフォームを含む)向けのアプリを作成する際に、ブラウザへのアクセスとすべての入力機能がある場合は、モバイル アプリケーションとデスクトップ アプリケーション用の OAuth 2.0 フローを使用します。(アプリがグラフィカル インターフェースのないコマンドライン ツールであっても、このフローを使用する必要があります)。

Google アカウントでのみユーザーのログインを行い、JWT ID トークンを使用して基本的なユーザー プロフィール情報を取得する場合は、テレビや入力機能が限られたデバイスでログインするをご覧ください。

前提条件

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

Google API を呼び出すすべてのアプリケーションは、 API Consoleでこれらの API を有効にする必要があります。

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

  1. Google API ConsoleのOpen the API Library
  2. If prompted, select a project, or create a new one.
  3. API Library には、利用可能なすべての API がプロダクト ファミリーと人気度別にグループ化されて一覧表示されます。有効にする API がリストに表示されない場合は、検索を使用して探すか、その API が属するプロダクト ファミリーの [すべて表示] をクリックします。
  4. 有効にする API を選択し、[有効にする] ボタンをクリックします。
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

承認認証情報を作成する

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

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

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

スコープを使用すると、アプリケーションは必要なリソースへのアクセスのみをリクエストできます。また、ユーザーはアプリケーションに付与するアクセス権の量を制御することもできます。そのため、リクエストするスコープの数とユーザーの同意を得る可能性の間には逆の関係がある場合があります。

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

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

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 リクエスト パラメータを含めます。

パラメータ
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_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。この値は 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 を入力し、まだ Google にログインしていない場合は、ユーザーに対して次のような同意画面が表示されます。

デバイス クライアントの同意画面の例

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

Google の承認サーバーは、各ポーリング リクエストに対して次のいずれかのレスポンスを返します。

アクセスを許可しました

ユーザーが同意画面で Allow をクリックしてデバイスへのアクセス権を付与した場合、レスポンスにはアクセス トークンと更新トークンが含まれます。トークンにより、デバイスがユーザーに代わって Google API にアクセスできるようになります。(デバイスがアクセスできる API は、レスポンスの scope プロパティによって決まります)。

この場合、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 アカウントは、Google Workspace 管理者のポリシーによってリクエストされた 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 の呼び出し

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

OAuth 2.0 Playground では、すべての Google API とそのスコープを確認できます。

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 つの制限があります。更新トークンは長期間保存し、有効な間は継続して使用する必要があります。アプリケーションがリクエストする更新トークンが多すぎると、これらの制限に達することがあり、その場合は古い更新トークンが機能しなくなります。

トークンの取り消し

場合によっては、ユーザーがアプリケーションに与えられたアクセス権の取り消しを希望することがあります。ユーザーは アカウント設定にアクセスしてアクセス権を取り消すことができます。詳しくは、サポート ドキュメント「アカウントにアクセスできるサードパーティのサイトやアプリのサイトやアプリのアクセス権の削除」をご覧ください。

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