Authentication

The IMIconnect authentication module enables Two Factor Authentication (2FA) by allowing one-time passwords (OTP) to be generated and verified by the platform. OTPs are sent to the users device as an SMS.

The authentication module provides additional security for mobile applications by acting as the second factor of authentication. For example, consider a user of a banking application who, after logging in with their username and password, may be asked to provide further authentication via a one-time password (OTP).

This feature requires the use of provisioned customer profiles that have a valid phone number (MSISDN). One-time passwords generated by the platform are valid for 30 minutes.

The authentication module is exposed through the ICUserAuthentication class.

ICUserAuthentication

Exposes methods that enable user authentication through the generation and validation of One Time Passwords (OTPs) sent over SMS.

ICUserAuthentication

Constructs an ICUserAuthentication instance that may be used to authenticate a user. Events are raised through the callback to report on the various stages of the authentication process.

📘

Throws an exception if customerId is empty, the callback is null or if the SDK has not been initialized.

  Syntax: ICUserAuthentication(String customerId, ICUserAuthenticationCallback callback) throws ICException

  Parameters:

  Example:

ICUserAuthenticationCallback authCallback = new ICUserAuthenticationCallback() 
{
  @Override
  public void onPinGenerated() 
  {
    Log.d("UserAuthentication", "Pin generated sucessfully");
  }

  @Override
  public void onPinValidated() 
  {
    Log.d("UserAuthentication", "Pin validated sucessfully");
  }

  @Override
  public void onPinReceived() 
  {
    Log.d("UserAuthentication", "Pin received sucessfully");
  }

  @Override
  public void onError(final ICException exception) 
  {
    Log.e("UserAuthentication", exception.toString());
  }
};

final String customerId = "[the previously provisioned customer profile id]";

ICUserAuthentication userAuthentication = null;

try 
{
  userAuthentication = new ICUserAuthentication(customerId, authCallback);
} 
catch (ICException e) 
{
  e.printStackTrace();
}

Methods:

generatePin

Used to generate a pin from the IMIconnect platform that will be sent to the user through SMS.
When the listen parameter is set to true the SDK will listen for the incoming SMS and automatically start the validation process once received. If the SMS is not received within 2 minutes, an error is reported through the callback onError method.

  Syntax: void generatePin(boolean listen)

  Parameters:

stopListening

Causes the SDK to stop listening for incoming SMS messages. Has no affect if the SDK is not currently listening.

📘

It is highly recommended that the hosting app implements a UI element that allows users to cancel the listening process and enter the pin manually.

  Syntax: void stopListening()

validatePin

Used to validate a pin with the IMIconnect platform. The result is reported through the callback specified when constructing the ICUserAuthentication instance.

  Syntax: void validatePin(String pin)

  Parameters:

userAuthentication.validatePin("pin");

//result of operation notified through ICUserAuthenticationCallback methods:
@Override
public void onPinValidated() 
{
  Log.d("UserAuthentication", "Pin validated sucessfully");
}

@Override
public void onError(final ICException exception) 
{
  //Error occurred
  Log.e("UserAuthentication", exception.toString());
  
  switch (exception.getErrorCode())
  {
    case ICErrorCode.FeatureNotSupported:
      //Authentication not enabled for the app configuration in the platform.
      break;
      
    case ICErrorCode.RestFailure:
      //Rest error occurred, query the ICRestException for more info
      ICRestException restException = (ICRestException)exception;
      
      int responseCode = restException.getResponseCode();
      String errorMessage = restException.getMessage();
      
      break;
  }
}