この OAuth 2.0 のフローは、入力機能が限定されたゲーム機やビデオ カメラなどのデバイスで実行されるアプリケーション用に設計されています。このフローでは、ユーザーがデバイス上でアプリケーションを操作して、URL とデバイス コードを取得します。ユーザーは次に、コンピュータやスマートフォンなど、入力機能が豊富な別のデバイスに切り替えて、デバイス コードを承認できます。
Important: You need to obtain authorization credentials in the Google Developers Console to be able to use OAuth 2.0 authorization.
This document contains the following sections:
-
The Obtaining OAuth 2.0 access tokens section explains how to obtain OAuth 2.0 access tokens for devices. The Google Accounts Authentication and Authorization documentation also provides complete details for implementing OAuth 2.0 in different types of applications.
-
The Calling the YouTube Data API section explains how to use the OAuth 2.0 tokens that your application obtains to make authorized API requests on a user's behalf.
-
The Client libraries section describes client library support for OAuth 2.0.
Obtaining OAuth 2.0 access tokens
このフローの手順は以下のとおりです。
-
client_id
とclient_secret
をアプリケーションに埋め込むGoogle にアプリケーションを登録して、登録プロセス中に作成された
client ID
とclient secret
をアプリケーションに埋め込みます。どちらの値も Google APIs console に表示されます。 -
デバイス コードをリクエストする
デバイスが
POST
リクエストをhttps://accounts.google.com/o/oauth2/device/code
で Google の承認サーバーに送信します。このリクエストでは以下のパラメータを指定します。パラメータ client_id
必須。アプリケーションの OAuth 2.0 クライアント ID です。 scope
必須。アプリケーションがユーザーの代わりにアクセスできるリソースを特定するスコープのスペース区切りのリストです。 以下のサンプル リクエストは、デバイス コードの取得方法を示しています。
POST /o/oauth2/device/code HTTP/1.1 Host: accounts.google.com Content-Type: application/x-www-form-urlencoded client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com& scope=https://www.googleapis.com/auth/youtube
-
Google からのレスポンスを処理する
Google がデバイスに JSON オブジェクトを返して、リクエストに応答します。サンプルのレスポンスは以下のとおりです。
{ "device_code" : "4/L9fTtLrhY96442SEuf1Rl3KLFg3y", "user_code" : "a9xfwk9c", "verification_url" : "http://www.google.com/device", "expires_in" : "1800" "interval" : 5, }
デバイス上のアプリケーションに、
user_code
とverification_url
が表示されます。アプリケーションは、ステップ 4 で使用するdevice_code
値、expires_in
値、およびinterval
値を格納する必要があります。 -
Google の承認サーバーのポーリングを開始する
ステップ 3 の JSON レスポンスで返された
device_code
を使用して、アプリケーションで Google の承認サーバーのポーリングを開始できます。これには、以下のキーと値のペアを指定して、アプリケーションからPOST
リクエストをhttps://accounts.google.com/o/oauth2/token
に送信します。キー client_id
アプリケーションの OAuth 2.0 クライアント ID です。 client_secret
クライアント ID に関連付けられているクライアント シークレット。この値は Google APIs console に表示されます。 code
デバイス コードはステップ 3 で取得しました。 grant_type
この値は http://oauth.net/grant_type/device/1.0
に設定します。サンプルのポーリング リクエストを以下に示します。ステップ 3 の JSON レスポンスで返された
interval
は、アプリケーションがポーリング リクエスト間に待機する最小秒数を指定します。POST /o/oauth2/token HTTP/1.1 Host: accounts.google.com Content-Type: application/x-www-form-urlencoded client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com& client_secret=hDBmMRhz7eJRsM9Z2q1oFBSem& code=4/YMSlR3fSCC1NtUh073DuZKTJJ3ss& grant_type=http://oauth.net/grant_type/device/1.0
ユーザーがステップ 5 からステップ 7 を完了するまで、アプリケーションはポーリング リクエストごとに以下のレスポンスのどちらか 1 つを受信します。
-
次のレスポンスは、ユーザーが API アクセスをデバイスに承認するためのステップを完了していない場合に表示されます。
{ "error" : "authorization_pending" }
-
次のレスポンスは、アプリケーションがポーリング リクエストを送信する頻度が高すぎることを示しています。
{ "error" : "slow_down" }
-
-
ユーザーが
user_code
を別のブラウザに入力するユーザーがパソコンや携帯電話などの別のデバイスでブラウザを起動し、
verification_url
にアクセスします。この URL はユーザーがステップ 3 で取得したuser_code
を入力できるページを表示します。注:
user_code
は大文字と小文字を区別するため、レスポンスの表示どおり正確に入力する必要があります。 -
ユーザーが Google アカウントにログインする
ユーザーは
user_code
を入力した後、デバイスからの YouTube Data API リクエストを許可するために使用する Google アカウントにログインするように求められます(ログイン済みのユーザーは、次のステップに直接進みます)。 -
ユーザーが同意を決定する
ユーザーがログインした後、Google の承認サーバーは、ユーザーの代わりにアクセスする権限を要求する Google サービスとアプリケーションの名前を表示するページを表示します。ユーザーはアプリケーションへのアクセス権の付与を同意または拒否できます。
-
トークンを取得するためにポーリング·サーバーからのレスポンスを処理する
ユーザーがアプリケーションにアクセス権を付与したら、デバイスが次に送信するポーリング リクエストでは、アクセス トークンと更新トークンを含む JSON オブジェクトが返されます。
{ "access_token":"1/fFAGRNJru1FTz70BzhT3Zg", "expires_in":3920, "token_type":"Bearer", "refresh_token":"1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ" }
重要: アプリケーションはどちらの値も格納する必要があります。
-
アクセス トークンを使用した承認済みリクエストの送信方法については、YouTube Data API の呼び出しセクションを参照してください。
-
アクセス トークンの有効期限が切れた場合に、更新トークンを使用して新しいアクセス トークンを取得する方法については、アクセス トークンの更新セクションを参照してください。
-
YouTube Data API の呼び出し
ユーザーのためにアクセス トークンを取得した後、アプリケーションはトークンを使用して、承認済みの API リクエストをそのユーザーの代わりに送信できます。API はアクセス トークンを指定する方法を 2 種類サポートしています。
-
アクセス トークンを
Authorization: Bearer
HTTP リクエスト ヘッダーの値として指定します。これは推奨される方法です。GET /youtube/v3/channels?part=id&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer ACCESS_TOKEN ...
次のコマンドで cURL を使用して、これをテストできます。
curl -H "Authorization: Bearer ACCESS_TOKEN" https://www.googleapis.com/youtube/v3/channels?part=id&mine=true
-
アクセス トークンを
access_token
クエリ パラメータの値として指定します。https://www.googleapis.com/youtube/v3/channels?part=id&mine=true&access_token=ACCESS_TOKEN
次のコマンドで cURL を使用して、これをテストできます。
curl https://www.googleapis.com/youtube/v3/channels?part=id&mine=true&access_token=ACCESS_TOKEN
有効期限切れ、不正使用、不適切なスコープ、またはその他の理由で無効なアクセス トークンを使用して保護されたリソースにアクセスするリクエストを送信した場合、API は HTTP 401 レスポンス コード(Unauthorized
)を返します。
API が HTTP 403 レスポンス コードを返した場合、アプリケーションを登録できない可能性があります。多くの API では、未登録のアプリケーションにクエリボリューム制限 0
が設定されており、その制限を超えた場合に 403 レスポンス コードが返されます。
次のセクションでは、アクセス トークンの更新方法を説明します。
アクセス トークンの更新
アクセス トークンは定期的に期限が切れるため、その都度更新する必要があります。アクセス トークンの期限切れまたはその他の場合に、アプリケーションは更新トークンを使用して新しい有効なアクセス トークンを取得できます。サーバー サイド ウェブ アプリケーション、インストール済みアプリケーション、およびデバイスはいずれも、承認プロセス中に更新トークンを取得します。
アクセス トークンの更新では、クライアント ID、クライアント シークレット、およびユーザーの更新トークンを指定する POST
リクエストをアプリケーションが Google の承認サーバーに送信します。このリクエストでは、grant_type
パラメータ値を refresh_token
に設定する必要もあります。このリクエストの例を以下に示します。
POST /o/oauth2/token HTTP/1.1 Host: accounts.google.com Content-Type: application/x-www-form-urlencoded client_id=21302922996.apps.googleusercontent.com& client_secret=XTHhXh1SlUNgvyWGwDk1EjXB& refresh_token=1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ& grant_type=refresh_token
承認サーバーが、新しいアクセス トークンを含む JSON オブジェクトを返します。
{ "access_token":"1/fFAGRNJru1FTz70BzhT3Zg", "expires_in":3920, "token_type":"Bearer" }
更新トークンの発行数には 2 つの制限があります。1 つはクライアント/ユーザーの組み合わせあたりの制限数で、もう 1 つはクライアント全体のユーザー当たりの制限数です。更新トークンは、長期間有効なストレージに保存して、有効な限り継続して使用するようにします。アプリケーションからの更新トークンのリクエスト数が多すぎるとこれらの制限数に到達し、一番古い更新トークンから順に無効になります。
トークンを取り消す
アクセス トークンを取り消す方法は 2 つあります。
-
ユーザーは、以下の URL にアクセスして明示的にアクセスを取り消すことによって、アプリケーションに許可したアクセスを取り消すことができます。
https://accounts.google.com/b/0/IssuedAuthSubTokens
このページにアクセスする手順は次のとおりです。
-
アプリケーションは、プログラムを使用して自身のアクセスを取り消すことができます。この取り消し方法は、ユーザーがアプリケーションの登録を解除したり取り消したりする場合に重要です。その場合、アプリケーションに付与された権限を削除する API リクエストが、削除プロセスの一部になります。
トークンをプログラムで取り消すには、アプリケーションからリクエストを
https://accounts.google.com/o/oauth2/revoke
に送信し、トークンをパラメータとして含めます。curl https://accounts.google.com/o/oauth2/revoke?token={token}
アクセス トークンまたは更新トークンを指定できます。トークンがアクセス トークンであり、対応する更新トークンを持っている場合、その更新トークンも取り消します。
取り消しが成功した場合、レスポンスのステータス コードは
200
です。エラーが発生するとレスポンスのステータス コードは400
になり、エラー コードもレスポンスに含まれます。
クライアント ライブラリ
注: Google を利用したログイン機能を提供する場合は、OAuth 2.0 認証メカニズムとさまざまな Google+ のソーシャル機能へのアクセスを提供する Google+ Sign-in を使用することを推奨します。
OAuth 2.0 をアプリケーションに実装する際に、以下のクライアント ライブラリを使用できます。独自にコードを作成する代わりにクライアント ライブラリを使用することを推奨します。ユーザーやアプリケーションの安全とセキュリティを確保するには、これらの標準のクライアント ライブラリを使用することが重要です。
- Google APIs Client Library for Java
- Google APIs Client Library for JavaScript
- Google APIs Client Library for Python
- Google APIs Client Library for .NET
- Google APIs Client Library for Ruby
- Google APIs Client Library for PHP
- OAuth 2.0 Library for Google Web Toolkit
- Google Toolbox for Mac OAuth 2.0 Controllers
YouTube Data API の呼び出しセクションでも、OAuth 2.0 トークン値を適切に設定するためのコードの変更について説明しています。