Two Factor Authentication (2FA)

The Webex Connect 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 user's 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 Webex Connect platform, and contain a valid phone number (MSISDN).

callback

ICUserAuthenticationCallback

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