OAuth 2.0 Flow: Client-side web apps

この 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
```
このページにアクセスする手順は次のとおりです。
1. Google サンドバーのユーザーの画像をクリックして、アカウントリンクをクリックするか他の方法を使用して、ユーザーの Google アカウントのアカウントの概要ページに移動します。
2. リンクをクリックしてセキュリティの設定ページを表示します。
3. ユーザーの Google アカウントにアクセスして詳細情報を使用できる接続済みのアプリケーションおよびウェブサイトのアクセスを管理するボタンをクリックします。
アプリケーションは、プログラムを使用して自身のアクセスを取り消すことができます。この取り消し方法は、ユーザーがアプリケーションの登録を解除したり取り消したりする場合に重要です。その場合、アプリケーションに付与された権限を削除する 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 をアプリケーションに実装する際に、以下のクライアントライブラリを使用できます。独自にコードを作成する代わりにクライアントライブラリを使用することを推奨します。ユーザーやアプリケーションの安全とセキュリティを確保するには、これらの標準のクライアントライブラリを使用することが重要です。

YouTube Data API の呼び出しセクションでも、OAuth 2.0 トークン値を適切に設定するためのコードの変更について説明しています。