HYPR Passwordless
HYPR SDK for iOS
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
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
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
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))
Updated 15 days ago