ログインとアクセストークン

Kii Cloud ではログイン済みのユーザーをアクセストークンによって識別します。ログイン状態を管理するにはアクセストークンの扱いが重要となります。

アクセストークン

ユーザー登録やログインに成功すると、このユーザーは Kii Cloud に対してログインした状態になります。この際 Kii Cloud はユーザーに対してアクセストークンを発行します。アクセストークンは認証済みユーザーを識別するための文字列です。

クライアント SDK では、ログイン後に入手したアクセストークンをメモリ上に保持し、リクエストが行われるたびに Kii Cloud に送信します。これにより、Kii Cloud はログイン中のユーザーを識別することができます。アクセストークンはクライアント SDK の内部で保持され、後続の処理で自動的に参照されるため、モバイルアプリの実装から見ると、後続の処理でアクセストークンの存在を特に意識する必要はありません(ログイン中かどうかは意識する必要があります)。

REST では、HTTPS リクエストの Authorization ヘッダによって明示的にアクセストークンを指定します。ログインで取得したアクセストークンをモバイルアプリ側で自己管理します。

アクセストークンがあれば、ユーザー名とパスワードを入力した場合と同様に、特定ユーザーの権限で Kii Cloud のデータにアクセスできます。アクセストークンをモバイルアプリで扱うときは、パスワードと同等のセキュリティを持つ情報として扱う必要があります。

アクセストークンに関連して、以下の場合は特殊な扱いとなります。

  • Kii Cloud SDK for Thing を使用した場合、Thing も専用の API によって Kii Cloud にログインし、アクセストークンを持った状態になります。詳細は Thing 管理 をご覧ください。

  • 仮ユーザー(Pseudo User)を使う場合、発行されたアクセストークンをモバイルアプリ側のコードで保持し続ける必要があります。詳細は 仮ユーザー機能を使用する をご覧ください。

ログイン状態の保持

アクセストークンはクライアント SDK のメモリ上に置かれるため、そのままではモバイルアプリの再起動によって失われます。再起動後にログイン状態を復元するには、以下のいずれかの方法を使用する必要があります。

  • ユーザー名とパスワード再入力によるログイン
  • アクセストークンの指定によるログイン
  • SDK による保存情報からのログイン

Android で Activity の再起動に備えて内部のセッション情報を保存する場合は、クライアント SDK の 情報の保存と復元機能 を使用します。しかし、Activity.onSaveInstanceState() での Bundle はプロセスが再起動した場合には復元されないため、アクセストークンをストレージに保存する処理も別途必要です。

ユーザー名とパスワード再入力によるログイン

この復帰方法では、プロセスの再起動時にユーザー名とパスワードを再入力することで、もう一度ログインし直します。再入力の手間によってユーザビリティが損なわれますが、ログイン状態の保持をさせない仕様が適切なアプリケーションでは、この方法を選択することもできます。

モバイルアプリ側でユーザーを作成する に示すように、ユーザー名とパスワードをランダムな内容で決め、これらをユーザーが入力しないような設計にした場合も同様に再ログインによって復帰できます。ただし、このような場合は 仮ユーザー の利用を検討することを推奨します。

アクセストークンの指定によるログイン

この方法では、アクセストークンをモバイルアプリの側で保存することによって、ログイン状態を保持し続けます。プロセスのシャットダウン後(Web の場合は HTML ページの遷移後)もログイン状態を継続したい場合や、Web サービスで見かける「ログイン状態を保持する」に相当する機能を実現したい場合に使用します。

この場合、次の図のようにログイン中の KiiUser からアクセストークンを取り出し、次回のモバイルアプリの起動時に、保存しておいたアクセストークンを使ってログインします。

この方法では、アクセストークンをモバイルアプリから自由に操作できるため、複数ユーザーの切り替えも実現できます。対象ユーザーを順番にログインしてアクセストークンを取得しておき、それら複数のアクセストークンを場面に応じて切り替えながら SDK に設定できます(クライアント SDK 内ではアクセストークンを 1 件しか保持できないため、SDK 内で複数ユーザーを同時にログイン状態にすることはできません)。

なお、アクセストークンの指定によるログインではアクセストークンしか復帰できないため、リフレッシュトークン の利用はできません。リフレッシュトークンを使用する場合は、下記に示す SDK による保存情報からのログイン方法を使用します。

SDK による保存情報からのログイン

この方法では、SDK によって自動的に保存されたアクセストークンや認証情報を使って再ログインすることで、ログイン状態を保持し続けます。

SDK では、ログイン完了時や KiiUser のリフレッシュ実行時に、アクセストークンや認証情報をストレージに自動的に保存しています。プロセスの再起動などの後で再ログインを行いたい場合、次の図のようにモバイルアプリから API の呼び出しを行うと(KiiUser.loginWithStoredCredentials メソッドを呼び出します)、保存された情報を使ってログインできます。

なお、再ログインを実行するかどうかにかかわらず、アクセストークン等の情報は、ログイン時やリフレッシュの実行時に常に保存されています(Android リファレンスガイドの SDK による保存情報からのログイン に示すように、Android では特定の初期化方法が必要です)。

この方法では、アクセストークン以外にも認証に必要な情報を保存しているため、再ログイン後もリフレッシュトークンによるアクセストークンのリフレッシュを実行できます。

アクセストークンの有効期限

アクセストークンには有効期限がありますが、デフォルトでは有効期限として 2147483647 秒が設定されています。これは、約 68 年後に相当する時間のため、アクセストークンの期限切れによる再ログインを考慮する必要はありません。

セキュリティの観点から、アクセストークンの有効期限を変更することもできます。また、変更することにより、万一、アクセストークンが漏洩しても、攻撃を受け続けるリスクを回避できます。

有効期限が経過した後、そのアクセストークンを使って Kii Cloud にアクセスすると、API は実行エラーになります。下記に示すリフレッシュトークンを使うと、新しいアクセストークンに自動更新することができます。

有効期限は初めにログインしたタイミングからの経過時間として設定します。一般的な Web アプリケーションのように、最終アクセス時刻からのアイドル時間ではない点に注意してください。

管理者機能によりユーザーの無効化が行われた場合は、有効期限にかかわらず、アクセストークンは無効になります。また、ユーザーのパスワードが変更された場合も、有効期限に関わらず、アクセストークンは無効になります。

有効期限の設定

有効期限はログイン API から指定できるほか、開発者ポータルでその上限値を設定することもできます。

  • API の引数からの指定

    ログインなどの API で有効期限を指定することで、発行されるアクセストークンに有効期限を設定できます。対象となる API は下記の 対象 API をご覧ください。

  • 開発者ポータルからの設定

    開発者ポータルの設定画面から、アクセストークンについてのポリシーを設定できます。有効期限が指定されていなかった場合のデフォルト値、有効期限の最大値を指定できます。

対象 API

アクセストークンの有効期限を設定した場合、以下の API からログインした場合に設定が使用されます。

  • パスワードによるログイン

  • ユーザーの新規作成

  • 別サービスアカウントを利用したログイン(ネイティブアプリケーションによる認証)

以下は有効期限の影響を受けません。

  • アクセストークンによる自動/手動ログイン(初めのアクセストークンの有効期限が使用されます)

  • 仮ユーザー機能によるログイン(期限切れにならないよう、常にデフォルト値が使用されます)

アクセストークンの互換性

各クライアント SDK で発行されたアクセストークンは SDK と REST の間で互換性があります。

たとえば、Kii Cloud SDK for Android を使用中に Android でサポートされていない機能を使用したい場合、SDK からアクセストークンを取得し、それを REST のアクセストークンとして使用できます。

リフレッシュトークン

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

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

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

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

クライアント SDK では、定められた設定をしておくことで、アクセストークンのリフレッシュを自動的に実行します。有効期限の経過まで 5 分未満になったタイミングでリクエストを行うと、新しいアクセストークンを取得する処理が自動的に行われます。

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

  • リフレッシュトークンはログイン時にアクセストークンと同時に取得できます。
  • リフレッシュが実行されると、アクセストークンとリフレッシュトークンは再発行されます。このとき、古いアクセストークンとリフレッシュトークンは無効になります。リフレッシュトークンは 1 回だけ使用できます。
  • リフレッシュトークンには有効期限がありません。
  • ユーザー名以外の電話番号やメールアドレスで認証する場合や、外部サービス を利用した認証を行う場合にもリフレッシュトークンを使用できます。仮ユーザー や Thing の Persistent トークン は対象外です。
  • ユーザーが無効化された場合、リフレッシュトークンも無効になります。
  • プロセス再起動時に アクセストークンの指定によるログイン を行った場合は、リフレッシュトークンが失われるため、アクセストークンの自動更新は実行されません。リフレッシュトークンを利用するには、SDK による保存情報からのログイン を使用します。