Infobip 2-factor authentication Android library

Requirements

The lowest required Android SDK version is set to 8.

Step by step integration

Download Android library from here.
Copy the library file into the libs folder.
Add dependency to build.gradle file (compile (name:'infobip-2fa', ext:'aar')).
Add user permissions to application project Manifest.xml file.
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:

sendPin,
resendPin,
verifyPin,
isPhoneNumberVerified,
getDeliveryInfo.

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(SendPinResponse response),
onError(int errorCode, String errorDescription).

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(SendPinResponse response),
onError(int errorCode, String errorDescription).

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(VerifyPinResponse response),
onError(int errorCode, String errorDescription).

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(IsPhoneNumberVerifiedResponse response),
onError(int errorCode, String errorDescription).

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(DeliveryInfoResponse response),
onError(int errorCode, String errorDescription).

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