HYPR Passwordless

In this document we'll cover how to use HYPR SDK for iOS to add HYPR Passwordless functionality to your App.

Things to Know about the HYPR SDK for iOS

HYPRUserAgent Data Model

HYPRUserAgent may have multiple profiles; each profile may have multiple userAccounts; each user accoun may have multiple RemoteDevices (Workstations).

This document focuses on the interaction with RemoteDevices (Workstations). If your App will have workstations from more than one server or rpAppId, your SDK will include more than one profile and corresponding userAccount. In this case, to interact with the workstation you must switch the active profile and (optional) active account to match the workstation with which the user wants to interact. In most cases, each profile will have only one account, and switching the profile will be enough.

// Switch profile
HYPRUserAgent.sharedInstance().switchActiveProfile(profile)
// Switch account (optional in most of the cases)
HYPRUserAgent.sharedInstance().switchActiveUserAccount(account)

Before Starting the Interaction with Workstations

First we need to setup the SDK:

// Enable the authenticators
        HYPRUAFClient.registerAuthenticatorModule(HYPRFingerprintAsm.self)
        HYPRUAFClient.registerAuthenticatorModule(HYPRFaceIDAsm.self)
        HYPRUAFClient.registerAuthenticatorModule(HYPRFaceAsm.self)
        HYPRUAFClient.registerAuthenticatorModule(HYPRPINAsm.self)
               
 // Optional: For sending/receiving HTTP Headers in HYPR SDK calls
        HYPRUserAgent.setCustomHeadersDelegate(self)
        
 // Enable or Disable SSL Pinning
        HYPRUserAgent.setSSLPinningEnabled(false)
        
 // Optional: Enable default AAID Picker UI for UserAgent
        HYPRUserAgent.setAAIDPickerViewEnabled(true)
        
 // Optional: Set AAIDPickerViewController if previous set to true
        let viewController = UIStoryboard(name:"Main", bundle: nil).instantiateViewController(withIdentifier: "PickerViewController")
        HYPRUserAgent.setAAIDPickerViewController(viewController)
        
 // Optional: Set the Face Authenticator Parameters
        HYPRFaceAsm.setTimeout(60000)

To present the HYPR SDK for iOS UI (authenticators and AAIDPicker) we'll need to setup the presenting view controller or parent view controller, as we call it. Depending on your App's implementation it could be done once the entire HYPR SDK for iOS UI will be present at the same view controller; or you may need it to set each time you go to another place - for example, in the viewWillAppear method:

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

Pairing/Registration

Before pairing the computer to your mobile app, it is required to setup the profile, which corresponds to the Relying Party (RP) server and rpAppId. There are two ways to do it:

• License configuration: Using the QR code or PIN, the SDK configures itself; this process includes setting up the RP profile and pairing the first workstation
• Manual configuration: You specify the RP URL and rpAppId; you must pair the workstation explicitly.

License Configuration

Here we pass nil as a key to trigger the QR code scanner presentation by the SDK. Scan the QR code on your workstation client and the process will start.

(As an alternative you can pass the PIN to the SDK as a string; for example, if the user in your app enters it manually.)

// Call the licenseConfiguration method with empty key parameter
HYPRUserAgent.sharedInstance().licenseConfiguration(withKey: nil) { (error) in
    // Error handling goes here
}

After the operation finishes successfully, the user will have the first RP profile and first workstation set.

Manual Configuration

Create and set the profile. This procedure should be executed once per RP server/rpAppId pair. You should execute it more times if the user is going to pair workstations from different rpAppIds/RP servers. In most cases your users will interact with workstations within a single RP server or rpAppId, so you could set it in the App delegate.

// If app profile does not exist, create a new one
if HYPRUserAgent.sharedInstance().activeProfile() == nil {
// Create the profile configuration where you specify the following:
		let profileConfig = HYPRUserAgentProfileConfiguration(rpAppId: "RP App ID here: i.e. HYPRDefaultApplication",
                                                  		rpServerUrl: "Place the RP URL here: i.e. https://9999-pov.hypr.com",
                                                   		 deviceType: "WORKSTATION",
                                          	  rpSSLPinCredentials: nil,// or ssl pin credentials if you have ones and set sslPinning to true in setup
                                               		 additionalData: nil)

// Create the profile with the profile configuration
		let profile = HYPRUserAgentProfile(displayName: "<Your profile name goes here>", configuration: profileConfig, persona: nil, userAccounts: nil)
            
		HYPRUserAgent.sharedInstance().registerProfile(profile!)
}

After the profile is set, pair your first workstation via QR code scanner.

HYPRUserAgent.sharedInstance().registerRemoteDevice(forUser: nil, pinInputType: .qRCodeScan , actionId: "<Your policy name goes here>") { (error) in
    if(error != nil) {
        // Error handling goes here
    } 
}

In both cases the user will be prompted to authenticate via matched authenticators, according to the specified policy. Policies are set on the Control Center for each rpAppId.

❗️

Critical Step

To dictate what authenticators to use during registration, authentication, and deregistration, you must create a policy that specifically requires them. Details are found under Policy Matching.

Both types of registration can be cancelled via the corresponding HYPRUserAgent method calls.

HYPRUserAgent.sharedInstance().cancelLicenseConfiguration { (error) in 
		// Error handling goes here
}

HYPRUserAgent.sharedInstance().cancelRegisterRemoteDevice { (error) in 
		// Error handling goes here
}

Operations

Here are the operations which can be performed on the paired device.

unlock

This operation includes unlock and login (if supported and corresponding settings are turned ON). From the HYPR SDK for iOS perspective, it is the same operation:

HYPRUserAgent.sharedInstance().unlock(workstation) { (error) in 
		// Error handling goes here
}

During this operation the user will be prompted to authenticate according to the registered authenticators and received policy from the server.

Unlock can be cancelled via the corresponding HYPRUserAgent method call.

HYPRUserAgent.sharedInstance().cancelUnlock(workstation, completion: { (error) in
		// Error handling goes here
})

updateRegisteredRemoteDevicesStatuses

When called, this operation will update the status of all workstations belonging to the active user account. You may want to call this method before trying to unlock the workstation. For example, it may be already unlocked, and you want to notify the user accordingly. Check the HYPRUserAgentRemoteDevice.h class in the HYPR SDK for iOS framework for reference.

HYPRUserAgent.sharedInstance().updateRegisteredRemoteDevicesStatuses { (error) in
		// Error handling goes here
}

Local operations

rename and (set as) default don't affect any server or workstation settings.

// Rename the workstation
let updatedWorkstation = HYPRUserAgent.sharedInstance().renameRemoteDevice(workstation, withDisplayName: name)
// Set the workstation as a defaulf for active account
updatedWorksation = HYPRUserAgent.sharedInstance().setRemoteDevice(workstation, default: true)

// Also you can get the active user's default workstation:
let defaultWorkstation = HYPRUserAgent.sharedInstance().defaultRemoteDevice()?

Offline Access

If set properly in the Control Center, users will be able to access (unlock) their workstations without an Internet connection using the offline tokens. To use this functionality they must pair their workstation with an iPhone and perform online unlock/login at least once before going offline to allow HYPR to preemptively cache the credentials.

There are two methods available:

// Getting the offline access info
let workstationOfflineAccessInfo = try? HYPRUserAgent.sharedInstance().offlineAccessInfo(for: workstation) {
    // Present UI with obtained info if needed                    
}

// Getting the offline access token to make user enter it on workstation instead of a password
HYPRUserAgent.sharedInstance().consumeOfflineToken(for: workstations, completion: { (token, info, error) in
		// Error handling, token presentation on UI goes here
}

In the second method, during the consumeOfflineToken operation, the user will be prompted to authenticate according to the registered authenticators and cached policy from the server.

Please also refer to the HYPROfflineAccessInfo.h class in HYPR SDK for iOS.

Deregister/Unpair

To unpair the existing workstation from the iPhone, the method takes an array of the workstation as a parameter.

HYPRUserAgent.sharedInstance().deregister([workstation], completion: { (error) in
		// Error handling goes here            
})

You may want to deregister the entire profile. To do so you must manually create and add it the next time the user wants to pair the workstation, or it will be created automatically via the licenseConfiguration call, as described in the beginning of this article.

HYPRUserAgent.sharedInstance().deregisterProfile(activeProfile) { (error) in
		// Error handling goes here
}

Limit the Number of Workstations

To limit the number of workstations a user can pair, use the following method:

HYPRUserAgent.sharedInstance().setWorkstationsLimit(NSNumber(integerLiteral: 9))