iOS Integration

If you have your own iOS/Android app and want to integrate ThumbSignIn capabilities with your mobile app.

How to use the ThumbSignIn mobile SDK in your app?

A mobile application which uses this SDK is called a ‘Relying Party’(RP). To use the ThumbSignIn SDK within your mobile app, follow these steps:

  1. Sign Up on the official thumbsignin site and create an app by specifying the App name, Description and Logo.
  2. Get familiar with the technical terms mentioned on your developer dashboard.
  3. Download the iOS/Android ThumbSignin SDK from your dashboard.
  4. Add this SDK to your mobile app’s codebase.
  5. Use the operations exposed by the SDK within your mobile app. These are described in the next section.

Main Operations of the ThumbSignIn SDK

  • Registration
  • Authentication
  • Transaction Confirmation
  • De-Registration
Components
Requirements
Operating System
Minimum supported version is iOS 9.3
Software
Xcode 8 and above
ThumbSignIn iOS SDK
Account
A developer account with Apple. An active account on ThumbSignIn platform.
Mobile Application
An iOS mobile application to be integrated with ThumbSignIn

Configuration Tasks

To use ThumbSignIn iOS SDK for your iOS App, follow the steps listed below:

  1. From the ThumbSignIn Dashboard, download ThumbSignIn iOS SDK.
  2. Unzip the SDK and drag-drop the .framework file into your XCode project.
  3. Select Create groups and select Copy items if needed in the prompt that appears.
  4. Click the Build Settings tab and add the flag -ObjC​ to the Other Linker flags setting.

Register Mobile Application with ThumbSignIn

  1. From the ThumbSignIn Dashboard, inside a newly created application, Click on iOS section.
  2. Enter the Bundle Identifier of your application after the template ios:bundle-id:

ThumbSignIn iOS SDK

SDK Configuration

The ThumbSignIn SDK uses ThumbSigninConfiguration.plist for configuring ThumbSignIn services. In your project, create an ThumbSigninConfiguration.plist file and replace the following values in the sample below with that of the values obtained during Application profile creation in the iOS Application section.

  • appId - The Application ID that is generated by ThumbSignIn for your application.

    <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>appID</key> <string>Your Application ID</string> </dict> </plist>
  • Invoke startManager method in didFinishLaunchingWithOptions method. See below

    [[ThumbSignInManager sharedManager] startManager];
  • Invoke the isUserRegistered method to check whether a user registration is available.

  • Invoke the enableAlternateLoginMechanism method right below the startManager method to display alternate login mechanisms using device passcode. See the example below.

    [[ThumbSignInManager sharedManager] enableAlternateLoginMechanism];

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 passwordless authentication mechanism using ThumbSignIn.This function can be triggered after legacy login flow or via a setting once user logged in the app (For eg: After Username & Password login).

      -(NSDictionary*)registerUser:(NSString*)userIdentifier successCallback:(TSSuccessCallBackBlock)successCallback errorCallback:(TSErrorCallBackBlock)errorCallback;
      1. @param userIdentifier: 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)
      2. @param successCallback: successCallback block to be performed after Successful Operation
      3. @param errorCallback: errorCallback block to be performed after Successful Operation
      4. @return domain related information like AppName[Key:"appName"] and iconURL[Key:"iconUrl"]

      TSSuccessCallBackBlock returns a ThumbSignInTransaction Model Object which contains the below properties

      NSString *status;/*Transaction status of the operation*/ NSString *userId;/*User identity*/ NSString *transactionId;/*The Transaction ID*/

      Use this model object to retrieve the transaction details of the registered user.TSErrorCallBackBlock returns a NSError type.

      Compare the error code of NSError with TSErrorsEnum to display the corresponding error message to the user.

    • Authentication

      This function is to authenticate the user using TouchID via ThumbSignIn. Only successfully registered user can use this Authenticator.

      -(void)authenticateWithSuccessCallback:(TSSuccessCallBackBlock)successCallback errorCallback:(TSErrorCallBackBlock)errorCallback;
      1. @param successCallback: block to be performed after successful Operation
      2. @param errorCallback: block to be performed after successful Operation
    • Transaction Confirmation

      This function is to authenticate the transaction for a user.

      -(void)authenticateTransactionWithDescription:(NSString*)description successCallback:(TSSuccessCallBackBlock)successCallback errorCallback:(TSErrorCallBackBlock)errorCallback;
      1. @param transactionContent: description of the transaction that needs to be displayed to the user during TouchID prompt.
      2. @param successCallback: block to be performed after successful Operation
      3. @param errorCallback: errorCallback block to be performed after successful Operation
    • 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 the Thumbsignin Authenticator unless he registers again.

      -(void)deregisterUserWithSuccessCallback:(TSSuccessCallBackBlock)successCallback errorCallback:(TSErrorCallBackBlock)errorCallback;
      1. @param successCallback: block to be performed after successful Operation
      2. @param errorCallback: block to be performed after successful Operation
  2. Website Login Use Case

    This function is used to initiate the QR code based Registration and Authentication in ThumbSignIn server using the QR code shown on the website after integration with ThumbSignIn.

    -(void)scanQRcode:(NSString *)QRContent withSuccessCallback:(TSSuccessCallBackBlock)successCallback error:(TSErrorCallBackBlock)errorCallback;
    1. @param QRContent: QRContent scanned from the QR code shown on the vendor’s website
    2. @param successCallback: block to be performed after successful Operation
    3. @param errorCallback: block to be performed after successful Operation

    Refer to this link for sample implementations to scan a QR code shown on the website.

  3. DeepLink Support

    What is Deep Link Support in ThumbSignIn?

    When a user opens a ThumbSignIn enabled web page in the mobile browser on the same phone as the one that has the authenticator app, there is obviously no way to scan the QR code using the camera. Mobile App Deep Linking enables strong authentication in this scenario by invoking the authenticator app when the user taps on a link on the web page.

    The following function is used to support registration and authentication using a deep link created via Branch.io.

    -(void)handleDeepLink:(NSDictionary *)deepLinkParameters withSuccessCallback:(TSSuccessCallBackBlock)successCallback error:(TSErrorCallBackBlock)errorCallback;
    1. @param deepLinkParameters: the dictionary received from branch.io
    2. @param successCallback: block to be performed after successful Operation
    3. @param errorCallback: block to be performed after successful Operation

    The following function is used to support registration and authentication using a deep link via URL schema.

    -(void)handleDeepLinkViaURLSchema:(NSURL *)url viaWebview:(BOOL)viaWebview withSuccessCallback:(TSSuccessCallBackBlock)successCallback errorCallback:(TSErrorCallBackBlock)errorCallback;
    1. @param URL: url you receive from -(BOOL)application:(UIApplication *)app openURL delegate function
    2. @param viaWebview : set the Bool value as true if deeplink is handled via webview.
    3. @param successCallback: block to be performed after successful Operation
    4. @param errorCallback: block to be performed after successful Operation

    Use the Deregistration API functionality available in the Mobile integration section above to deregister the user.

Integration with Swift Project

With the help of ‘Bridging Header File’ - we could easily use this Thumbsignin framework in any iOS applications which are developed in Swift.The developer has to enter #import statements (#import <TSFIDOUAF /TSFIDOUAF.h>) to this file and framework classes will be available in Swift project code without any additional #import statements.

Sample App

This section should answer “ Where in the iOS app should we add the code?”. Developers could invoke at instances where passwordless mechanisms are required using the above mentioned 4 methods. They could handle the success/failure scenarios in respective callbacks.

  1. REGISTRATION - Invoke the registration API to register users at any point after legacy login flow (existing login process of the application e.g. username/password)

  2. AUTHENTICATION - Invoke the authentication API from the legacy login screen by displaying it as the alternative option to log in. The authentication API should be triggered only after the user has successfully completed the registration step

  3. TRANSACTION - Use the transaction API to authenticate users before any kind of transaction or functionality. For eg:(“pay 500 $ Bill”).

  4. DEREGISTRATION - Enable the deregister functionality for the user if he/she wants to opt out of passwordless login. This API can be made available in settings of the App.

Sample code in Swift

Register

ThumbSignInManager.shared().registerUser("PramatiUser123", successCallback: { (tsModel) in print("sucess(tsModel!)") }) { (tsError) in print("error:(String(describing: tsError))")}

Authenticate

ThumbSignInManager.shared().authenticate(successCallback: { ( tsModel) in print("sucess(tsModel!)") }) { (tsError) in print("error:(String(describing: tsError))")}

Transaction

ThumbSignInManager.shared().authenticateTransaction(withDescription: "$500", successCallback: { ( tsModel) in print("sucess(tsModel!)") }) { (tsError) in print("error:(String(describing: tsError))")}

DeRegister

ThumbSignInManager.shared().deregisterUser(successCallback: { (tsModel) in print("sucess(tsModel!)") }) { (tsError) in print("error:(String(describing: tsError))") }

Error Codes

The following error codes may be returned while using ThumbSignIn iOS SDK:

typedef NS_ENUM(NSInteger, TSErrorsEnum) { /*UAF protocol failure*/ TS_TECHNICAL_ERROR=8001, /* User cancelled the transaction when touchID is prompted*/ TS_USER_CANCELLED=8002, /*TouchID is not available or setup*/ TS_NO_SUITABLE_AUTHENTICATOR=8003, /*If the APPID configured in the plist failed during configuration check with the ThumbSignIn server*/ TS_APPID_VALIDATION_FAILED=8004, /*If the device is jailbroken*/ TS_DEVICE_JAILBROKEN=8005, /*If the operation failed due to untrusted bundle identifier. The bundle identifier configured inin the ThumbSignIn Dashboard does not match with the one in the project*/ TSERROR_UNTRUSTED_FACETID=8006, /*IF the SDK version is unsupported*/ TSERROR_UNSUPPORTED_VERSION=8007, /*If the operation failed due to some unknown reason*/ TSERROR_UNKNOWN=8008, /*Internet connectivity error*/ TSERROR_NETWORK=8009, TSERROR_REGISTRATION_NOT_AVAILABLE=8010, TSERROR_SAME_USER_ALREADY_REGISTERED=8011, TSERROR_INVALID_ERROR_QRCODE=8012, TSERROR_TIMED_OUT=8013, /*Default Enum*/ TSERROR_NULL=8999 }

Face ID Support

Face ID required adding a usage string with the key NSFaceIDUsageDescription(aka Privacy - Face ID Usage Description) to your app’s Info.plist.

If your app attempts to access Face ID without a corresponding purpose string, your app may exit.