Android Integration

Components
Requirements
Operating System
Minimum supported version is 23
Software
Google fingerprint API/Device security pin
ThumbSignIn Android SDK
Account
An active account on ThumbSignIn platform.
Mobile Application
An Android mobile application to be integrated with ThumbSignIn.

Configuration Tasks

To use ThumbSignIn Fido SDK for your Mobile Application, follow the below steps:

Setup Your Project

  1. From the ThumbSignIn Dashboard, download ThumbSignIn Android SDK.
  2. Extract the zip and use Fido-sdk.aar file as a dependency in your Android app.

Register Mobile Application with ThumbSignIn

  1. From the ThumbSignIn Dashboard, inside a newly created application, click on Android section.
  2. Enter the facet Identifier of your application.e.g: with the prefix android:apk-key-hash:.

ThumbSignIn Android SDK

Follow the below steps to integrate ThumbSignIn Android SDK in your application.

SDK Configuration

The ThumbSignIn SDK needs an API-key to verify a valid app-integration. The integrating application needs to add this key as meta-data in their application manifest (inside application tag)

<application> . . . <meta-data android:name="pramati.fido.apiKey" android:value="some-api-key" /> . </application>

appId - The Application ID generated by ThumbSignIn for your application during application profile creation.

Permissions needed

<uses-permission android:name="android.permission.USE_FINGERPRINT" /> <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.USE_FINGERPRINT" /> <uses-permission android:name="android.permission.CAMERA" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <!-- Optional --> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Initialization

The ThumbSignIn SDK should be initialized as below:

public class ThirdPartyRelyingApp extends Application { public void onCreate() { super.onCreate(); . . ThumbSignIn.init(getApplicationContext()); . }

API Usage

The ThumbSignIn SDK can be used to enable two type of use cases

  1. Mobile Login: Log in to a mobile app installed on the phone
  2. Website Login: Log in to a website open in a desktop / mobile browser
  1. Mobile Login Use Case

    • Registration

      This function is to register the user for strong authentication using ThumbSignIn. It should be triggered after legacy login flow or via a setting once user logged in the app e.g. after username and password login.

      /** * Register a user, * @param username identifier of the user (Note: userIdentifier can be an internal mapping to the user provided to ThumbSignIn, not necessarily be the actual username or user id in your platform) * @param callback */ public static void register (String username, Callback callback) { }

      The callback is in the following format:

      /** * The final callback to return result to 3rd party app. */ public interface Callback { void onSuccess (TSResponse response); void onFailure (TSErrorCode errorCode); }
    • Authentication

      This function is to authenticate the user using fingerprint/pin via ThumbSignIn. Only successfully registered user can use this authenticator.

      /** * Authenticate a user * @param username * @param callback */ public static void authenticate(String username, Callback callback) {}
    • Transaction Confirmation

      /** * In addition to authentication show transaction text to user as well * @param username * @param transaction description of the transaction that needs to be displayed to user during fingerprint-authentication * @param callback */ public static void transact(String username, String transaction, Callback callback) {}
    • Deregistration

      This function is used to deregister the user from ThumbSignIn server. After the successful deregistration, the user will no longer be able to use ThumbsignIn authenticator unless he registers again.

      public static void dereg(Callback callback) {}
    • Callback parameters

      1. onSuccess method passes TSResponse (ThumbSignIn model)

        /** * This is a model class for final response received from FAAS. It is used in success callback to * return transaction info to app. The developer can use these information in various format. */ public class TSResponse { private boolean success; // Transaction status of the operation private String userId; // User identity private String transactionId; // Transaction ID private String token; // Optional! JWT web token(used for IoT Requirement) }
      2. onFailure method passes TSErrorCode (ThumbSignIn errorCode):

        /** * This class is used to return error codes to 3rd party app */ public enum TSErrorCode { INTERNET_NOT_AVAILABLE("Connectivity error", "Internet connectivity error"), TIMEOUT("Operation failed", "Transaction timed out!"), NO_ERROR("No error", ""), USER_CANCELLED("Operation cancelled", "You have cancelled the operation"), NOT_VERIFIED_APK("Apk not verified", "SDK integration failure during configuration validation"), NO_SECURITY_ENABLED("Security not enabled", "Operation Failed as Fingerprint/Pin is not available or set up"), NOT_REGISTERED("Authentication not enabled", "Passwordless Authentication for %1$s not yet enabled using this device. Log in using your password on the website to enable passwordless authentication."), USER_ALREADY_REGISTERED("Already enabled", "Passwordless Authentication has already been enabled using this device"), SERVER_ERROR("Operation failed", "Sorry for the inconvenience. Please try again!"), FORMAT_ERROR("Invalid QR Code", "The QR code you scanned is not valid"), ERROR_SDK("Operation failed", "The ThumbSignIn SDK reports error"), UNKNOWN("Operation failed", "Please try again!"); }
    • Additional Methods added for IoT requirement

      Note: These are exposed to 3rd party Apps only upon request.

      /** * Authenticates an IoT device * * @param username * @param callback */ public static void authenticateiOT(String username, Callback callback) {}

      Jwt web token can be fetched via TSResponse parameter in success Callback.

      ThumbSignIn.authenticateiOT(PreferenceManager.getUserName(), new ThumbSignIn.Callback() { @Override public void onSuccess(TSResponse response) { Log.d(TAG, "received token: "+response.getToken()); } @Override public void onFailure(TSErrorCode errorCode) { //... do something } });
  2. Website Login Use Case

    This function is to initiate the QR code based Registration and Authentication in ThumbSignIn server.

    1. After, successful legacy-login(existing login process of the application eg: username, password) to vendor’s website, a user can start FIDO registration process. The user can scan ThumbSignIn generated QR code and forward the scanned raw text data to FIDO sdk
    2. Once, a user is FIDO-registered with ThumbSignIn, he can login directly to website by scanning QR displayed on vendor’s homepage.

    Note: if QR code has deeplink as prefix, i.e. {deepLinkPrefix}/:::{qr - base64 - content}, this method will automatically extract {qr - base64 - content} and do further operation

    /** * Handles QR content. Method will extract QR code after splitter(/:::), if it exists. * * @param qrContent * @param callback */ public static TSScanResult handleQRContent(String qrContent, ThumbSignIn.Callback callback) {}

    How to know Facet-Id (HASH of apk-signing certificate)

    /** * FacetID MUST be a URI derived from the Base64 encoding SHA-1 hash of the APK signing certificate. * [APK-Signing]: android:apk-key-hash:<base64_encoded_sha1_hash-of-apk-signing-cert> * * TODO: check and match if apk-hash string can be renamed to "pramati-fido-key" string. * @return FacetID */ public static String getFacetID() { Context context = ThumbSignIn.getContext(); try { PackageInfo paramPackageInfo = context.getPackageManager().getPackageInfo(context.getApplicationContext(). getPackageName(), context.getPackageManager().GET_SIGNATURES); ByteArrayInputStream byteArrayInputStream = new ByteArrayInputStream(paramPackageInfo.signatures[0].toByteArray()); Certificate certificate = CertificateFactory.getInstance("X509").generateCertificate(byteArrayInputStream); MessageDigest messageDigest = MessageDigest.getInstance("SHA1"); String facetID = "android:apk-key-hash:" + Base64.encodeToString(messageDigest.digest(certificate.getEncoded()), 3); return facetID; } catch (Exception e) { Log.e ( "FACET-ID", "Can't fetch facet-ID", e); } return null; }
  3. DeepLink Support

    This method expects a map having transaction content under transaction tag. If you intend to provide raw transaction data(data under ‘transaction’ tag), you can use ThumbSignIn#handleQRContent method instead.

    /** * Handle deeplink forwarded via 3rd party application, * The input string is map/dictionary, which must have <b>transaction<b/> or (<b>transactionId * and op both</b>) value. If input is invalid one, it will throw @{@link IllegalArgumentException}. * * @param deepLinkJson * @param callback * @throws IllegalArgumentException */ public static void handleDeepLink(String deepLinkJson, ThumbSignIn.Callback callback) {}

Sample App

The four different API methods need to be invoked at different points during the app user experience and the success/failure scenarios handled during the respective callbacks.

  1. For Registration, the developers could initiate registration API for the user after legacy login flow(existing login process of the application. eg: username, password) to relying-party application. See the illustration below for a sample implementation:

  2. Now, users can be prompted to register for FIDO, If he agrees for FIDO registration, then invoke the ThumbSignIn#registration API, otherwise proceed with user logged-in screen.

  3. Now, after successful fingerprint/pin verification, the user will be registered with ThumbSignIn.

  4. For Authentication, the developers can trigger an authentication API from the legacy login screen by displaying it as the alternative option to login. The authentication API needs to be triggered only after the user successfully registered with ThumbSignIn. See the illustration below for a sample implementation.

  5. Use the transaction API to authenticate users before any kind of transaction or functionality e.g. “pay $100 Bill”.

  6. You can enable the deregister functionality for the user if he/she wants to opt out of passwordless login. This API can be triggered by any settings section of the App.