iOS SDK Integration

The BlokSec SDK allows app developers to embed passwordless authentication into their own native siOS applications. In this way, users will have a smooth, consistent experience when authenticating to your application, and you don’t need to work about the complex details of building web or mobile-native authentication.

Compatibility

The BlokSec iOS SDK permits a deployment target of iOS 12.1 or higher. It requires Xcode 11+ and Swift 4.2+.

Dependencies

To be able to use the BlokSec SDK in iOS application, please follow the steps given below.

1. Download BlokSec.xcframework from the BlokSec public GitHub iOS SDK repository.

2. Embed the above xcframework file to Host Application.

3. In your app's source code files, use the following import syntax to include BlokSec Framework

“Import BlokSecFramework”

Prerequisites

To complete authentication flow when the request is sent through Email or SMS, it comes as a URL, which is specially formatted to be handled by the BlokSec SDK. These URLs will have the FQDN (fully-qualified domain name) of https://bloksec.io.

To properly handle these URLs, your app must be configured to handle the Universal links. (Please see [https://developer.apple.com/ios/universal-links/] (https://developer.apple.com/ios/universal-links/) for more information about universal linking in iOS.) Update your AppDelegate to respond to the user activity object the system provides when a universal link routes to your app, as described in Supporting Universal Links in Your App With these pre-requisites completed, you are ready to begin leveraging the SDK in your application.

SDK Usage (Initialise)

Each method in BlokSec SDK is asynchronous.

Before using any API of the BlokSec SDK, its necessary to initialize the SDK. This can be done by accessing the shared instance of BlokSec of type BlokSecSDK:

BlokSec.shared

Sample Usage

guard let bloksec = BlokSec.shared else {
// Failure Handling
return
}

New User Registration

To register a new user, BlokSec SDK provides the below method

/** This method is used to register the User with the specified Registration Request
    - Parameters:
        - request: request of type BSRegistrationRequest containing relevant information to get registered
 */

public func registerUser (request: BlokSecFramework.BSRegistrationRequest, 
withCompletion completion: BlokSecFramework.BlokSecSDKStartCompletion? = nil)

Create BSRegistrationRequest instance and call registerUser method

Sample usage

BlokSec.shared?.registerUser(request: registerNewUserRequest) { userId in 
  guard let userId = userId else {
      // Failure Handling
       return
    }
 }

Authentication

When you choose to login using BlokSec, an authentication request is sent to the app with a request ID which can be used to fetch the request object from the API. The authentication request may be sent via push notification, email, or SMS.

**Push Notification **To complete authentication flow use below APIs in the sequence.

1. Get the request ID from the push notification Payload

Email or SMS

In the case of Email or SMS, the user is given a URL with the domain https://bloksec.io/request/<requestID> which will be delegated to your app to handle as a deep link.

1. Extract <requestID> from the URL

After getting the request ID follow the below mentioned sequence of APIs to complete the authentication.

2. Use the request ID, to fetch the request details which could be displayed to the user and ask for the consent:

   BlokSec.shared?.getAuthenticationRequest(...)

3. Send the user response to the BlokSec service

   BlokSec.sendAuthenticationResponse(...)

Account Association

When an account is registered with BlokSec for passwordless login, an email is sent with a link containing a registration ID in the format https://bloksec.io/registration/<registrationID>

To complete the registration, follow the given sequence of APIs:

1. Retrieve <registrationID> from the deep link (in the same way request URLs are handled above)

2. Get the registration details using the method

   BlokSec.shared?.getRegistrationDetails(...)

3. Finally complete registration using the method

   BlokSec.shared?.completeRegistration(...)

Restore / Backup

This feature facilitates restore of all the accounts when you switch to new device or need to reset or restore the device (e.g., in the case of a lost phone)

Backup

To back up the user’s root account information, use the below method. It requires you to send a PIN / passphrase. This PIN is important as it is used to encrypt the data being saved to the output QR code and is therefore required during the restore process. Please provide clear instructions to the user not to forget this PIN / passphrase, and to keep the QR code in a safe place.

This method returns QR Code in form of UIImage. Save this QR Code securely. Without it, the user will not be able to restore their account(s) and would have to re-register.

BlokSec.shared?.createBackupQRCode(..)

Restore

To restore the user, scan (or load from photos) the QR code that was generated during backup. Use below method to restore the account by passing the data extracted from QR code along with the passphrase and the device Token:

BlokSec.shared?.restoreFromQRCode(...)

API Reference

Shared Instance API

/// Shared Instance to interact with the SDK
  public static let shared: BlokSecFramework.BlokSecSDK?

User Registration API

/** This method is used to register the User with the specified Registration Request
 - Parameters:
- request: request of type BSRegistrationRequest containing relevant information to get registered
*/
 func registerUser(request: BlokSecFramework.BSRegistrationRequest, withCompletion completion: BlokSecFramework.BlokSecSDKStartCompletion?)
 /** This Method is used to raise the registration  request for use
 - Parameters:
 - request:  registration request of type BSRaiseRegistrationRequest
- completion: Completion Closure providing the registration id of user
*/
 func raiseRegistrationRequest(request: BlokSecFramework.BSRaiseRegistrationRequest, withCompletion completion: @escaping BlokSecFramework.RaiseRegistrationRequestResponse)

Account Association APIs

/** This Method is used to get the registration details of user
- Parameters:
- registrationId:  registration Id to fetch the details of registration of user
- completion: Completion Closure providing the registration details of user of type RegistrationDetailsResponse
*/
 func getRegistrationDetails(registrationId: String, completion: @escaping BlokSecFramework.RegistrationDetailsResponse)
/** This Method is used to complete the registration of account
- Parameters:
- accountRequest:  account Request containing the meta data to create the account
- completion: Completion Closure providing the created account or error of type CreateAccountResponse
*/
func completeRegistration(accountRequest: BlokSecFramework.BSAccountRequest, completion: @escaping BlokSecFramework.CreateAccountResponse)

Authentication APIs

/** This Method is used to raise the authentication request for use
- Parameters:
- request:  auth request of type BSRaiseAuthenticationRequest
- completion: Completion Closure providing the registration id of user
*/
func raiseAuthenticationRequest(request: BlokSecFramework.BSRaiseAuthenticationRequest, withCompletion completion: @escaping BlokSecFramework.RaiseAuthenticationRequestResponse)

/** This Method is used to authenticate the user for particular application
- Parameters:
- requestId: Auth request Id received in universal URL or push notification to authenticated
- completion: Completion Closure providing the response of authentication or error of type AuthenticateRequestResponse
*/
func getAuthenticationRequest(requestId: String, completion: @escaping BlokSecFramework.AuthenticateRequestResponse)
/** This Method is used to authenticate the user for particular application
- Parameters:
- latestpushNotificationRequestModel: Auth request Id received in universal URL or push notification to authenticated
- completion: Completion Closure providing the response of authentication or error of type AuthenticateUserResponse
*/
func sendAuthenticationResponse(authRequest: BlokSecFramework.BSAuthenticationRequest, completion: @escaping BlokSecFramework.AuthenticateUserResponse)

Backup API

Returns a QR code which can be used later to restore the user's complete account tree. Note that a passphrase is used to encrypt the data; this passphrase must be supplied during the restore process in order to decrypt the incoming data. Without the valid passphrase, the QR code contains unusable, encrypted binary data.

/** This method returns the QR Image for the backed up account with the specified passphrase
- Parameters:
- passphrase: Passphrase entered by user to backup the Account
- Returns: Returns QR Code Image associated to the backup
*/
func createBackupQRCode(withPass passphrase: String) -> UIImage?

Restore API

/** This method is used to restore the Account from QR Info with the passphrase used during the backup
- Parameters:
- qrInfo: QR Info Retrieved by reading the QR of type String
- passphrase: Passphrase entered by user to restore the Account of type String
- deviceToken: Device Token in which the account needs to be restored of type optional String
- completion: Completion Closure of type UserProfileCompletion that provides information of restored account
*/
func restoreFromQRCode(_ qrInfo: String, usingPassPhrase passphrase: String, inDevice deviceToken: String?, withCompletion completion: @escaping BlokSecFramework.UserProfileCompletion) throws

Helper APIs

/** This Method is used to fetch the user Profile from Server
- Parameters:
- completion: Completion Closure providing the response of user profile or error of type UserProfileCompletion
*/
func getUserProfile(withCompletion completion: @escaping BlokSecFramework.UserProfileCompletion)