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

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 の画面から、有効期限のデフォルト値と最大値を短く設定するのが確実な方法です。
ログイン処理を実行します（loginWithToken によるログインを除く）。ログインが成功すると、リフレッシュトークンはその他の認証情報とともにストレージに自動保存されます。
アプリでは自分でアクセストークンのリフレッシュ処理を実装する必要はありません。Kii SDK はアクセストークンが期限切れになる前に自動的にリフレッシュ処理を行います。

リフレッシュトークンの永続化には、SDK による保存情報からのログインの方法を使用します。

リフレッシュが実行されていることをテストしたい場合は、アクセストークンの指定によるログインにある getAccessToken メソッドで確認できます。

リフレッシュ時のエラーへの対処

リフレッシュトークンを使用する場合、リフレッシュ失敗の例外を扱う必要があります。アクセストークンの更新は、SDK がネットワークアクセスを行うタイミングで自動的に行われるため、アクセストークンとリフレッシュトークンが変更されたことをアプリケーションが知る必要はありません。しかし、ネットワークアクセスが発生する API が特定の例外を返した場合、再ログインを考慮する必要があります。

通常、アクセストークンの更新は成功するはずですが、ネットワークエラー後に再試行した場合などの特殊な状況では、再ログインが必要になるケースがあります。同じリフレッシュトークンで 2 回更新を行うことはできないため、ネットワークエラーによってサーバーで再発行されたリフレッシュトークンを受け取れないようなケースからは、回復できません。

SDK から RefreshTokenFailedException 例外を受け取った場合は、再試行できない状態になったため、ログアウトされています。この場合、アプリ側でユーザー名とパスワードを使った再ログイン処理が必要です。