Authenticating with an External Service Account

Kii Cloud supports the user authentication with external services, such as Facebook and Twitter.

These services provide features that allow integration with external applications and work with Kii Cloud. End users can use their credentials for one of these services to log in to Kii Cloud without remembering the username and password for their user account created on Kii Cloud. Once the user is authenticated, a Kii user that is associated with the external service account becomes logged in.

In this documentation, services such as Facebook and Twitter are called "external services" as these services are external to Kii Cloud.

Supported external services

Kii Cloud supports the following external services with its SDKs and REST API.

The following table summarizes supported external services for each platform.

Android iOS JavaScript REST
Facebook Yes Yes Yes Yes
Twitter Yes Yes Yes Yes
Google Yes Yes Yes -
Sina Weibo (新浪微博) Yes Yes - -
QQ Yes Yes Yes Yes

The following services are not supported when you are selecting "China" as the server location: Facebook, Twitter, and Google.

Supported features

For all external services, Kii Cloud supports the following two features for integrating users.

  • Creating new users and login

    You can let a user to login to the Kii Cloud with their external service account information.

    When making an initial login to the Kii Cloud, a user can use their external service's username and password. Once the authentication with this information succeeds, a new KiiUser will be created. On the next login and after that, the user can login to the Kii Cloud as this KiiUser by providing the same external service account information.

  • Linking existing users

    You can let a currently logged-in KiiUser to bind their external service account information. By binding the external service account information, the user will be able to login to the Kii Cloud also with this information. The user can also unbind the external service account from their KiiUser.

    The feature works when a target KiiUser is logged in. After the user authenticates themselves with their external service's username and password, a mobile app can execute the dedicated "link" Kii Cloud API to link the external service account to the KiiUser. On the next login and after that, the user can login to the Kii Cloud as this KiiUser by providing the same external service account information.

    Note that you can bind multiple external service accounts to a KiiUser. If you do this, the user will be able to log in with all of them.

    When linking a user, the email address used in the external service can be different from the one registered in KiiUser. When linking a Facebook account, please be aware that Kii Cloud will try to auto-link accounts with their email addresses as described in Auto-linking a Facebook account.

Your mobile app needs to get a user's username and password for the external service. In most cases, the SDK provided by the external service provides a UI for showing a login screen. By leveraging the SDK, you will be able to integrate a login screen that complies with the design of the external service, like in the following examples.

Auto-linking a Facebook account

If you use the native application authentication for Facebook account integration, Kii Cloud attempts to bind a Facebook account to an existing Kii Cloud account by matching their email addresses.

When a user logs in to Kii Cloud with their Facebook account, Kii Cloud will check if there is an existing KiiUser that has the same email address. If a KiiUser with the same email address is found, that KiiUser will be linked with the Facebook account. Otherwise, Kii Cloud will create a new KiiUser and link it to the Facebook account.

Here is an example. Suppose there is a KiiUser with the email address user1@kii.com and the password kiipw. Also, suppose that the same user has a Facebook account with the same email address user1@kii.com. When the user logs in to Kii Cloud with this Facebook account, the account will be linked to the existing KiiUser account user1@kii.com. Once the link is established, the user can log in to Kii Cloud by using the Facebook account as well as directly typing the username user1@kii.com and password kiipw.

Please note that if a user signs up for Kii Cloud with a Facebook account, a KiiUser that has the email address of the Facebook will be created. This means that the user will not be able to create a new KiiUser account with this email address (because the email address is already taken).

If you are going to let users sign up for Kii Cloud with their email addresses and also let users log in with their Facebook account, make sure to enable the email address verification. If the email address verification is disabled, a malicious user can create a new KiiUser with other people's email address. If the user whose email address was misused signs up for Kii Cloud with their Facebook account, the malicious user can hijack the Kii Cloud account.

Basic steps

To integrate an external service, you need to get an access token from the external service and set the token in the Kii Cloud API.

Note that we no longer support an integration mechanism in which the Kii Cloud SDK provides a login screen.

The steps to enable an external service account login are as follows:

  1. Register your application on the target external service.

    Please register your application on the target external service as a developer. When the registration is completed, you will get an access key.

  2. Register the access key.

    Go to Kii Cloud developer portal and register the access token you've got from the external service.

  3. Implement login mechanism

    For most cases, you will need to include the SDK provided by the external service to get the access token of the external service. Please consult the SDK manual provided by the target external services for the details on how to get the access token.

Flow

Here is a typical flow for implementing a mobile app.

  1. Invoke an API of an external service and show a login screen.
  2. Get the external service's username and password from a user. The external service will authenticate the user with this information.
  3. If successfully authenticated, the mobile app gets an access token of the external service.
  4. The mobile app provides the access token of the external service to an API of the Kii Cloud SDK (or REST API) and proceeds with the integration.

Note that the above flow assumes that the external service SDK provides the login UI, and it does not require the OAuth Consumer server. The actual flow for getting an access token may differ depending on the target external service.

If you use the REST API, you need to develop a module that corresponds to the "client SDK" in the figure as a part of your mobile app.

Please do not confuse Kii Cloud access token with the access token provided by the external service.