ログイン

ユーザーの作成が完了すると、登録した情報によるログインができるようになります。ログイン機能の概要については ユーザー登録とログイン をご覧ください。

また、REST API におけるログインを行うと、Kii Cloud はアクセストークンを返します。以後、ユーザーログインを必要とする REST API を利用する際には、このアクセストークンを HTTP ヘッダに埋め込むことになります。アクセストークンの機能概要については ログインとアクセストークン をご覧ください。

ログイン

ログインを行い、アクセストークンを取得する例を以下に挙げます。

curl -v -X POST \
  -H "Authorization: Basic {BASE64_ENCODED_APPID:APPKEY}" \
  -H "Content-Type: application/json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/oauth2/token" \
  -d '{
        "grant_type": "password",
        "username": "user_123456",
        "password": "123ABC"
      }'

ログインは Basic 認証 を使って行います。{BASE64_ENCODED_APPID:APPKEY} には AppID と AppKey をコロン(:) で連結した文字列を Base64 エンコードしたものを入れてください。

ここで、"username" に指定可能な値は以下のとおりです。

  • username
  • international phone number
  • email address
  • EMAIL: email address
  • PHONE: international phone number(例:PHONE:+819012341234)
  • PHONE: 2-letter country code local phone number(例:PHONE:JP-9012341234)

さらに "expiresAt" パラメータを指定することでアクセストークンの有効期限(UNIX 時間・ミリ秒、UTC)が設定可能です。有効期限の設定がない場合は、アクセストークンは永久的に有効となります。

ログインが成功すると、Kii Cloud は次のようなレスポンスを返します。 このレスポンスにおける "access_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},
  "expires_in" : 2147483647,
  "token_type" : "bearer"
}

リクエストの "expiresAt" とレスポンスの "expired_in" は表現形式が異なる点にご注意ください。"expiresAt" は日付での指定ですが、"expired_in" は現在時刻からの残り秒数です。たとえば、2015 年 12 月 1 日の正午(UTC)に翌日の正午までのトークンを取得するとき、"expiresAt" : 1449057600000 の指定により、"expires_in" : 86400 前後の値(24 時間× 60 分× 60 秒前後)が返ります。

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

ユーザーのパスワードが変更されると、アクセストークンは無効になります。この場合は、ユーザー名とパスワードを使ってログインを行い、新しいアクセストークンを取得してください。
また、ユーザーが無効化された場合も、アクセストークンは無効になります。

ログイン完了後、ログアウトする方法はありません。アプリの実装では、発行されたアクセストークンをクライアントのメモリ上から破棄することでログアウト相当とします(クライアント SDK も同様の実装です)。なお、一旦、ユーザーの 無効化 を行うと、発行済みのアクセストークンを無効にできますが、そのユーザーに紐付いているすべてのアクセストークンが無効になるため、注意が必要です。

ユーザーが未登録の場合や、パスワードが一致しない場合は HTTP ステータス 400 が返ります。管理者によってユーザーが 無効化 されていた場合も HTTP ステータス 400 が返ります。

セキュリティ上の理由により、REST API ではこれらのどれが原因で失敗したのかを判別できません。ただし、管理者は 開発者ログ を確認することで、エラーの原因を特定することができます。

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

セキュリティ対策として OAuth 2.0 のリフレッシュトークンを使用できます。

リフレッシュトークンを使うと、アクセストークンの有効期限が切れそうな場合、REST API を呼び出すことで新しいアクセストークンに更新することができます。リフレッシュトークンの機能概要については、こちら をご覧ください。

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

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

開発者ポータルでの有効期限の設定

アクセストークンのリフレッシュを行う際は、開発者ポータルから設定を変更する必要があります。

アクセストークンの有効期限のデフォルト値 / 最大値や、リフレッシュトークンの使用有無に関する設定は、開発者ポータルから変更できます。アクセストークンの有効期限の設定は、有効期限に関するポリシーを設定することになるため、より確実な設定が期待できます。

設定方法は以下のとおりです。

  1. アプリケーションコンソール上の "Edit" ボタンをクリックします。

  2. "SECURITY" をクリックします。

  3. リフレッシュトークンの使用有無や、アクセストークンの有効期限の設定を変更します。設定できる値は以下の 3 つがあります。

    • Enable Refresh Token:リフレッシュトークンを使用するかどうかの設定です。初期状態は OFF です。
    • Default expiration period in minutes:API の引数によって、アクセストークンの有効期限が指定されなかった場合に使用される値です。初期状態は 35791394 分です。
    • Maximum expiration period in minutes:アプリ上、許される有効期限の最大値です。これを超えたアクセストークンを取得しようとした場合はエラーとなります。有効期限のデフォルト値は、この値以下のものにする必要があります。初期状態は 35791394 分です。

リフレッシュトークンを使用する場合、アクセストークンの有効期限の設定にはバランスが必要です。有効期限が長すぎると、漏洩した場合に不正アクセスが続くリスクが高くなる一方、短すぎるとリフレッシュトークンをネットワークでやりとりする頻度が増えるため、攻撃に対するリスクが高まります。

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

開発者ポータルで「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: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:APPKEY} には AppID と AppKey をコロン(:) で連結した文字列を 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
}

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