IMIconnect Developer Hub

Welcome to the IMIconnect developer hub. You'll find all the resources to help you get started with IMIconnect quickly. We are here to support you if you get stuck. Let's jump right in!

Get Started

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:

Parameter
Type
Description

customerId

String

Specifies the id of the customer profile that will be used for authentication. The customer profile must have been previously provisioned within the IMIconnect platform, and contain a valid phone number (MSISDN).

callback

A callback implementation through which authentication events will be raised.

  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:

Parameter
Type
Description

listen

boolean

Pass true to cause the SDK to listen for the incoming SMS and automatically validate the received pin.

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:

Parameter
Type
Description

pin

String

Specifies the pin number to be validated.

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;
  }
}

Authentication


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.