📘

Before proceeding with this document, please make sure that you've integrated the HYPR SDK documented here: General Setup

Overview

Out-of-Band Authentication provides the means to login to a web account on a browser via your mobile device.

The first step is to pair your mobile device with your web account via Out-of-Band Device Setup. (Instructions will be shown later)

After performing Out-of-Band Device Setup, you can now login via Out-of-Band Authentication with the following steps:

1. Provide the web account username
2. Invoke the Out-of-Band Authentication API which will send a push notification to the mobile device prompting the mobile to authenticate. Upon successful authentication, the web account will be unlocked.

Before performing out-of-band authentication please make sure to setup Firebase and your app with the documentation below:
iOS Firebase Out-of-Band Authentication Setup

Currently we have two Web SDKs, select the appropriate documentation which details how to perform Out-of-BandAuthentication.

Javascript Web SDK Out-of-Band Authentication with iOS
Java Web SDK Out-of-Band Authentication with iOS

📘

Out of Band Authentication (OOB)

Out of Band Authentication is where you authenticate to your resource through another channel. An example of Out of Band Authentication is, if you are trying to login to a website on your Desktop browser, and you authenticate into that website with your mobile application on your mobile device.

Below is a video on demonstrating Out of Band Authentication for Web Account Login.

Part 1: Setup Firebase Project

As demonstrated in the video above, we facilitate Out of Band Authentication via Push Notifications. Below are steps for setting up Firebase for push notifications in your application.

Step 1: Sign up for Firebase if you haven't already
Step 2: Go to the Firebase console
Step 3: Login/Sign
Step 4: Create project and open project or open existing project

Step 5:Open up the Project Settings

Step 6: Keep a reference to the Server Key and Sender ID

Part 2: Configure Control Center for Push Notifications

Step 1: Login to your Control Center and select RP Application that needs to be configured.

Step 2: Edit Application to add Push Notification configuration.

Step 3: Navigate through steps 1 and 2

Step 4: Add Firebase configuration parameters

Step 5: Click Next and Save.

Part 3: Add Firebase to your iOS Project

Step 1: Navigate to your Firebase Account Dashboard and create iOS project

Step 2: Configure your project according to screenshot below.

Step 3: Follow instructions to integrate Firebase SDK into your iOS project.

Part 3: Add Firebase SDK to your iOS Project

Step 1: Create a group to contain the frameworks

Step 2: Embed and Link the HYPR Frameworks

Step 3: Add the GoogleService-Info.plist

Pairing the Web Account with the Mobile Device

In order to pair your mobile device with the web account, you'll need generate the PIN/QR Code and call HYPRUserAgent's registerRemoteDevice method which has two ways to pair either through PIN or QR Code.

Out of Band Device Setup has an option of presenting an Alert View Controller that accepts a PIN or a QR Code Scan view.
To display an Alert View Controller for PIN input, please use one of two public methods provided as shown below. Either one of those two methods will prompt an Alert View Controller for PIN input.

📘

The default policy for remote device registration is defaultRegAction. This means that the authenticators specified in defaultRegAction will be the authenticators used during remote device registration. To learn more about policies, please refer to this document: iOS Policy Matching

PIN Entry setup example

class ViewController: UIViewController {
  func outOfBandDeviceSetup() {
    HYPRUserAgent.setParentViewController(self)
    // Here you need to pass in .alert for pinInputType
    HYPRUserAgent.sharedInstance().registerRemoteDevice(forUser: nil, pinInputType: .alert, actionId: "<your policy name goes here>") { error in
      if let error = error {
        // Handle Error
        print(error)
      }
      else {
        // Out of Band Device Setup is successful
        print("Out of Band Device Setup Successful!")
      }
    }
  }
}

Alert PIN Input View

To display a QR Code Scan View, please use below method provided as shown below. In addition, title text, title color, title font, and logo image can be modified as shown below.

class ViewController: UIViewController {
  func outOfBandDeviceSetup() {
    HYPRUserAgent.setParentViewController(self)
    // Setting UI elements for QR Scan view
    let qrCodeConfig = HYPRViewConfiguration.qrCodeViewConfiguration()
    qrCodeConfig.titleText = "SCAN QR CODE"
    qrCodeConfig.titleFont = UIFont(name: "You Font", size: 16.0)
    qrCodeConfig.titleColor = UIColor.white
    qrCodeConfig.logoImage = UIImage(named: "you logo")
    // Here you need to pass in .qrCodeScan for pinInputType
    HYPRUserAgent.sharedInstance().registerRemoteDevice(forUser: nil, pinInputType: .qrCodeScan, actionId: "<your policy name goes here>") { error in
      if let error = error {
        // Handle Error
        print(error)
      }
      else {
        // Out of Band Device Setup is successful
        print("Out of Band Device Setup Successful!")
      }
    }
  }
}

QR Code Scan View

Processing the Push Notification

Here are steps to enable push notifications and also enabling your authenticator(s). For the purposes of demonstration we will only enable the PIN authenticator.

We need to enable push notifications and authenticators during App startup so we placed it within AppDelegate.swift.

Within func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) , if the callback in HYPRFirebaseAdapter.handlePushPayloadUserInfo returns an error in the callback, then out of band authentication was unsuccessful. You'll need to inform the user of that at that point.

The HYPRFirebaseAdapter.handlePushPayloadUserInfo method returns a userInfo dictionary in the completion block. The following keys will return the corresponding values:

import HyprCore
import HyprCore
import HYPRPIN
import HYPRFirebaseNotificationAdapter

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    // Enable any authenticator you like. 
    // We are just enabling PIN for the purposes of demonstration
    HYPRUAFClient.registerAuthenticatorModule(HYPRPINAsm.self)
    
    // Set SSLPinningEnabled to true if you are using SSL Pinning
    HYPRUserAgent.setSSLPinningEnabled(false)
    HYPRUserAgent.setNotificationProviderAdapter(HYPRFirebaseAdapter.shared())
    HYPRFirebaseAdapter.shared().userPushNotifications(enabled: true)
    if HYPRUserAgent.sharedInstance().activeProfile() == nil {
      let config = HYPRUserAgentProfileConfiguration(
        rpAppId: "Relying Party App ID i.e: HYPRDefaultApplication",
        rpServerUrl: "Relying Party URL i.e.: https://9999-pov.hypr.com",
        deviceType: "WEB",
        rpSSLPinCredentials: nil,
        additionalData: nil)
        
        let profile = HYPRUserAgentProfile(displayName: "Place a profile name name here: i.e. MyProfile",
          configuration: config,
          persona: nil,
          userAccounts: nil)
          
        HYPRUserAgent.sharedInstance().registerProfile(profile!)
      }
    return true
  }
  
  func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    if let rootController = self.window?.rootViewController {
      HYPRUserAgent.setParentViewController(rootController)
    }
    let didHandle = HYPRFirebaseAdapter.handlePushPayloadUserInfo(userInfo) { (responseUserInfo, error) in
      //the responseUserInfo includes one or more key-value pairs. Keys are:
      //extern NSString * const HYPR_OOB_ACTION_TITLE_KEY;
      //extern NSString * const HYPR_OOB_ACTION_MESSAGE_KEY;
      //extern NSString * const HYPR_OOB_ACTION_TYPE;  
      //details can be found in HYPRPushNotificationAdapter.h
      // if there is no error, then success
      // if there is an error, with code != cancelled, then fail
      if error == nil {
        print("push notification successfully processed!")
      } else if let hyprError = error as NSError?, hyprError.code != HYPRError.cancelled.rawValue {
        print("\(#function): \(hyprError.description)")
      }
    }
  
    if didHandle {
      completionHandler(.newData)
    } else {
      completionHandler(.noData)
    }
  }
}

In order to perform out of band authentication upon receiving the push, add the following line of code in your Initial View Controller's viewWillAppear method.

class ViewController: UIViewController {
    
    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        HYPRUserAgent.setParentViewController(self)
    }
}

🚧

Your application will not process the Out of Band push notification unless your initial view controller has the following method in its viewWillAppear method. HYPRUserAgent.setParentViewController(self)

UI Customization

📘

This document only covers UI Customization for iOS

Out of Band Device Setup has an option of presenting an Alert View Controller that accepts a PIN or a QR Code Scan view.

To display an Alert View Controller for PIN input, please use one of two public methods provided as shown below. Either one of those two methods will prompt an Alert View Controller for PIN input.

class ViewController: UIViewController {
  func outOfBandDeviceSetup() {
    HYPRUserAgent.setParentViewController(self)
    // Here you need to pass in a nil for pin to prompt an alert for PIN input
    HYPRUserAgent.sharedInstance().registerRemoteDevice(forUser: nil, pin: nil, actionId: "<your policy name goes here>") { error in
      if let error = error {
        // Handle Error
        print(error)
      }
      else {
        // Out of Band Device Setup is successful
        print("Out of Band Device Setup Successful!")
      }
    }
  }
}

class ViewController: UIViewController {
  func outOfBandDeviceSetup() {
    HYPRUserAgent.setParentViewController(self)
    // Here you need to pass in .alert for pinInputType
    HYPRUserAgent.sharedInstance().registerRemoteDevice(forUser: nil, pinInputType: .alert, actionId: "<your policy name goes here>") { error in
      if let error = error {
        // Handle Error
        print(error)
      }
      else {
        // Out of Band Device Setup is successful
        print("Out of Band Device Setup Successful!")
      }
    }
  }
}

Alert PIN Input View

To display a QR Code Scan View, please use below method provided as shown below. In addition, title text, title color, title font, and logo image can be modified as shown below.

class ViewController: UIViewController {
  func outOfBandDeviceSetup() {
    HYPRUserAgent.setParentViewController(self)
    // Setting UI elements for QR Scan view
    let qrCodeConfig = HYPRViewConfiguration.qrCodeViewConfiguration()
    qrCodeConfig.titleText = "SCAN QR CODE"
    qrCodeConfig.titleFont = UIFont(name: "You Font", size: 16.0)
    qrCodeConfig.titleColor = UIColor.white
    qrCodeConfig.logoImage = UIImage(named: "you logo")
    // Here you need to pass in .qrCodeScan for pinInputType
    HYPRUserAgent.sharedInstance().registerRemoteDevice(forUser: nil, pinInputType: .qrCodeScan, actionId: "<your policy name goes here>") { error in
      if let error = error {
        // Handle Error
        print(error)
      }
      else {
        // Out of Band Device Setup is successful
        print("Out of Band Device Setup Successful!")
      }
    }
  }
}

QR Code Scan View

Customizable properties for QR Code Scan View in 'HYPRUserAgentQRCodeViewConfiguration'

If you are creating your own Out of Band Device Setup screen, you'll need to create a view controller that takes in the 6 digit pin. Once you have that PIN, you'll need to provide that PIN to the HYPRUserAgent's registerRemoteDevice method as shown below.

class ViewController: UIViewController {
  func outOfBandDeviceSetup() {
    HYPRUserAgent.setParentViewController(self)
    // Here you pass in your PIN 
    HYPRUserAgent.sharedInstance().registerRemoteDevice(forUser: nil, pin: "<Your pin here>", actionId: "<your policy name goes here>") { error in
      if let error = error {
        // Handle Error
        print(error)
      }
      else {
        // Out of Band Device Setup is successful
        print("Out of Band Device Setup Successful!")
      }
    }
  }
}

📘

iOS Apple Push Notification Service (APNS)

In order to get push notifications when your app is backgrounded, you'll need to add the certificate to your Firebase iOS Project. Please refer to this document for more information
https://firebase.google.com/docs/cloud-messaging/ios/certs
Creating an Out of Band Certificate

After Out of Band Device Setup is implemented, you can now perform Out of Band Authentication. For more information, please refer to the following documentation:

Javascript Web SDK Out of Band Authentication with iOS
Java Web SDK Out of Band Authentication with iOS

Setting limit to the number of Relying Party Profiles

If you want to limit the number of Relying Party call the following method the user can have, call the following method:

HYPRUserAgent.sharedInstance().setLimit(<your limit goes here>, forProfilesOf: .web)

Register with JSON Content

If the Server API Version used to communicate with the server is 4+ then the QR Code content used for web account pairing will be JSON.
With that being said, if the preference is to not scan a QR Code to register, there is an option to register with the JSON Content that the QR Code represents directly.

Code Example

HYPRUserAgent.sharedInstance().registerRemoteDevice(withJsonContent: contentJson) { error in
if let error = error {
    // Process Error
  } else {
    self.presentInfoAlert(title: "Success!", message: "Registered Successfully!")
  }
}

📘

iOS Apple Push Notification Service (APNS)

In order to get push notifications when your app is backgrounded, you'll need to add the certificate to your Firebase iOS Project. Please refer to this document for more information
https://firebase.google.com/docs/cloud-messaging/ios/certs
Creating an Out of Band Certificate

After Out of Band Device Setup is implemented, you can now perform Out of Band Authentication. For more information, please refer to the following documentation:

• Javascript Web SDK Out of Band Authentication with iOS
• Java Web SDK Out of Band Authentication with iOS