アクセストークンのリフレッシュ

Kii Cloud では、OAuth 2.0 のリフレッシュトークンをサポートしています。リフレッシュトークンを使うと、ユーザビリティを損なうことなくアクセストークンの有効期限を短く設定できます。

Kii Cloud へのリクエストでは、アクセストークンが毎回ネットワーク上に送出されているため、漏洩とそれによる不正操作のリスクが伴います。この対策のため有効期限を短く設定したい一方、頻繁なユーザー名とパスワードの再入力はユーザビリティを損なうため避けたいところです。リフレッシュトークンを使うと、内部的にアクセストークンを再発行できるため、この問題を解決できます。

以下にリフレッシュトークンを使用した場合の動きを示します。リフレッシュトークンがネットワーク上を流れる回数は、アクセストークンに比べて少なくてすむため、漏洩の観点からは相対的に安全性が高まります。

なお、図はリフレッシュトークンの動きに特化した内容ですが、実際には他の関連情報も保存しています。

クライアント SDK では、定められた設定をしておくことで、アクセストークンのリフレッシュを自動的に実行します。有効期限の経過まで 5 分未満になったタイミングで SDK の API を呼び出すと、SDK の内部で、新しいアクセストークンを取得する処理が自動的に行われます。REST API を使用する場合は、SDK 内部で実行しているリフレッシュに相当する処理をモバイルアプリのロジックで実行します。

リフレッシュトークンを使用する場合の詳細な仕様は以下のとおりです。

リフレッシュトークンはログイン時にアクセストークンと同時に取得できます。
リフレッシュが実行されると、アクセストークンとリフレッシュトークンは再発行されます。このとき、古いアクセストークンとリフレッシュトークンは無効になります。リフレッシュトークンは 1 回だけ使用できます。
ユーザー名以外の電話番号やメールアドレスで認証する場合もリフレッシュトークンを使用できます。仮ユーザーや Thing の Persistent トークンは対象外です。
同じユーザーに複数回ログイン（ユーザー名とパスワードなど）したとき、発行された複数のアクセストークンはお互いのリフレッシュの影響を受けません。たとえば、アクセストークン A1 がリフレッシュによってアクセストークン A2 になっても、別のログイン操作によって発行されたアクセストークン B は有効なままです。アクセストークン B は別のタイミングでリフレッシュされます。
リフレッシュトークンは基本的に期限切れになりませんが、パスワードの変更時や運用上の都合などで無効になることがあります。リフレッシュトークンが無効にならないことを前提とした実装は避け、再ログインの手段を用意しておくことをおすすめします。
ユーザーが無効化された場合、リフレッシュトークンも無効になります。
次の API を実行しようとした時にアクセストークンがすでに有効期限切れになった場合でも、リフレッシュトークンが有効であればリフレッシュ処理を実行し、新しいアクセストークンで次の API を実行できます。

リフレッシュトークンの利用手順

リフレッシュトークンを使用する手順は以下のとおりです。

開発者ポータルからリフレッシュトークンを有効にします。開発者ポータルでの設定をご覧ください。
アクセストークンの有効期限を設定します。ログイン時の引数でも設定できますが、上記 1 の画面から、有効期限のデフォルト値と最大値を短く設定するのが確実な方法です。
ログイン処理を実行します。ログインが成功すると、REST API の戻り値としてアクセストークン、リフレッシュトークン、アクセストークンの有効期限が有効な時間が返されます。
アクセストークンを使用して、アプリの機能を実行します。
アクセストークンの有効期限が切れる前に、下記のリフレッシュ API を呼び出します。戻り値のアクセストークン、リフレッシュトークン、アクセストークンの有効期限を新しい値として使用します。以降、4 と 5 を繰り返します。

アクセストークンのリフレッシュ

開発者ポータルで「Enable Refresh Token」を ON にすると、ログインのレスポンス上のフィールド "refresh_token" に、リフレッシュトークンが返されます。リフレッシュの際は、この値が必要です。

< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Content-Type: application/json
< Transfer-Encoding: chunked
< Date: Mon, 14 May 2012 22:52:52 GMT
<
{
  "id" : {USER_ID},
  "access_token" : {ACCESS_TOKEN},
  "refresh_token" : {REFRESH_TOKEN}
  "expires_in" : 864000
}

取得したリフレッシュトークンを保存する場合は、安全な方法や場所を選択してください。リフレッシュトークンがあれば、ログインしたユーザーの権限で Kii Cloud の領域にアクセスできるため、機密情報として扱う必要があります。

アクセストークンのリフレッシュを行う例を以下に挙げます。

この例は開発者ポータルでデフォルトのアクセストークンの有効期限を設定した場合を想定しています。API で指定する場合は、"expires_at" フィールドに有効期限の日時（UNIX 時間・ミリ秒、UTC）を指定します。

curl -v -X POST \
  -H "Authorization: Basic {BASE64_ENCODED_APPID_AND_APPKEY}" \
  -H "Content-Type: application/json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/oauth2/token" \
  -d '{
        "grant_type": "refresh_token",
        "refresh_token": "{REFRESH_TOKEN}"
      }'

アクセストークンのリフレッシュは Basic 認証を使って行います。{BASE64_ENCODED_APPID_AND_APPKEY} には AppID と任意の値をコロン（:）で連結した文字列を Base64 エンコードしたものを入れてください。

リフレッシュが成功すると、Kii Cloud は次のようなレスポンスを返します。このレスポンスにおける "access_token" の値が新しいアクセストークン、"refresh_token" の値が新しいリフレッシュトークンです。また "expired_in" は、アクセストークンが有効な時間（秒）となります。

< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Content-Type: application/json
< Transfer-Encoding: chunked
< Date: Mon, 14 May 2012 22:52:52 GMT
<
{
  "id" : {USER_ID},
  "access_token" : {ACCESS_TOKEN},
  "refresh_token" : {REFRESH_TOKEN}
  "expires_in" : 864000
}

リクエストがサーバーで受理されてリフレッシュ処理が実行されると、クライアントがそのレスポンスを受け取ったかどうかにかかわらず、サーバー側で認識できるアクセストークンが更新されます。この際、リクエスト前に使用していたアクセストークンとリフレッシュトークンは無効になります。通信エラー等でレスポンスを受け取れなかった場合は、もう一度ログインし直す必要があります。