OAuth 2.0 Flow: Devices

この OAuth 2.0 のフローは、入力機能が限定されたゲーム機やビデオ カメラなどのデバイスで実行されるアプリケーション用に設計されています。このフローでは、ユーザーがデバイス上でアプリケーションを操作して、URL とデバイス コードを取得します。ユーザーは次に、コンピュータやスマートフォンなど、入力機能が豊富な別のデバイスに切り替えて、デバイス コードを承認できます。

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. client_id と client_secret をアプリケーションに埋め込む

    Google にアプリケーションを登録して、登録プロセス中に作成された client ID と client secret をアプリケーションに埋め込みます。どちらの値も Google APIs console に表示されます。

  2. デバイス コードをリクエストする

    デバイスが POST リクエストを https://accounts.google.com/o/oauth2/device/code で Google の承認サーバーに送信します。このリクエストでは以下のパラメータを指定します。

    パラメータ
    client_id 必須。アプリケーションの OAuth 2.0 クライアント ID です。
    scope 必須。アプリケーションがユーザーの代わりにアクセスできるリソースを特定するスコープのスペース区切りのリストです。

    以下のサンプル リクエストは、デバイス コードの取得方法を示しています。

    POST /o/oauth2/device/code HTTP/1.1
Host: accounts.google.com
Content-Type: application/x-www-form-urlencoded

client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
scope=https://www.googleapis.com/auth/youtube

  3. Google からのレスポンスを処理する

    Google がデバイスに JSON オブジェクトを返して、リクエストに応答します。サンプルのレスポンスは以下のとおりです。

    {
  "device_code" : "4/L9fTtLrhY96442SEuf1Rl3KLFg3y",
  "user_code" : "a9xfwk9c",
  "verification_url" : "http://www.google.com/device",
  "expires_in" : "1800"
  "interval" : 5,
}

    デバイス上のアプリケーションに、user_code と verification_url が表示されます。アプリケーションは、ステップ 4 で使用する device_code 値、expires_in 値、および interval 値を格納する必要があります。

  4. Google の承認サーバーのポーリングを開始する

    ステップ 3 の JSON レスポンスで返された device_code を使用して、アプリケーションで Google の承認サーバーのポーリングを開始できます。これには、以下のキーと値のペアを指定して、アプリケーションから POST リクエストを https://accounts.google.com/o/oauth2/token に送信します。

    キー
    client_id アプリケーションの OAuth 2.0 クライアント ID です。
    client_secret クライアント ID に関連付けられているクライアント シークレット。この値は Google APIs console に表示されます。
    code デバイス コードはステップ 3 で取得しました。
    grant_type この値は http://oauth.net/grant_type/device/1.0 に設定します。

    サンプルのポーリング リクエストを以下に示します。ステップ 3 の JSON レスポンスで返された interval は、アプリケーションがポーリング リクエスト間に待機する最小秒数を指定します。

    POST /o/oauth2/token HTTP/1.1
Host: accounts.google.com
Content-Type: application/x-www-form-urlencoded

client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
client_secret=hDBmMRhz7eJRsM9Z2q1oFBSem&
code=4/YMSlR3fSCC1NtUh073DuZKTJJ3ss&
grant_type=http://oauth.net/grant_type/device/1.0

    ユーザーがステップ 5 からステップ 7 を完了するまで、アプリケーションはポーリング リクエストごとに以下のレスポンスのどちらか 1 つを受信します。

    • 次のレスポンスは、ユーザーが API アクセスをデバイスに承認するためのステップを完了していない場合に表示されます。

      {
  "error" : "authorization_pending"
}

    • 次のレスポンスは、アプリケーションがポーリング リクエストを送信する頻度が高すぎることを示しています。

      {
  "error" : "slow_down"
}

  5. ユーザーが user_code を別のブラウザに入力する

    ユーザーがパソコンや携帯電話などの別のデバイスでブラウザを起動し、verification_url にアクセスします。この URL はユーザーがステップ 3 で取得した user_code を入力できるページを表示します。

    注: user_code は大文字と小文字を区別するため、レスポンスの表示どおり正確に入力する必要があります。

  6. ユーザーが Google アカウントにログインする

    ユーザーは user_code を入力した後、デバイスからの YouTube Data API リクエストを許可するために使用する Google アカウントにログインするように求められます（ログイン済みのユーザーは、次のステップに直接進みます）。

  7. トークンを取得するためにポーリング·サーバーからのレスポンスを処理する

    ユーザーがアプリケーションにアクセス権を付与したら、デバイスが次に送信するポーリング リクエストでは、アクセス トークンと更新トークンを含む JSON オブジェクトが返されます。

    {
  "access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in":3920,
  "token_type":"Bearer",
  "refresh_token":"1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ"
}

    重要: アプリケーションはどちらの値も格納する必要があります。

    • アクセス トークンを使用した承認済みリクエストの送信方法については、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 トークン値を適切に設定するためのコードの変更について説明しています。