OAuth 2.0 Flow: Devices

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

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

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

client_id と client_secret をアプリケーションに埋め込む

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

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

デバイスが 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

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 値を格納する必要があります。

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"
}
```

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

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

注: user_code は大文字と小文字を区別するため、レスポンスの表示どおり正確に入力する必要があります。
ユーザーが Google アカウントにログインする

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

ユーザーがログインした後、Google の承認サーバーは、ユーザーの代わりにアクセスする権限を要求する Google サービスとアプリケーションの名前を表示するページを表示します。ユーザーはアプリケーションへのアクセス権の付与を同意または拒否できます。
トークンを取得するためにポーリング·サーバーからのレスポンスを処理する

ユーザーがアプリケーションにアクセス権を付与したら、デバイスが次に送信するポーリングリクエストでは、アクセストークンと更新トークンを含む 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 種類サポートしています。

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