OAuth 2.0 Flow: Installed apps

この OAuth 2.0 のフローは、携帯電話やパソコンなどのデバイスにインストール済みのアプリケーション用に設計されています。これらのアプリケーションは、ユーザーがアプリケーションを操作中に、またはアプリケーションが長時間操作されないためバックグラウンドで実行されているときに、YouTube Data API にアクセスできます。

このフローは、ユーザーが YouTube Data API を操作できるようにするためのトークンをアプリケーションが安全に格納できないことを前提としています。また、アプリケーションがシステム ブラウザにアクセス可能であるか、アプリケーションにブラウザ コントロールを埋め込み可能であることが必要です。どちらの条件も満たさないアプリケーションについては、上記の [デバイス] タブをクリックして、デバイス用 の OAuth 2.0 の手順を参照してください。

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. アプリケーションをインストール済みのアプリケーションとして登録する

    アプリケーションを登録するときは、インストール済みのアプリケーションとして指定してください。これにより、redirect_uri パラメータのデフォルト値が変化します。

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

    注: 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 です。 インストール済みのアプリケーションを登録すると、http://localhost:porturn:ietf:wg:oauth:2.0:oob という 2 つの redirect_uri 値が自動的に作成されます。以下の説明を参照して、アプリケーションに適切な値を選択してください。

    http://localhost:port
    この値は Google の承認サーバーが承認コードを、クライアント デバイスのウェブ サーバーにクエリ文字列パラメータとして返すことを指定します。ポート番号は、Google APIs console で設定を変更せずに指定できます。

    この URL の承認コードを受け取るには、アプリケーションがローカル ウェブ サーバーでリスンする必要があります。プラットフォームでサポートされている場合は、承認コードを取得する方法としてこのメカニズムが推奨されます。ただし、一部のプラットフォームではこの方法はサポートされていません。また、サポートされていても、(Windows ファイアウォールなどの)他のソフトウェアによってこのメッセージの表示がブロックされることもあります。

    urn:ietf:wg:oauth:2.0:oob
    この値は、Google の承認サーバーが承認コードをブラウザのタイトル バーに返すことを指定します。このオプションは、クライアントの設定を大幅に変更しないとクライアントで HTTP ポートをリスンできない場合に便利です。Windows アプリケーションはこれに該当します。

    この値を使用する場合、ブラウザが承認サーバーからレスポンスを読み込んだことをアプリケーションで認識できる必要があります。その後、アプリケーションがブラウザのページ タイトルから承認コードを抽出します。ページ タイトルからトークンを解析する手順については、ステップ 4 を参照してください。

    承認コードを含むページがユーザーに表示されないようにする場合は、アプリケーションがブラウザ ウィンドウを閉じるようにする必要もあります。ブラウザ ウィンドウを閉じるメカニズムはプラットフォームによって異なります。
    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 のリトリーブ
    state 省略可能。アプリケーションがリクエストとリダイレクト レスポンスの間にステータスを維持するために使用する文字列です。送信した値が、アプリケーションのアクセス リクエストをユーザーが同意または拒否した後に、redirect_uri のハッシュ(#)フラグメントで name=value ペアとして返されます。このパラメータは、ユーザーをアプリケーションの正しいリソースに転送する場合や、ナンスの送信、クロスサイト リクエスト フォージェリの軽減など、複数の目的で使用できます。

    以下のサンプル 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
    
  3. Google からのレスポンスを処理する

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

    • redirect_urihttp://localhost(またはローカル ウェブ サーバーと同じパス)に設定した場合、次の 2 つのシナリオのどちらか 1 つが適用されます。

      • ユーザーがアプリケーションにアクセス権を付与した場合、Google は code パラメータを redirect_uri に追加します。以下の URL を参照してください。この値は、ステップ 5 で説明する、アクセス トークンを交換する 1 回限りの承認コードを指定します。

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

        http://localhost/oauth2callback#error=access_denied
    • redirect_uriurn:ietf:wg:oauth:2.0:oob に設定した場合、Google の承認サーバーは以下のようにページをブラウザに返します。次に、アプリケーションが承認コードをページ タイトルから抽出します。

      トークンを抽出するため、アプリケーションは、ページ タイトルの最後のスペース文字に続く文字列は x=a&y=b という形式のパラメータ文字列であると想定します。コードは、そのページが最終のタイトル文字列を含みログイン フローが完了していること示す code= または error= 割り当てを探して、そのサブストリングからパラメータを解析します。ページ タイトルが値を code パラメータに割り当てた場合、その値がトークンです。ただし、アプリケーションでは、トークンの長さやパラメータ文字列のパラメータ数については想定しないでください。

      たとえば以下のスクリーンショットは、次の属性を持つページです。

      • ページ タイトル: Success code=4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu
      • パラメータ文字列: code=4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu
      • 承認トークン: 4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu

  4. 更新トークンとアクセス トークンの承認コードを交換する

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

    キー
    code ステップ 4 で 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
    
  5. レスポンスを処理してトークンを格納する

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