2-factor authentication

Infobip 2-factor authentication Android library

Requirements

Step by step integration

  1. Download Android library from here.
  2. Copy the library file into the libs folder.
  3. Add dependency to build.gradle file (compile (name:'infobip-2fa', ext:'aar')).
  4. Add user permissions to application project Manifest.xml file.
  5. Rebuild your project.

User permissions:

<uses-permission android:name="android.permission.INTERNET" />

Application registration

In order to use this library, user has to create an Infobip account and register mobile application. After registering the application, application ID will be obtained, and after creating message for that application, you will get message ID.

API key can be obtained by calling REST API method for generating this key.

Initialization

Initialization is required for using the main library functionality - authenticating users and should be done by creating TFAManager object using constructor TFAManager(String apiKey).

Parameter Type Description
apiKey String This key is used for client authorization and can be obtained by calling appropriate REST API method.

Example

TFAManager manager = new TFAManager("e99df81a22c9a40d41d328ad19a70c83-9225c21b-e8a5-4021-81da-df81a22c");

After creating TFAManager object, library methods can be called. Available methods are:

Starting 2-factor authentication

Starting 2-factor authentication invokes server-side generating PIN code and sending the code to defined destination. That can be done by calling the sendPin(SendPinRequest request, SendPinListener listener) function.

Method parameters

Parameter Type Description
request SendPinRequest Object that contains information about request.
listener SendPinListener Response status will be provided via the listener.

SendPinRequest

The SendPinRequest class contains information about 2-FA initiation request and can be instantiated using either the SendPinRequest(String applicationId, String messageId, String to) or the SendPinRequest(String applicationId, String messageId, String to, Boolean ncNeeded) constructor. Parameters: applicationId, messageId and to are request mandatory fields and can be set only through constructor.

Field Type Description
applicationId String 2-FA application ID.
messageId String ID of message that will be sent to phone number.
to String Msisdn(phone number) to which PIN code will be sent.
from String The name that will appear on the end user’s mobile phone as the sender of the 2-FA message.
ncNeeded Boolean If ncNeeded value is true, Number context lookup will be requested before sending SMS. If field’s value is false, SMS will be sent without requesting Number context.

Note:

from field can have null value. In that case, default sender ID will appear as the sender of the 2-FA message.

ncNeeded can have null value. In that case, Number context will be requested.

SendPinListener

SendPinListener is used for receiving response from server and has two methods that should be implemented:

onSuccess method is called when response from server is successful with SendPinResponse object as argument.

onError method is called when response from server is unsuccessful and will always receive appropriate errorCode and errorDescription.

Example

SendPinRequest request = new SendPinRequest("A9F4290821F1EE6BC06A8F0792F86035", "8F0792F86035A9F4290821F1EE6BC06A", "41793026727", true);

SendPinListener listener = new SendPinListener(){
    @Override
    public void onSuccess(SendPinResponse response) {
        ...
    }

    @Override
    public void onError(int errorCode, String errorDescription){
        ...
    }
};

manager.sendPin(request, listener);

Resend PIN

If you want to send the same PIN code to the same phone number, you can do it by calling the resendPin(String pinId, SendPinListener listener) method.

Method parameters

Parameter Type Description
pinId String ID of the sent PIN code.
listener SendPinListener Response status will be provided via this listener.

SendPinListener

SendPinListener is used for receiving response from server and has two methods that should be implemented:

onSuccess method is called when response from server is successful with SendPinResponse object as argument.

onError method is called when response from server is unsuccessful and will always receive appropriate errorCode and errorDescription.

Example

SendPinListener listener = new SendPinListener(){
    @Override
    public void onSuccess(SendPinResponse response) {
        ...
    }

    @Override
    public void onError(int errorCode, String errorDescription){
        ...
    }
};

manager.resendPin("1DA742B334365527E7FBD8ACC02F7F562", listener);

Pin Verification

In order to continue the process, a one-time PIN (OTP) code that was generated and sent to user, needs to be verified. User will enter PIN code and if it matches the one that is received, he will be allowed to continue the process.

Method that needs to be called in order to verify PIN code is verifyPin(VerifyPinRequest request, VerifyPinListener listener) method.

Method parameters

Parameter Type Description
request VerifyPinRequest The object contains information about PIN verification.
listener VerifyPinListener Response status will be provided via the listener.

VerifyPinRequest

The VerifyPinRequest class contains information about PIN verification request and can be instantiated using the VerifyPinRequest(String pinId, String pin) constructor. Parameters passed to constructor are request mandatory fields and can be set only through constructor.

Field Type Description
pinId String ID of the PIN that has to be verified.
pin PIN code received by user.

VerifyPinListener

VerifyPinListener is used for receiving response from server and has two methods that should be implemented:

onSuccess method is called when response from server is successful with VerifyPinResponse object as argument.

onError method is called when response from server is unsuccessful and will always receive appropriate errorCode and errorDescription.

Example

VerifyPinRequest request = new VerifyPinRequest("1DA742B334365527E7FBD8ACC02F7F562", "23ac71");

VerifyPinListener listener = new VerifyPinListener(){
    @Override
    public void onSuccess(VerifyPinResponse response) {
        ...
    }

    @Override
    public void onError(int errorCode, String errorDescription){
        ...
    }
};

manager.verifyPin(request, listener);

Checking if phone number is verified

In every moment you can check if phone number is already verified. That can be done by calling isPhoneNumberVerified(IsPhoneNumberVerifiedRequest request, IsPhoneNumberVerifiedListener listener).

Method parameters

Parameter Type Description
request IsPhoneNumberVerifiedRequest Object that contains information about request.
listener IsPhoneNumberVerifiedListener Response status will be provided via the listener.

IsPhoneNumberVerifiedRequest

The IsPhoneNumberVerifiedRequest class has one mandatory field: msisdn, and can be instantiated using the IsPhoneNumberVerifiedRequest(String msisdn) constructor.

Field Type Description
msisdn String Msisdn (phone number) for which you would like to check verification status.
verified Boolean Filter by verified status.
sent Boolean Filter by message sent status.

IsPhoneNumberVerifiedListener

IsPhoneNumberVerifiedListener is used for receiving response from server and has two methods that should be implemented:

onSuccess method is called when response from server is successful with IsPhoneNumberVerifiedResponse object as argument.

onError method is called when response from server is unsuccessful and will always receive appropriate errorCode and errorDescription.

Example

IsPhoneNumberVerifiedRequest request = new IsPhoneNumberVerifiedRequest("41793026727");
request.setSent(true);

IsPhoneNumberVerifiedListener listener = new IsPhoneNumberVerifiedListener(){
    @Override
    public void onSuccess(IsPhoneNumberVerifiedResponse response) {
        ...
    }

    @Override
    public void onError(int errorCode, String errorDescription){
        ...
    }
};
}

manager.isPhoneNumberVerified(request, listener);

Getting PIN delivery information

After sending PIN code to end user, you may want to know if PIN code is delivered. This can be done by requesting PIN delivery information.

This information should be requested by calling getDeliveryInfo(String pinId, DeliveryInfoListener listener) method.

Method parameters

Parameter Type Description
pinId String ID of PIN code for which delivery information is requested.
listener DeliveryInfoListener Response status will be provided via the listener.

DeliveryInfoListener

DeliveryInfoListener is used for receiving response from server and has two methods that should be implemented:

onSuccess method is called when response from server is successful with DeliveryInfoResponse object as argument.

onError method is called when response from server is unsuccessful and will always receive appropriate errorCode and errorDescription.

Example


DeliveryInfoListener listener = new DeliveryInfoListener(){
    @Override
    public void onSuccess(DeliveryInfoResponse response) {
        ...
    }

    @Override
    public void onError(int errorCode, String errorDescription){
        ...
    }
};

manager.getDeliveryInfo("1DA742B334365527E7FBD8ACC02F7F562", listener);

Models

SendPinResponse

The SendPinResponse class contains information about 2-FA initiation response. The class fields:

Field Type Description
pinId String ID of the sent PIN code.
to String Phone number of PIN code recepient.
ncStatus String Number context status. This status can take on of these values: NC_DESTINATION_UNKNOWN, NC_DESTINATION_REACHABLE, NC_DESTINATION_NOT_REACHABLE or NC_NOT_CONFIGURED.
smsStatus String Status of sent SMS, can take on of the values: MESSAGE_SENT or MESSAGE_NOT_SENT.

VerifyPinResponse

The VerifyPinResponse class contains information about PIN verification. This class fields are:

Field Type Description
pinId String ID of the PIN code for which verification process was started.
msisdn String Msisdn(phone number) for which verification process was started.
verified Boolean TRUE or FALSE depending on correctness of sent pin code.
attemptsRemaining Integer Number of remaining PIN attempts.
pinError String Tells if any error occurred during PIN verification. This field can have one of the following values: WRONG_PIN, TTL_EXPIRED, NO_MORE_PIN_ATTEMPTS.

IsPhoneNumberVerifiedResponse

The IsPhoneNumberVerifiedResponse class contains information about phone number verification statuses. The class has one field:

Field Type Description
verificationStatusList List<VerificationStatus> List of verification statuses for one phone number.

VerificationStatus

The VerificationStatus class contains information about phone number verification status for one PIN code.

Field Type Description
msisdn String Msisdn (phone number) for which verification status is checked.
verified Boolean Tells whether the phone number is verified or not.
verifiedAt Long If number is verified, this field contains UNIX timestamp (in millis) of verification time.
sentAt Boolean If message is sent to msisdn, this field contains UNIX timestamp (in millis) of sending time.

DeliveryInfoResponse

The DeliveryInfoResponse class contains information about delivery status of PIN code. PIN code can be resent, so the response contains the list of sent SMS statuses for one PIN code. This class has one field:

Field Type Description
deliveryInformation List<SMSDeliveryInformation> Delivery information for one PIN code.

SMSDeliveryInformation

Field Type Description
status Integer Sent SMS delivery status. Possible status values are listed here.
description String Sent SMS delivery status description.
finalStatus Boolean Tells if SMS delivery status is final.

Delivery status values

Status Description FinalStatus
MESSAGE_ACCEPTED Message accepted true
MESSAGE_NOT_SENT Message not sent false
MESSAGE_NOT_DELIVERED Message sent, not delivered true
MESSAGE_WAITING_DELIVERY Message sent, waiting for delivery false
MESSAGE_DELIVERED Message sent and delivered true
MESSAGE_NETWORK_NOT_ALLOWED Message not sent, network not allowed true
MESSAGE_NETWORK_NOT_AVAILABLE Message not sent, bulk or gateway offline true
MESSAGE_INVALID_DESTINATION_ADDRESS Message not sent, invalid destination address true
MESSAGE_DELIVERY_UNKNOWN Message delivery unknown true
INVALID_SOURCE_ADDRESS Message not sent, invalid source address true
NOT_ENOUGH_CREDITS Message not sent, not enough credits true
MESSAGE_REJECTED Message rejected true
MESSAGE_EXPIRED Message expired true
SYSTEM_ERROR System error true