Falcon Device Binding SDK

The Falcon Device Binding SDK is a powerful Android library designed to secure open APIs by providing secure short-lived tokens. It enables Android projects to generate tokens using device binding, which involves generating a unique device fingerprint and mapping it to users. This mapping is stored on the backend server and ensures that our APIs are accessed only from the user's registered device.

The device fingerprint, along with a time-based one-time password (OTP), is then used to generate request tokens for API calls. These tokens have a 30-second validity. The library also provides functionality to check the validity of the device binding status and handle scenarios where the user has changed their device.

This documentation provides an overview of the objectives, technical specifications, integration steps, and details of the available functions in the Falcon Authentication SDK.

Technical Specifications

• Minimum Supported SDK: API level 21 (Android 5.0 Lollipop) or higher.
• Library File Extension: .aar (Android Archive)
• Latest version: v1.0.0
• Permissions required on Android

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

Getting Started

To integrate the Falcon Authentication SDK into your Android project, follow these steps:

1. Download the Falcon Authentication SDK

• Download the latest version of the Falcon Authentication SDK from the official repository.
• Extract the downloaded SDK package.

2. Import the Library into your Android Project

• Create a new directory named libs under android/app.
• Copy the falconauthsdk.aar file into the libs directory
• The library module will be added to your project.

3. Add Library Dependency

• Open the build.gradle file of your app module.
• Add the following line to the dependencies block:

implementation files('libs/falconauthsdk.aar')
implementation 'commons-codec:commons-codec:1.15'

4. Sync and Build

• Sync the project with Gradle files to ensure the library is properly added.
• Build the project to verify that the library is successfully integrated.

Integration

The library’s functionality can be broadly classified under two main headings namely device binding and token generation. Let’s look the steps for both these functionalities.

Device Binding

To Initiate the process of Device Binding, the SDK provides a function named initiateDeviceBinding

Params

Sample

import com.falconfsauth.sdk.DeviceBinding;
import com.falconfsauth.sdk.Utils.ApiUtils;

DeviceBinding.initiateDeviceBinding(appContext, enterpriseId, authorization, mobileNumber, userId, new ApiUtils.Callback<String>() {
      @Override
      public void onSuccess(String s, Integer integer) {
          promise.resolve(s);
      }

      @Override
      public void onError(Exception error) {
          promise.reject(error.getMessage());
      }
  });

Response

Send Verification SMS

To verify that the user trying to login has a SIM card with that number currently available in the device, the SDK provides a function named sendRegistrationSMS

Params

Sample

import com.falconfsauth.sdk.DeviceBinding;
import com.falconfsauth.sdk.SendSMSCallback;

DeviceBinding.sendRegistrationSMS(appContext, virtualMobileNumber, smsContent, simSlotIndex, silent, new SendSMSCallback() {
      @Override
      public void onSuccess(String result) {
          promise.resolve("SMS_SENT: " + result);
      }

      @Override
      public void onError(String error) {
          promise.reject("SMS_FAILED: " + error);
      }
  });

Check Binding Status

After the SMS has been successfully sent, call checkBindingStatus to check whether the binding was successful. You may call this a few times at a fixed interval of 10 seconds to get the updated status.

Params

Sample

import com.falconfsauth.sdk.DeviceBinding;
import com.falconfsauth.sdk.Utils.ApiUtils;

DeviceBinding.checkBindingStatus(appContext, enterpriseId, authorization, mobileNumber, userId, token, new ApiUtils.Callback<String>() {
      @Override
      public void onSuccess(String s, Integer integer) {
          promise.resolve(s);
      }

      @Override
      public void onError(Exception error) {
          promise.reject(error.getMessage());
      }
  });

Response

Token Generation

After the SMS has been successfully sent, call checkBindingStatus to check whether the binding was successful. Once the state changes to VERIFIED, you may call this function to generate the request tokens.

Params

Sample

import com.falconfsauth.sdk.DeviceBinding;

String requestToken = DeviceBinding.generateRequestToken(deviceToken, totpSecret);

Response