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 Developers Console to be able to use OAuth 2.0 authorization.

This document contains the following sections:

Obtaining OAuth 2.0 access tokens

このフローの手順は以下のとおりです。

  1. アクセス トークンを取得する

    注: 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

  2. 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

  3. ユーザーのトークンを検証する

    ユーザーがアプリケーションにアクセス権を付与済みの場合、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

  4. トークンの検証レスポンスを処理する

    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 種類サポートしています。

  1. アクセス トークンを 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

  2. アクセス トークンを 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 によるログイン

注: Google を利用したログイン機能を提供する場合は、OAuth 2.0 認証メカニズムとさまざまな Google+ のソーシャル機能へのアクセスを提供する Google+ Sign-in を使用することを推奨します。

OAuth 2.0 をアプリケーションに実装する際に、以下のクライアント ライブラリを使用できます。独自にコードを作成する代わりにクライアント ライブラリを使用することを推奨します。ユーザーやアプリケーションの安全とセキュリティを確保するには、これらの標準のクライアント ライブラリを使用することが重要です。

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