Falcon Device Binding SDK
SDK for Device Binding and Token Management
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:
- Download the latest version of the Falcon Authentication SDK from the official repository.
- Extract the downloaded SDK package.
- 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.
- 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'
- 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
Name | Type | Description |
---|---|---|
appContext | Context | The context of the current activity |
enterpriseId | String | The enterprise ID of the current user |
authorization | String | Basic Authentication header key (Shared while onboarding) |
mobileNumber | String | Mobile number of the current user |
userId | String | User ID of the current user |
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
Name | Type | Description |
---|---|---|
token | String | This is the device registration token which will be sent in the verification SMS |
virtualMobileNumber | String | This the number where the verification SMS should be sent |
keyword | String | This keyword will be used as a prefix in the verification SMS content separated by a space |
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
Name | Type | Description |
---|---|---|
appContext | Context | The context of the current activity |
virtualMobileNumber | String | The verification SMS will be sent to this number |
smsContent | String | The contents of the verification sms. This is a combination of the keyword and deviceToken separated by a space. These values are received from the registration API. Example: "flcnp xxxxxxxtokenxxxxxxxx" |
simSlotIndex | String | Use this to control which SIM card to use for sending the SMS. This must be the same number as the one registered with us |
silent | Boolean | Use this to control whether the default SMS app will be opened to send the SMS. If silent is true, the SMS will be sent in the background. We strongly recommend using silent as true. |
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
Name | Type | Description |
---|---|---|
appContext | Context | The context of the current activity |
enterpriseId | String | The enterprise ID of the current user |
authorization | String | Basic Authentication header key (Shared while onboarding) |
mobileNumber | String | Mobile number of the current user |
userId | String | User ID of the current user |
token | String | This is the device registration token received from the registration API |
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
Name | Type | Description |
---|---|---|
state | String | This will be either PENDING or VERIFIED. The state changes from PENDING to VERIFIED if the verification SMS was sent from the registered number successfully. The state will change to EXPIRED if the device binding was re-initiated |
deviceToken | String | This is the deviceToken needed for generating requestTokens |
secret | String | This is the totpSecret that will be used to generate the request token |
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
Name | Type | Description |
---|---|---|
deviceToken | String | This is the device token received from the check binding status API |
totpSecret | String | This is the totp secret received from the check binding status API |
Sample
import com.falconfsauth.sdk.DeviceBinding;
String requestToken = DeviceBinding.generateRequestToken(deviceToken, totpSecret);
Response
Name | Type | Description |
---|---|---|
requestToken | String | This is the request token which should be sent in the API calls |
Updated 6 days ago