OAuth 2.0 Flow: Server-side web apps

この OAuth 2.0 のフローは、機密情報の格納および状態の保持が可能なサーバーで動作する Web アプリケーション用に設計されています。この種類のアプリケーションは、ユーザーがアプリケーションを使用しているときおよび終了した後に、YouTube Data API にアクセスできます。

このシナリオは、承認が必要なアクションをユーザーが試行した時点から始まります。アプリケーションはユーザーを、アプリケーションが必要とする API アクセスの種類を指定するクエリ パラメータを含んでいる Google URL にリダイレクトします。

Google がユーザーの認証と同意を処理し、承認コードを返します。アプリケーションはそのコードを、client_id および client_secret と共に使用してアクセス トークンを取得します。このアクセス トークンを使用することで、ユーザーの代わりに 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 エンドポイントが承認コードを返すかどうかを指定します。 このパラメータ値は code に設定します。
    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 に設定します。
    access_type 推奨。このパラメータは、ユーザがブラウザの前にいないときに、アプリケーションがアクセス トークンを更新できるかどうかを指定します。有効なパラメータ値は onlineoffline です。ユーザーが表示されないときにアプリケーションが更新トークンを使用できるようにするには、このパラメータ値を offline に設定します(これはアクセス トークンを更新する方法です。このドキュメントの後半で説明します)。
    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=code&
      access_type=offline
    
  2. Google からのレスポンスを処理する

    ユーザーがアプリケーションにアクセス権を付与することを同意または拒否すると、ステップ 1 で指定した redirect_uri に Google がユーザーをリダイレクトします。

    • ユーザーがアプリケーションにアクセス権を付与した場合、code パラメータが redirect_uri に追加されます。この値は一時的な承認コードであり、ステップ 4 で説明したとおり、アクセス トークンに交換可能です。

      http://localhost/oauth2callback?code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf
    • ユーザーがアプリケーションにアクセス権を付与することを拒否した場合、redirect_uri のハッシュ フラグメントに access_denied エラー メッセージが含まれます。

      http://localhost/oauth2callback#error=access_denied
  3. 更新トークンとアクセス トークンの承認コードを交換する

    ユーザーがアプリケーションにアクセス権を付与済みであれば、更新トークンとアクセス トークンについて、ステップ 3 で取得した承認コードを交換します。これには、以下のキーと値のペアを本文に含む POST リクエストを https://accounts.google.com/o/oauth2/token に送信します。

    キー
    code ステップ 3 で Google が redirect_uri に返した承認コード。
    client_id アプリケーションの OAuth 2.0 クライアント ID です。この値は Google APIs console に表示されます。
    client_secret クライアント ID に関連付けられているクライアント シークレット。この値は Google APIs console に表示されます。
    redirect_uri クライアント ID の登録済み redirect_uri です。
    grant_type この値は authorization_code に設定します。

    サンプルのリクエストを以下に示します。

    POST /o/oauth2/token HTTP/1.1
    Host: accounts.google.com
    Content-Type: application/x-www-form-urlencoded
    
    code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf&
    client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
    client_secret=hDBmMRhz7eJRsM9Z2q1oFBSe&
    redirect_uri=http://localhost/oauth2callback&
    grant_type=authorization_code
    
  4. レスポンスを処理してトークンを格納する

    Google は、短期間有効なアクセス トークンと更新トークンを含む JSON オブジェクトを返すことによって POST リクエストに応答します。

    {
      "access_token" : "ya29.AHES6ZTtm7SuokEB-RGtbBty9IIlNiP9-eNMMQKtXdMP3sfjL1Fc",
      "token_type" : "Bearer",
      "expires_in" : 3600,
      "refresh_token" : "1/HKSmLFXzqP0leUihZp2xUt3-5wkU7Gmu2Os_eBnzw74"
    }
    
    • アクセス トークンを使用した承認済みリクエストの送信方法については、YouTube Data API の呼び出しセクションを参照してください。

    • 更新トークンを使用して新しいアクセス トークンを取得する方法については、アクセス トークンの更新セクションを参照してください。

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 トークン値を適切に設定するためのコードの変更について説明しています。