この OAuth 2.0 のフローは、JavaScript ベースのウェブ アプリケーションから承認済みの Google API リクエストを送信できるようにするために設計されています。JavaScript ベースのウェブ アプリケーションは状態を長時間維持することができないため、アプリケーションはユーザーが使用している間に YouTube Data API にアクセスします。このフローは、アプリケーションに機密情報を格納できないことを前提としています。
Important: You need to obtain authorization credentials in the Google API 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 client-side web applications. The Google Accounts Authentication and Authorization documentation also provides complete details for implementing OAuth 2.0 in different types of applications.
-
The Making an authorized API request 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
このフローの手順は以下のとおりです。
-
アクセス トークンを取得する
注: Google の承認サーバーは SSL(HTTP)経由のアクセスのみを受け付け、HTTP 接続を拒否するため、Google の承認サーバーへのリクエストには
http
ではなくhttps
を使用する必要があります。API 認証が必要な操作をユーザーが初めて実行したときに、そのユーザーを
https://accounts.google.com/o/oauth2/auth
で Google の承認サーバーに転送する必要があります。以下の表は、この URL に含める必要がある(または含めることができる)リクエスト パラメータをまとめたものです。リクエスト URI のパラメータ値は適切に URL エスケープする必要があることに注意してください。パラメータ 説明 client_id
必須。アプリケーションの OAuth 2.0 クライアント ID です。この値は APIs Console で確認できます。 redirect_uri
必須。クライアント ID の登録済み redirect_uri
です。 APIs Console でアプケーション用の有効なリダイレクト URI を登録してください。response_type
必須。Google OAuth 2.0 エンドポイントが承認コードを返すかどうかを指定します。 JavaScript アプリケーションではこのパラメータ値を token
に設定する必要があります。このパラメータ値は、Google 承認サーバーがアクセス トークンを、サーバーが返すリダイレクト URI のハッシュ(#
)フラグメントでname=value
ペアとして返すことを指定します。scope
必須。アプリケーションがユーザーの代わりにアクセスできるリソースを特定するスコープのスペース区切りのリストです。これらの値は、Google がユーザーに表示する同意ページに記載される権限のリストを決定します。
YouTube Data API は次のスコープをサポートしています。
スコープス https://www.googleapis.com/auth/youtube YouTube アカウントの管理 https://www.googleapis.com/auth/youtube.readonly YouTube アカウントの表示 https://www.googleapis.com/auth/youtube.upload YouTube の動画のアップロード、YouTube の動画の管理 https://www.googleapis.com/auth/youtubepartner-channel-audit channel
リソース内のauditDetails
のリトリーブapproval_prompt
省略可能。このパラメータは、ユーザーが特定の操作を実行するたびに、アカウントのアクセス権をアプリケーションに付与するプロンプトを表示するかどうかを指定します。デフォルト値は auto
で、この場合、ユーザーは保護されたリソースに初めてアクセスするときにのみ、アクセスを許可する必要があります。
ユーザーが特定のスコープ セットに関してアプリケーションにアクセス権を付与済みの場合にもそのユーザーを同意ページに転送するには、このパラメータ値をforce
に設定します。state
省略可能。アプリケーションがリクエストとリダイレクト レスポンスの間にステータスを維持するために使用する文字列です。送信した値が、アプリケーションのアクセス リクエストをユーザーが同意または拒否した後に、 redirect_uri
のハッシュ(#
)フラグメントでname=value
ペアとして返されます。このパラメータは、ユーザーをアプリケーションの正しいリソースに転送する場合や、ナンスの送信、クロスサイト リクエスト フォージェリの軽減など、複数の目的で使用できます。login_hint
省略可能。認証を実行するユーザーをアプリケーションが識別できる場合、このパラメータを使用して、Google の承認サーバーにヒントを提供できます。サーバーはこのヒントを使用してログイン フォームのメール フィールドにデータを入力したり適切なマルチログイン セッションを選択したりすることで、ログイン フローを簡素化できます。 以下のサンプル URL は、アプリケーションがユーザーの代わりに YouTube Data API リクエストを送信する権限をリクエストする、Google の承認サーバー URI です。パラメータ値を適切に URL エスケープする必要があることに注意してください。
https://accounts.google.com/o/oauth2/auth? client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com& redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback& scope=https://www.googleapis.com/auth/youtube& response_type=token
-
ユーザーが同意を決定する
このステップではユーザーがアプリケーションに、ユーザーとして承認済みの API リクエストの実行を許可するかどうかを決定します。Google の承認サーバーにより、ユーザーの認証情報を使用してアクセスする権限を要求している Google API サービスとアプリケーションの名前が表示されます。ユーザーは、アプリケーションにアクセス権を付与することに同意するか、または拒否することができます。
前のステップのサンプル URL をクリックすると、このフローをテストできます。ファイルをサーバーに置くことで、ユーザーのレスポンスがリダイレクト URI
http://localhost/oauth2callback
にどのように表示されるかを確認することもできます(詳細については次のステップを参照してください)。 -
Google からのレスポンスを処理する
ユーザーがアプリケーションにアクセス権を付与することを同意または拒否すると、ステップ 1 で指定した
redirect_uri
に Google がユーザーをリダイレクトします。-
ユーザーがアプリケーションにアクセス権を付与した場合、Google がリダイレクト URI のハッシュ フラグメントに短期間有効なアクセス トークンを追加します。以下のサンプル URI を参照してください。レスポンスには
expires_in
パラメータとtoken_type
パラメータも含まれます。これらのパラメータはそれぞれ、秒単位のトークンの寿命と返されるトークンの種類を表します。承認サーバーへのリクエストにstate
パラメータが含まれていた場合、レスポンスにもstate
パラメータが含まれます。http://localhost/oauth2callback#access_token=1/QbIbRMWW&token_type=Bearer&expires_in=3600
注: アプリケーションでは、レスポンスのハッシュ フラグメントに他のパラメータも含めることができる必要があります。前の段落の説明は、
redirect_uri
で返される名前と値のペアの最小セットについての記述です。ページで実行される JavaScript コードは
window.location.hash
値からアクセス トークンを取得可能であり、トークンを Cookie に格納するか、サーバーにPOST
します。 -
ユーザーがアプリケーションにアクセス権を付与することを拒否した場合、
redirect_uri
のハッシュ フラグメントにaccess_denied
エラー メッセージが含まれます。http://localhost/oauth2callback#error=access_denied
-
-
ユーザーのトークンを検証する
ユーザーがアプリケーションにアクセス権を付与済みの場合、
redirect_uri
で返されるトークンを明示的に検証する必要があります。トークンを検証または確認することで、アプリケーションが Confused deputy problem(混乱した使節の問題)に脆弱でないことを保証できます。トークンを検証するには、リクエストを
https://www.googleapis.com/oauth2/v1/tokeninfo
に送信し、トークンをaccess_token
パラメータの値として設定します。この URL が、トークンの発行先アプリケーション、トークンに関連付けられているユーザー、ユーザーがアクセス権を付与したスコープ、トークンの有効期限など、トークンに関する情報を受け入れて返します。以下のサンプル URL は、トークンの検証リクエストの送信先の例です。
https://www.googleapis.com/oauth2/v1/tokeninfo?access_token=ACCESS_TOKEN
-
トークンの検証レスポンスを処理する
Google 承認サーバーはトークンの検証リクエストに対して、トークンを表す JSON オブジェクトまたはエラー メッセージを含む JSON オブジェクトを返します。
-
トークンが有効な場合、JSON オブジェクトには以下のプロパティが含まれています。
フィールド audience
アクセス トークンの意図されたユーザーであるアプリケーション。
重要: トークンを使用する前に、フィールドの値が Google APIs console のClient ID
に完全に一致することを確認する必要があります。確認することで、アプリケーションが Confused deputy problem(混乱した使節の問題)に脆弱でないことを保証できます。expires_in
トークンが無効になるまでの残りの秒数。 scope
ユーザーがアクセス権を付与したスコープのスペース区切りのリスト。このリストは、ステップ 1 の承認リクエストで指定したスコープに一致する必要があります。 userid
この値を使用して、複数の Google API からのプロファイル情報を関連付けることができます。ステップ 1 でリクエストに https://www.googleapis.com/auth/userinfo.profile
スコープを含めた場合のレスポンスにのみ、表示されます。このフィールド値は、アプリケーションでユーザー セッションを作成および管理するために使用可能な、ログイン ユーザー用の不変の ID です。サンプルのレスポンスは以下のとおりです。
{ "audience":"8819981768.apps.googleusercontent.com", "user_id":"123456789", "scope":"https://www.googleapis.com/auth/youtube", "expires_in":436 }
-
トークンの有効期限が切れた場合、または改ざんやアクセス権の取り消しが行われた場合は、Google の承認サーバーが JSON オブジェクトでエラー メッセージを返します。エラーの種類は 400 エラーで、JSON 形式の本文は以下のようになります。
{"error":"invalid_token"}
仕様により、このエラーの理由に関しては追加の情報は提供されません。
注: 400 エラーは一般的に、アクセス トークン リクエスト URL の形式が不適切であるか、URL エスケープが適切に行われていないことを示します。
-
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 トークン値を適切に設定するためのコードの変更について説明しています。