Authentication

The authentication module contains the necessary operations to create, sign in and log out of a Kiwi Account.

Authentication Platforms

One account may have one credential for each authentication platform. Each credential holds information to authenticate with a given authentication platform.

The current supported authentication platforms are:

E-mail and Password:

Authentication through e-mail and password requires only the target e-mail and password for sign-up and sign-in operations.

After a sign-up call, and e-mail confirmation may be sent, according to configuration. If the configuration demands the e-mail confirmation, then the credential will not be marked as valid until the user confirms the e-mail.

Msisdn and Pincode

Authentication using a phone number (msisdn) as key. In order to verify the user, a pincode is sent to the target device, and should be used for signUp/ signIn.

The proccess of asking for a pincode and using it to initiate signUp/signIn operations may be done automatically or manually, as shown further.

Facebook

Authentication using a Facebook user token. It's up to the app to integrate with Facebook and extract this token.

After the sent token is verified on Kiwi server, the related Facebook id is extracted and used as credential key.

Sign Up

Sign Up calls create an account using the giving credentials. Sign Up calls DO NOT sign in.

Sign Up with e-mail and password:

    Future<SignUpResponse> signUpFuture =
        kiwiSDK.auth().signUpWithEmailAndPassword(email, password);

Sign Up calls for e-mail and password platform return an Future object containing a SignUpResponse object.

Sign Up with msisdn and pin code:

There are 3 possible ways to sign up with msisdn and pincode. In all of them the result of the operation should be retrieved by using one implementation of a MsisdnPinAuthenticationSignUpListener, which will contain the result SignUpResponse object .

  • 1) Sign Up with pincode:

    • Used when the app already knows the pincode that should be used to authenticate the user (pincode was input manually by the user).

    kiwiSDK.auth().signUpWithMsisdnAndPincode(msisdn, pincode, new MsisdnPinAuthenticationSignUpListener() {
        @Override
        public void onSuccess(SignUpResponse signUpResponse) {
            handleSignUp(signUpResponse);
        }

        @Override
        public void onError(SignUpResponse signUpResponse) {
            handleSignUp(signUpResponse);
        }
    });

  • 2) Sign Up without pincode:

    • Used when the app does not know and does not want to handle the retrieval of the pincode. The send and retrieve of the pincode will be done internally by kiwiSdk. Kiwi will wait the pincode sms for a limit number of seconds, and if it does not arrive on time, will finish with a timeout status.

    • The msisdn's carrier's will also by detected by Kiwi.

    • If the pincode arrives on time, it will be stored internally, and it can be retrieved in order be used on a signIn operation

      kiwiSDK.auth().signUpWithMsisdn(msisdn, timeoutInSeconds, new MsisdnPinAuthenticationSignUpListener() {
  @Override
  public void onSuccess(SignUpResponse signUpResponse) {
      handleSignUp(signUpResponse);
  }

  @Override
  public void onError(SignUpResponse signUpResponse) {
      handleSignUp(signUpResponse);
  }
});

  • 3) Sign Up without pincode using Carrier:

    • Same as number 2, but passing carrier

      kiwiSDK.auth().signUpWithMsisdn(msisdn, Carrier.TIM, timeoutInSeconds, new MsisdnPinAuthenticationSignUpListener() {
  @Override
  public void onSuccess(SignUpResponse signUpResultStatus) {
      handleSignUp(signUpResultStatus);
  }

  @Override
  public void onError(SignUpResponse signUpResultStatus) {
      handleSignUp(signUpResultStatus);
  }
});

Sign Up with Facebook User Token:

    Future<SignUpResponse> responseFuture = kiwiSDK.auth().signUpWithFacebookToken(USER_TOKEN);

Sign Up calls for facebook return an Future object containing a SignUpResponse object.

SignUpResponse description:

A SignUpResponse holds a SignUpOperationStatus and a AuthenticationIntegrationStatus.

The SignUpOperationStatus indicates the result of the operation, but does not specify the status according to the AuthenticationPlatform. For that purpose, the AuthenticationIntegrationStatus should be used, since it contains errors specified by platform.

The AuthenticationIntegrationStatus is better explained at the end of this page.

The possible sign up results are described below:

  • UNKNOWN_ERROR: An Unknown error happened while performing authentication request

  • SUCCESS: Success signing up

  • INVALID_PARAMETERS: Invalid parameters sent. Probably missing any credentials values

  • SERVER_ERROR_INVALID_CREDENTIAL: Could not sign up because the credentials sent are invalid. For example, invalid e-mail, invalid msisdn, non-matching pincode.

  • SERVER_ERROR_CREDENTIAL_ALREADY_EXISTS: Could not sign up because the sent credentials already exist

  • SERVER_ERROR_CONNECTION_FAILURE: Could not perform sign up request due to a connection error

  • SERVER_ERROR_UNEXPECTED_RESPONSE: Received an unexpected response while making an sign up request

  • SERVER_ERROR_PARSING_RESPONSE: Could not parse response sent from server after an sign up request

  • ERROR_TIMEOUT_WAITING_CREDENTIAL_CONFIRMATION: Timeout reached while waiting for credential confirmation. For example, timeout waiting for pincode

  • ERROR_HANDLING_CREDENTIAL_CONFIRMATION: Error happened while handling credential confirmation. For example, error asking for pincode to be sent

Sign In

Sign in calls authenticate the current user on Kiwi's server. After an successful sign in request, every request to Kiwi will use authentication.

Sign In with e-mail and password:

    Future<SignInResponse> signInFuture =
        kiwiSDK.auth().signInWithEmailAndPassword(email, password);

Sign In with msisdn and pincode

There are 3 possible ways to sign in with msisdn and pincode. In all of them the result of the operation should be retrieved by using one implementation of a MsisdnPinAuthenticationSignInListener, which will contain the result of the operation.

  • 1) Sign In with pincode:

    • Used when the app already knows the pincode that should be used to authenticate the user (pincode was input manually by the user).

      kiwiSDK.auth().signInWithMsisdnAndPincode(msisdn, pincode, new MsisdnPinAuthenticationSignInListener() {
  @Override
  public void onSuccess(SignInResponse signInResponse) {
      handleSignInResponse(signInResponse);
  }

  @Override
  public void onError(SignInResultStatus signInResponse) {
      handleSignInError(signInResponse);
  }
});

  • 2) Sign In without pincode:

    • Used when the app does not know and does not want to handle the retrieval of the pincode. The send and retrieve of the pincode will be done internally by kiwiSdk. Kiwi will wait the pincode sms for a limit number of seconds, and if it does not arrive on time, will finish with a timeout status.

    • The msisdn's carrier's will also by detected by Kiwi.

      kiwiSDK.auth().signInWithMsisdn(msisdn, timeoutInSeconds, new MsisdnPinAuthenticationSignInListener() {
@Override
public void onSuccess(SignInResponse signInResponse) {
  handleSignInResponse(signInResponse);
}

@Override
public void onError(SignInResultStatus signInResponse) {
  handleSignInError(signInResponse);
}
});

  • 3) Sign In without pincode:

    • Same as number 2, but forcing carrier.

      kiwiSDK.auth().signInWithMsisdn(msisdn, Carrier.TIM, timeoutInSeconds, new MsisdnPinAuthenticationSignInListener() {
@Override
public void onSuccess(SignInResponse signInResponse) {
  handleSignInResponse(signInResponse);
}

@Override
public void onError(SignInResponse signInResponse) {
  handleSignInError(signInResponse);
}
});

Sign In with Facebook User Token:

    Future<SignInResponse> signInFuture =
        kiwiSDK.auth().signInWithFacebookToken(USER_TOKEN);

Sign in calls return a SignInResponse Object, which contains the result of the Sign in operation, a AccountProfile object, which holds information about the user's account (see Account Guide), and a AuthenticationIntegrationStatus. NOTE: The account is only returned after successful sign in operations.

SignInResponse description

A SignInResponse Object contains the SignInResultStatus, a AccountProfile object, which holds information about the user's account (see Account Guide), and a AuthenticationIntegrationStatus. NOTE: The account is only returned after successful sign in operations.

The possible sign in operation status are:

  • UNKNOWN_ERROR: An Unknown error happened while performing authentication request

  • SUCCESS: Success signing in

  • INVALID_PARAMETERS: Invalid parameters sent. Probably missing any credentials values

  • SERVER_ERROR_CREDENTIAL_NOT_FOUND: Could not sign in because the credential was not found

  • SERVER_ERROR_CREDENTIAL_NOT_VALIDATED: Could not sign in because the target credential has not yet been validated

  • SERVER_ERROR_CONNECTION_FAILURE: Could not perform sign in request due to a connection error

  • SERVER_ERROR_UNEXPECTED_RESPONSE: Received an unexpected response while making an sign in request

  • SERVER_ERROR_PARSING_RESPONSE: Could not parse response sent from server after an sign in request

  • ERROR_TIMEOUT_WAITING_CREDENTIAL_CONFIRMATION: Timeout reached while waiting for credential confirmation. For example, timeout waiting for pincode

  • ERROR_HANDLING_CREDENTIAL_CONFIRMATION: Error happened while handling credential confirmation. For example, error asking for pincode to be sent

Check if credential exists

If needed, the app can check if a given credential already exists on Kiwi before attempting to make a signUp operation. Each platform have a specific method for doing that.

// Email/Password
Future<CheckCredentialExistsStatus> future = kiwiSDK.auth().checkEmailExists(email);
// Msisdn/Pin
Future<CheckCredentialExistsStatus> future = kiwiSDK.auth().checkMsisdnExists(msisdn);
// Facebook
Future<CheckCredentialExistsStatus> future = kiwiSDK.auth().checkFacebookIdExists(FACEBOOK_ID);

The CheckCredentialExistsStatus may contain the following values:

  • CREDENTIAL_EXISTS - target credential exists

  • CREDENTIAL_DOES_NOT_EXIST - target credential does not exist

  • INVALID_PARAMETERS - missing credential

  • SERVER_ERROR_UNKNOWN - unexpected error happened inside Kiwi's server

  • NETWORK_ERROR - error while trying to connect with Kiwi's server. Possibly lack of connection

Log Out

When a log out operation happens all the information regarding account is deleted from the device (including account subscriptions and account context). In order to recover this value a new sign in must be made.

    Future<LogoutResultStatus> logoutFuture =
        kiwiSDK.auth().logout();

The possible logout results are:

  • UNKNOWN_ERROR: An Unknown error happened while performing log out request

  • SUCCESS: Successfully logged out

  • NOT_LOGGED_IN: Could not log out because was not logged in

Authentication token

Every time you perform a sign in operation, Kiwi users a session token to represent your session. This token lives for a period of time (configurable in our admin), after that, you'll be asked to perform a sign in again.

Retrieve

If you want to keep track of the current session token, do it as the code below:

    Future<String> authenticationTokenFuture = kiwiSDK.auth().retrieveAuthenticationToken();

Refresh (Currently With bug that always return success.. Do not use )

If you don't want to ask your user to repeat the sign in, you can refresh your session token, so, your session will last more time. Do it as below:

Future<RefreshTokenResultStatus> authenticationTokenFuture = kiwiSDK.auth().refreshToken();

The possible RefreshTokenResultStatus are:

  • SUCCESS - Authentication token refreshed successfully

  • NOT_LOGGED_IN - Can't refresh token if not logged in

  • SERVER_REJECTED_REQUEST - Server refused to refresh the current token, because it's expired or invalid

SignIn

In order to achieve frictionless login across multiple apps one may use the method to logIn using a previously stored (for now, stored by the app) authenticationToken.

kiwiSDK.auth().signInWithAuthToken(testAuthenticationToken, new SignInWithTokenCallback() {
      @Override
      public void onSuccess(SignInWithTokenResponse signInWithTokenResponse) {
          showToast("Sign in with token was successful. Response: " + signInWithTokenResponse);
      }

      @Override
      public void onError(SignInWithTokenResultStatus signInWithTokenResultStatus) {
          showToast("Sign in with token was unsuccessful. Status: " + signInWithTokenResultStatus);
      }
  });

A SignInWithTokenResponse contains a SignInWithTokenResultStatus and an AccountProfile object. The possible Status for SignInWithTokenResultStatus are the following:

  • SUCCESS - Successfully logged in with sent token

  • SUCCESS_ALREADY_LOGGED_TO_TOKEN - Was already logged with the sent token. Nothing was done.

  • INVALID_TOKEN - Sent token was invalid

  • SERVER_ERROR - An unexpected error happened on the server while trying to logIn with the sent token

Magic Token

If a user is logged on a Web page, it may ask Kiwi server to generate a magic token that will allow him/her to signIn without needing to input credentials again.

The signIn process with a magic token is described as follow:

MagicTokenSignInResponse response = kiwiSDK.auth().signInWithMagicToken(magicToken).get();

The MagicTokenSignInResponse object contains the status of the operation, and, in case of success, the account profile. The most important status are

  • SUCCESS: operation performed successfully

  • INVALID_TOKEN: sent token is invalid (maybe it was already used, maybe it's expired)

  • ERROR_SERVER_UNKNOWN: unknown error happened at server

  • ERROR_NETWORK_ERROR: error while trying to connect with Kiwi server

Platform specific operations

Msisdn and Pincode

Send Pincode:

Operation that only asks for a pincode to be sent to the user. On this operation Kiwi does not wait for the sms to arrive. This method sould be used when one knows that the sms will not reach the target device (for example, when the target device is a tablet) or when the app suspects that the sms is taking to long to arrive (Kiwi is returning timeout)

SendPincodeResponse sendPincodeResponse = kiwiSDK.authMsisdnPin().sendPincode(msisdn).get();

The possible results for SendPincodeStatus are:

  • UNKNOWN_ERROR: An Unknown error happened locally while performing send pincode request

  • SUCCESS: A pincode was sent to the target device

  • ERROR_INVALID_MSISDN: The msisdn sent is not valid

  • SERVER_ERROR_INVALID_CONFIGURATION: Missing mandatory configuration in order to send pincode (Eg: missing large account configuration)

  • SERVER_ERROR_SENDING_PINCODE: Error while trying to send sms through Atlas

  • SERVER_ERROR_CONNECTION_FAILURE: Error connecting with Kiwi's server in order to ask for the pincode to be sent

  • SERVER_ERROR_UNEXPECTED_RESPONSE: Received an unexpected response while making an sign in request

  • SERVER_ERROR_PARSING_RESPONSE: Could not parse response sent from server after an sign in request

  • SERVER_ERROR_UNKNOWN: Server internal error

  • SERVER_ERROR_COULD_NOT_DETECT_CARRIER: Could not detect any carrier for the target phone number, so the pincode was not sent

Authentication Integration Status

Every authentication and acconunt response object holds a AuthenticationIntegrationStatus.

This attribute intends to work as an extra statusCode, providing more information about what may have caused an error while performing an authentication request.

The possible authentication integration status are:

NONE(-1, "Sdk did not tried or was not able to perform the request to the server. " +
            "For example, SDK found missing parameters on the request or an invalid state and decided not to continue with the request." +
            "Others reasons may include lack of connectivity, error reading server response.")

// RANGE 0-99 includes generic errors, may happen on any integrator
GENERIC_SUCCESS(0, "Success"),
GENERIC_ERROR_INVALID_AUTHENTICATION_TOKEN(1, "Invalid authentication token sent. Can't authenticate"),
GENERIC_ERROR_CREATING_AUTHENTICATION_TOKEN(2, "Error creating a valid authentication token"),
GENERIC_CREDENTIAL_ALREADY_EXISTS(3, "A credential with the given key already exists"),
GENERIC_COULD_NOT_FIND_CREDENTIAL(4, "Could not find information for the given credentials. Either a login with the given key does not exist or it does exist but the sent credentials were invalid"),
GENERIC_UNKNOWN_STATUS_VERIFYING_CREDENTIAL(5, "An unexpected status was returned while checking the target credential"),
GENERIC_UNKNOWN_ERROR_VERIFYING_CREDENTIAL(6, "An unknown error happened while checking the target credential"),
GENERIC_UNKNOWN_ERROR_CREATING_ACCOUNT(7, "An unknown error happened while trying to create an account"),
GENERIC_ERROR_LINKING_SUBSCRIPTION_NOT_FOUND(8, "Could not link subscription. Subscription not found"),
GENERIC_SUCCESS_SUBSCRIPTION_ALREADY_LINKED(9, "Subscription was already linked to the given account"),
GENERIC_ERROR_SUBSCRIPTION_DOES_NOT_BELONG_TO_USER(10, "Subscription does not belong to target user. Can't link"),
GENERIC_ERROR_SUBSCRIPTION_LINKED_TO_OTHER_ACCOUNT(11, "Subscription was already linked to other account"),
GENERIC_ERROR_ACCOUNT_NOT_FOUND(12, "Couldn't find account"),
GENERIC_CREDENTIAL_NOT_VALIDATED(13, "Credential hasnt been validated yet"),


// RANGE 100-199 includes Email/Password specific errors
EMAIL_PASSWORD_INVALID_EMAIL_FORMAT(101, "Invalid email sent. Invalid format"),
EMAIL_PASSWORD_EMAIL_ALREADY_CONFIRMED(102, "Tried to confirm an email that was already confirmed"),
EMAIL_PASSWORD_ERROR_GENERATING_EMAIL_CONFIRMATION_TOKEN(103, "Error trying to generate a token to confirm an email"),
EMAIL_PASSWORD_INVALID_EMAIL_CONFIRMATION_TOKEN(104, "Error trying to decode sent email confirmation token. Token is invalid"),
EMAIL_PASSWORD_ERROR_GENERATING_RESET_PASSWORD_TOKEN(105, "Error trying to generate a token to reset a password"),
EMAIL_PASSWORD_INVALID_RESET_PASSWORD_TOKEN(106, "Error trying to decode sent reset password token. Token is invalid"),
EMAIL_PASSWORD_MISSING_NEW_PASSWORD(107, "Error trying to change password. Missing new password"),
EMAIL_PASSWORD_MISSING_EMAIL(108, "Missing email"),


// RANGE 200-299 include Msisdn/Pin specific errors
MSISDN_PIN_INVALID_MSISDN_FORMAT(201, "Invalid msisdn sent. Invalid format"),
MSISDN_PIN_MISSING_PINCODE(202, "No pincode was sent. Cant authenticate"),
MSISDN_PIN_ERROR_SENDING_PINCODE_MISSING_MSISDN(203, "Error while trying to send pincode, missing target msisdn"),
MSISDN_PIN_ERROR_SENDING_PINCODE_MISSING_IDENTITY_POOL_CONFIGURATION(204, "Could not send pincode because no Identity Pool was found for the given application's context"),
MSISDN_PIN_ERROR_SENDING_PINCODE_MISSING_CARRIER_CONFIGURATION(205, "Could not send pincode because one or more mandatory properties were not configured for the target carrier"),
MSISDN_PIN_ERROR_SENDING_PINCODE_SMS(206, "Error while sending pincode sms through atlas"),
MSISDN_PIN_ERROR_SENDING_PINCODE_COULD_NOT_DETECT_CARRER(207, "Could not detect the target phone's carrier. Can't continue.")
PreviousUserNextAccount

Last updated